;;; pearl.el --- Linear.app integration -*- lexical-binding: t; -*-

;; Copyright (C) 2025
;; Author: Craig Jennings <c@cjennings.net>
;; Based on and inspired by Gael Blanchemain's linear-emacs.
;; Version: 1.0.0
;; Package-Requires: ((emacs "27.1") (request "0.3.0") (dash "2.17.0") (s "1.12.0") (transient "0.3.0"))
;; Keywords: tools
;; URL: https://git.cjennings.net/pearl.git

;; This file is not part of GNU Emacs.

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.

;;; Commentary:

;; pearl integrates Linear.app issue tracking with Emacs and org-mode.
;; Fetch your issues -- open issues, a project, an ad-hoc filter, a Linear
;; Custom View, or a named local view -- into a single self-describing org
;; file: each issue is a heading, its description and comments render in the
;; body, and its structured fields live in a namespaced LINEAR-* drawer.
;;
;; Edit a description or title and push it back with conflict-aware sync; set
;; priority, state, assignee, or labels by command; add comments; and create
;; or delete issues -- all without leaving Emacs.  See README.org for the full
;; command surface and configuration.

;;; Code:

;;
;; This file is organized into the following sections:
;;
;; - Dependencies and requirements
;; - Customization and variables
;; - Core API functions (async-first)
;; - Team management functions
;; - Issue management functions
;; - Issue state management functions
;; - Org-mode integration functions
;; - Mapping functions (between Linear and org-mode)
;; - User-facing commands
;; - Org-mode sync hooks
;; - Backward compatibility functions
;;

;; Dependencies
(require 'request)
(require 'json)
(require 'dash)
(require 's)
(require 'org)
(require 'cl-lib)
(require 'transient)
(require 'auth-source)

;;; Customization and Variables
(defgroup pearl nil
  "Integration with Linear issue tracking."
  :group 'tools
  :prefix "pearl-")

(defcustom pearl-api-key nil
  "API key for Linear.app.
Can be set manually or loaded from LINEAR_API_KEY environment variable
using `pearl-load-api-key-from-env'."
  :type 'string
  :group 'pearl)

(defcustom pearl-graphql-url "https://api.linear.app/graphql"
  "GraphQL endpoint URL for Linear API."
  :type 'string
  :group 'pearl)

(defcustom pearl-default-team-id nil
  "Default team ID to use for creating issues.
When set, skips team selection prompt when creating new issues."
  :type 'string
  :group 'pearl)

(defcustom pearl-debug nil
  "Enable debug logging for Linear requests.
When enabled, detailed API request and response information will be
logged to the *Messages* buffer."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory)
  "Path to the org file where Linear issues are stored.
This file is created or updated by `pearl-list-issues'.
Defaults to \\='gtd/linear.org\\=' in your `org-directory'."
  :type 'file
  :group 'pearl)

(defcustom pearl-accounts nil
  "Named Linear accounts for multi-workspace use.
An alist of (NAME . PLIST) where NAME is a string and PLIST carries the
per-workspace settings:

  :api-key-source  how the key is *found* (not the key itself), a tagged
                   list -- one of (:auth-source :host H :user U),
                   (:env \"VAR\"), or (:literal \"lin_...\").
  :org-file        the account's active org file (`~' is expanded).
  :default-team-id default team for new issues; optional.
  :default-view    local-view name `pearl-open-default-view' opens for this
                   account, or nil for my open issues; optional.
  :url             GraphQL endpoint; optional, defaults to
                   `pearl-graphql-url'.

Leave nil for legacy single-account behavior off the standalone
`pearl-api-key' / `pearl-org-file-path' globals.  See
`pearl-switch-account' and `pearl-default-account'."
  :type '(alist :key-type string :value-type plist)
  :group 'pearl)

(defcustom pearl-default-account nil
  "Name of the account `pearl-active-account' resolves to at first need.
A durable preference (unlike the runtime `pearl-active-account').  When
`pearl-accounts' is set and no account is active yet, the first command that
needs account context resolves this name; if it is nil, that command errors
asking the user to set it or run `pearl-switch-account'."
  :type '(choice (const :tag "None" nil) string)
  :group 'pearl)

(defcustom pearl-async-default t
  "Use async API calls by default.
When t, all API calls will be asynchronous unless explicitly overridden.
Set to nil to use synchronous calls by default for backward compatibility."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-progress-messages t
  "Show progress messages during long operations.
When enabled, displays messages about ongoing API operations."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-max-issue-pages 10
  "Maximum number of issue pages to fetch, at 100 issues per page.
`pearl-list-issues' stops after this many pages and warns that the
result may be truncated.  Raise it if you are assigned more issues than
this cap can hold."
  :type 'integer
  :group 'pearl)

(defcustom pearl-request-timeout 30
  "Seconds a synchronous Linear request waits before giving up.
The synchronous wrappers busy-wait for their async counterpart to call
back.  If it never does (dropped connection, server stall), they return
nil after this many seconds rather than hanging Emacs."
  :type 'number
  :group 'pearl)

(defcustom pearl-surface-buffer t
  "When non-nil, surface the active org buffer after a command updates it.
A command run while the buffer is buried (its async result lands after you have
navigated away) brings the buffer back to a window so the result is visible.
Set to nil to leave window layout untouched."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-surface-select-window nil
  "When non-nil, surfacing the active buffer also selects its window.
With the default nil, `pearl-surface-buffer' shows the buffer via
`display-buffer' without moving focus.  Set non-nil to have focus follow
\(via `pop-to-buffer') so point lands in the surfaced buffer."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-compose-window-side 'bottom
  "Side of the frame Pearl's compose and conflict buffers open from.
One of `bottom', `top', `left', or `right'.  Pearl always applies this side
window when popping a compose buffer, overriding any `display-buffer-alist'
entry for those buffers."
  :type '(choice (const bottom) (const top) (const left) (const right))
  :group 'pearl)

(defcustom pearl-compose-window-size 0.3
  "Size of Pearl's compose and conflict side window.
A float below 1 is a fraction of the frame (0.3 = 30%); an integer is an
absolute size in lines (for `bottom'/`top') or columns (for `left'/`right').
Paired with `pearl-compose-window-side'."
  :type 'number
  :group 'pearl)

(defun pearl--compose-display-action ()
  "Return the `display-buffer' action for a compose or conflict buffer.
A side window on `pearl-compose-window-side', sized by
`pearl-compose-window-size' -- `window-width' for the left/right sides,
`window-height' for top/bottom."
  (cons '(display-buffer-in-side-window)
        (list (cons 'side pearl-compose-window-side)
              (cons (if (memq pearl-compose-window-side '(left right))
                        'window-width
                      'window-height)
                    pearl-compose-window-size))))

(defun pearl--surface-buffer (buffer)
  "Bring BUFFER to a window after a command updated it, unless already shown.
No-op when `pearl-surface-buffer' is nil, BUFFER is dead, or BUFFER is already
visible in some window (so the common already-on-screen case causes no window
churn).  Uses `pop-to-buffer' when `pearl-surface-select-window' is non-nil
\(focus follows) and `display-buffer' otherwise (shown without stealing focus)."
  (when (and pearl-surface-buffer
             (buffer-live-p buffer)
             (not (get-buffer-window buffer t)))
    (if pearl-surface-select-window
        (pop-to-buffer buffer)
      (display-buffer buffer))))

(defcustom pearl-fold-after-update t
  "When non-nil, re-fold the Linear page after a fetch or refresh repopulates it.
`#+STARTUP:' visibility only applies on a file's first visit, so a repopulation
that replaces a visited buffer's contents in place would otherwise leave the
page fully expanded.  Folding restores the scannable outline -- issue headings
visible, descriptions, comments, and property drawers hidden.  Set to nil to
leave the buffer expanded after updates."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-help-header t
  "When non-nil, render a folded \"* Pearl Help\" 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-hide-preamble t
  "When non-nil, collapse the `#+' keyword preamble to a one-line summary.
A display overlay replaces the `#+' block atop each Linear file with a styled
\"Pearl - <view> · <count> · <time>\" line in `pearl-preamble-summary' face.
The buffer text is untouched, so refresh and parsing still work; the overlay
only governs display.  Set to nil to show the raw `#+' keyword lines."
  :type 'boolean
  :group 'pearl)

(defface pearl-preamble-summary
  '((t :inherit org-document-title :foreground "goldenrod"))
  "Face for the one-line summary that replaces the hidden `#+' preamble block.
Inherits `org-document-title' for the large title look; override via Customize
\(e.g. a different colour for a light theme)."
  :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
the buffer mirrors what you would see opening the issue in Linear itself.
Set this to t for opt-in tidying — it capitalizes each word for a neater
outline, keeping minor words (articles, short conjunctions and prepositions)
lowercase unless they are first or last, and leaving words that already
contain an uppercase letter (acronyms like API, identifiers, camelCase)
untouched.  Display-only either way: the title's provenance hash is taken over
the rendered form, so an unedited title is still a no-op on sync and is never
rewritten on Linear."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-show-identifier-in-heading t
  "When non-nil, prefix the issue heading title with the Linear identifier.
For example `** TODO [#B] SE-401: Fix the bug'.  Display-only: title sync
strips the `IDENT: ' prefix before hashing and pushing, so the identifier
never leaks into the title on Linear.  Set to nil to omit the prefix."
  :type 'boolean
  :group 'pearl)

(defconst pearl--title-case-minor-words
  '("a" "an" "and" "as" "at" "but" "by" "for" "if" "in" "nor" "of" "on" "or"
    "per" "the" "to" "vs" "via")
  "Words kept lowercase by `pearl--title-case' unless first or last.")

(defun pearl--title-case (title)
  "Return TITLE in smart title case.
Each word is capitalized except minor words (see
`pearl--title-case-minor-words') in non-edge positions; a word that already
contains an uppercase letter is left as-is so acronyms and identifiers survive.
Internal whitespace is normalized to single spaces."
  (let* ((words (split-string title))
         (last (1- (length words)))
         (case-fold-search nil))         ; so [[:upper:]] is genuinely upper-only
    (mapconcat
     (lambda (cell)
       (let ((i (car cell)) (w (cdr cell)))
         (cond
          ((string-match-p "[[:upper:]]" w) w)
          ((and (/= i 0) (/= i last)
                (member (downcase w) pearl--title-case-minor-words))
           (downcase w))
          ;; upcase only the first char (not `capitalize', which treats an
          ;; apostrophe/hyphen as a word break: "don't" -> "Don'T")
          ((string-empty-p w) w)
          (t (concat (upcase (substring w 0 1)) (substring w 1))))))
     (let ((i -1)) (mapcar (lambda (w) (cons (cl-incf i) w)) words))
     " ")))

(defun pearl--heading-title (issue)
  "Return the displayed heading title for ISSUE (the form the renderer writes).
Brackets are stripped (they break Org parsing); title case is applied when
`pearl-title-case-headings' is non-nil.  This is the bare title without the
identifier prefix -- the form the title provenance hash is taken over."
  (let ((stripped (replace-regexp-in-string
                   "\\[\\|\\]" "" (or (plist-get issue :title) ""))))
    (if pearl-title-case-headings (pearl--title-case stripped) stripped)))

(defun pearl--heading-with-identifier (display-title identifier)
  "Prefix DISPLAY-TITLE with \"IDENTIFIER: \" when prefixing is enabled.
Returns DISPLAY-TITLE unchanged when `pearl-show-identifier-in-heading' is nil
or IDENTIFIER is empty."
  (if (and pearl-show-identifier-in-heading
           identifier (not (string-empty-p identifier)))
      (format "%s: %s" identifier display-title)
    display-title))

(defun pearl--strip-identifier-prefix (heading identifier)
  "Strip a leading \"IDENTIFIER: \" prefix from HEADING when present.
Returns HEADING unchanged when IDENTIFIER is empty or absent from the front."
  (let ((prefix (and identifier (not (string-empty-p identifier))
                     (concat identifier ": "))))
    (if (and prefix (string-prefix-p prefix heading))
        (substring heading (length prefix))
      heading)))

(defun pearl--hide-all-drawers ()
  "Collapse every property drawer in the current buffer, across Org versions."
  (cond ((fboundp 'org-fold-hide-drawer-all) (org-fold-hide-drawer-all))
        ((fboundp 'org-cycle-hide-drawers) (org-cycle-hide-drawers 'all))))

(defun pearl--hide-or-tidy-drawers ()
  "Hide property drawers in the accessible buffer, honoring org-tidy if active.
With `org-tidy-mode' on, re-tidy via `org-tidy-buffer' so freshly rendered
drawers pick up org-tidy's compact display instead of a plain fold; otherwise
fold them natively.  org-tidy stays an optional soft dependency -- the native
fold is the fallback when it is absent or off."
  (if (and (bound-and-true-p org-tidy-mode) (fboundp 'org-tidy-buffer))
      (org-tidy-buffer)
    (pearl--hide-all-drawers)))

(defun pearl--hide-drawers-in-region (start end)
  "Collapse property drawers between START and END.
Used after inserting a single subtree (a freshly added comment) so its drawer
folds shut like the rest of the page, rather than rendering expanded."
  (save-restriction
    (narrow-to-region start end)
    (pearl--hide-or-tidy-drawers)))

(defun pearl--fold-subtree-at-marker (marker)
  "Fold the subtree at MARKER to outline-only and tidy its drawers.
The subtree's heading stays visible; everything under it (body, drawers,
comment children) is collapsed.  A merge refresh re-renders updated
subtrees and inserts new ones expanded; this folds just those so they
match what the buffer's `#+STARTUP' visibility would have produced,
without touching subtrees the user left expanded.  A nil or dead MARKER
is a silent no-op."
  (when (and marker (marker-buffer marker))
    (save-excursion
      (goto-char marker)
      (org-back-to-heading t)
      (let ((beg (point))
            (end (save-excursion (org-end-of-subtree t t) (point))))
        (cond ((fboundp 'org-fold-subtree) (org-fold-subtree t))
              ((fboundp 'outline-hide-subtree) (outline-hide-subtree)))
        (pearl--hide-drawers-in-region beg end)))))

(defun pearl--fold-touched-subtrees (markers)
  "Fold each subtree at the markers in MARKERS.
Used after `pearl--merge-issues-into-buffer' so the page stays as the
user had it.  Untouched and locally-edited subtrees are left exactly as
they were; only the subtrees the merge actually re-rendered (updated)
or appended (added) come in folded.  A no-op when
`pearl-fold-after-update' is nil."
  (when pearl-fold-after-update
    (dolist (m markers)
      (pearl--fold-subtree-at-marker m))))

(defun pearl--restore-page-visibility ()
  "Re-fold the whole current buffer to its `#+STARTUP' visibility and hide drawers.
Used after a full repopulation (list / view replace path) so the page does
not sprawl open.  A no-op when `pearl-fold-after-update' is nil.  The merge
path uses `pearl--fold-touched-subtrees' instead so an edit-then-merge flow
keeps the user's expanded subtrees visible."
  (when pearl-fold-after-update
    ;; A full in-place rebuild (Branch B / merge) leaves Org's parsed startup
    ;; options stale -- the new `#+STARTUP:' text is in the buffer but
    ;; `org-startup-folded' still holds the value read on first visit.  Re-read
    ;; the options so the fold honors the buffer's actual `#+STARTUP'.
    (when (fboundp 'org-set-regexps-and-options) (org-set-regexps-and-options))
    ;; `org-set-startup-visibility' was renamed in Org 9.6; funcall picks the
    ;; available name without tripping the byte-compiler's obsoletion warning.
    (funcall (if (fboundp 'org-cycle-set-startup-visibility)
                 'org-cycle-set-startup-visibility
               'org-set-startup-visibility))
    (pearl--hide-or-tidy-drawers)))

;; Cache variables

(defvar pearl--cache-teams nil
  "Cache for teams.")

(defvar pearl--cache-states nil
  "Cache of workflow states per team, an alist of (TEAM-ID . STATES).
Populated on first state lookup; clear it to force a refresh.")

(defvar pearl--cache-team-collections nil
  "Cache of per-team collections for name->id resolution.
An alist keyed by (KIND . TEAM-ID) where KIND is one of `projects',
`labels', `members', `cycles'; the value is the list of nodes.  Clear it (or
pass a force argument) to refresh.")

(defvar pearl--cache-views nil
  "Cache of the workspace's Linear Custom Views (a list of node alists).
Populated on first listing; clear it (or pass a force argument) to refresh.")

(defvar pearl--cache-viewer nil
  "Cached current-viewer plist (:id :name), fetched once per session.
Backs the comment-edit permission check; clear it to force a refresh.")

(defvar pearl--cache-org-url-key nil
  "Cached workspace URL key (organization.urlKey), fetched once per session.
Backs `pearl--view-url', which reconstructs a Custom View's web link because
Linear's `CustomView' type exposes no `url' field.  Clear it to force a
refresh.")

;; Progress tracking variables
(defvar pearl--active-requests 0
  "Number of currently active API requests.")

;;; Multi-Account Support

(defvar pearl-active-account nil
  "Name of the Linear account currently active, or nil.
Runtime state, never a persisted defcustom: which account you are on right
now.  `pearl-switch-account' sets it with `setq'; persisting it would make
the last switch stick across sessions and fight `pearl-default-account'.")

(defun pearl--resolve-api-key-source (source account)
  "Resolve SOURCE to an API key string for ACCOUNT (named for error messages).
SOURCE is a tagged list: (:literal KEY), (:env VAR), or
\(:auth-source :host H :user U).  Errors -- naming ACCOUNT, never dumping the
lookup -- when the key cannot be found or SOURCE is malformed."
  (pcase source
    (`(:literal ,key) key)
    (`(:env ,var)
     (or (getenv var)
         (error "No API key for account %s: environment variable %s is unset"
                account var)))
    (`(:auth-source . ,plist)
     (let* ((found (car (apply #'auth-source-search
                               (append plist '(:require (:secret) :max 1)))))
            (secret (and found (plist-get found :secret))))
       (cond
        ((null secret)
         (error "No API key for account %s: auth-source found no matching entry"
                account))
        ((functionp secret) (funcall secret))
        (t secret))))
    (_ (error "No API key for account %s: unrecognized :api-key-source form"
              account))))

(defun pearl--resolve-account (name)
  "Resolve account NAME from `pearl-accounts' to a context plist.
The plist is (:name :api-key :org-file :default-team-id :url) with the key
resolved from `:api-key-source', `:org-file' expanded, and `:url' defaulting
to `pearl-graphql-url'.  Errors when NAME is unknown or its key is missing."
  (let ((spec (cdr (assoc name pearl-accounts))))
    (unless spec
      (error "No Pearl account named %s" name))
    (let ((org-file (plist-get spec :org-file)))
      (list :name name
            :api-key (pearl--resolve-api-key-source
                      (plist-get spec :api-key-source) name)
            :org-file (and org-file (expand-file-name org-file))
            :default-team-id (plist-get spec :default-team-id)
            :default-view (plist-get spec :default-view)
            :url (or (plist-get spec :url) pearl-graphql-url)))))

(defun pearl--current-account-context ()
  "Return the active account's context plist, or nil in legacy single-account mode.
Returns nil when `pearl-accounts' is empty (downstream then reads the legacy
globals unchanged).  Otherwise resolves `pearl-active-account', falling back to
`pearl-default-account' on first need -- which it then records as active.
Errors when accounts are configured but neither is set."
  (when pearl-accounts
    (let ((name (or pearl-active-account
                    pearl-default-account
                    (user-error (concat "Pearl accounts are configured but none is active; "
                                        "set `pearl-default-account' or run "
                                        "`pearl-switch-account'")))))
      (unless pearl-active-account
        (setq pearl-active-account name))
      (pearl--resolve-account name))))

(defvar pearl--account-context nil
  "The account context bound for the current dynamic extent, or nil.
`pearl--with-account-context' binds this so async continuations -- pagination
and render/mutate callbacks -- re-establish the account that was active when
the request was dispatched, rather than reading whatever account happens to be
active when they later run.")

(defmacro pearl--with-account-context (context &rest body)
  "Evaluate BODY with the legacy globals bound to CONTEXT's account values.
CONTEXT is a context plist from `pearl--resolve-account'.  A nil CONTEXT is a
passthrough: BODY runs against the current globals (legacy single-account
mode), so nothing changes when `pearl-accounts' is unset.  Also binds
`pearl--account-context' so a nested async dispatch propagates the same
account into its own callbacks."
  (declare (indent 1) (debug (form body)))
  (let ((ctx (make-symbol "ctx")))
    `(let ((,ctx ,context))
       (if (null ,ctx)
           (progn ,@body)
         (let ((pearl--account-context ,ctx)
               (pearl-api-key (plist-get ,ctx :api-key))
               (pearl-graphql-url (plist-get ,ctx :url))
               (pearl-org-file-path (or (plist-get ,ctx :org-file)
                                        pearl-org-file-path))
               (pearl-default-team-id (plist-get ,ctx :default-team-id)))
           ,@body)))))

(defun pearl--read-buffer-account (&optional buffer)
  "Return the `#+LINEAR-ACCOUNT' name BUFFER carries, or nil.
BUFFER defaults to the current buffer; the search is bounded to the preamble so
it stays cheap on large buffers, matching `pearl--read-active-source'."
  (with-current-buffer (or buffer (current-buffer))
    (save-excursion
      (goto-char (point-min))
      (when (re-search-forward "^#\\+LINEAR-ACCOUNT: \\(.*\\)$" 4000 t)
        (string-trim (match-string 1))))))

(defun pearl--require-account-context (&optional mutation)
  "Guard a current-buffer command against the active Linear account.
Returns the active account's context plist, or nil in legacy single-account
mode (`pearl-accounts' unset), where there is nothing to guard.

Otherwise enforces buffer ownership before any API call:
- buffer owned by the active account -> proceed;
- buffer owned by a *different* configured account -> refuse, naming both, so a
  command can't run under one account against another's file;
- no `#+LINEAR-ACCOUNT' marker and MUTATION non-nil -> refuse until a refresh
  stamps ownership; a non-mutating render/list command proceeds (it will stamp
  ownership on its next write)."
  (when pearl-accounts
    (let* ((ctx (pearl--current-account-context))
           (active (plist-get ctx :name))
           (buffer-account (pearl--read-buffer-account)))
      (cond
       ((and buffer-account (not (string-equal buffer-account active)))
        (user-error (concat "This file belongs to %s; active account is %s.  "
                            "Run M-x pearl-switch-account first")
                    buffer-account active))
       ((and (null buffer-account) mutation)
        (user-error "No LINEAR-ACCOUNT in this file; refresh it under an account first"))
       (t ctx)))))

(defun pearl--ensure-buffer-account-header ()
  "Stamp `#+LINEAR-ACCOUNT' into the current buffer if missing (accounts mode).
A no-op in legacy mode or when the marker is already present.  The merge/refresh
path doesn't rebuild the header through `pearl--build-org-content', so without
this a legacy file (rendered before accounts were configured) would never
acquire ownership -- leaving the buffer guard's \"refresh it under an account
first\" advice unresolvable, since the refresh itself wouldn't stamp it."
  (when (and pearl--account-context
             (not (pearl--read-buffer-account)))
    (save-excursion
      (goto-char (point-min))
      (when (re-search-forward "^#\\+LINEAR-SOURCE:" nil t)
        (beginning-of-line)
        (insert (format "#+LINEAR-ACCOUNT: %s\n"
                        (plist-get pearl--account-context :name)))))))

(defun pearl--clear-account-scoped-state ()
  "Clear every cache scoped to a single Linear workspace.
The one place that lists the account-scoped caches -- the five Linear lookups
plus any future account-derived state -- so a newly added cache is registered
here and `pearl-switch-account' invalidates it without re-implementing cache
semantics.  A personal workspace's teams must never bleed into a work one."
  (setq pearl--cache-teams nil
        pearl--cache-states nil
        pearl--cache-team-collections nil
        pearl--cache-views nil
        pearl--cache-viewer nil
        pearl--cache-org-url-key nil))

(defun pearl--mode-line-lighter ()
  "Return the `pearl-mode' mode-line lighter, naming the active account.
\" Pearl[work]\" when accounts are configured and one is active; plain
\" Pearl\" in legacy single-account mode."
  (if (and pearl-accounts pearl-active-account)
      (format " Pearl[%s]" pearl-active-account)
    " Pearl"))

(defun pearl-switch-account (name)
  "Switch the active Linear account to NAME.
Interactively, completes over the configured `pearl-accounts'.  Resolves the
account (erroring on an unknown name or missing key), makes it active, clears
the account-scoped caches so the next lookup refetches against the new
workspace, refreshes the mode-line indicator, and visits the account's org file
when it exists."
  (interactive
   (list (if (null pearl-accounts)
             (user-error "No accounts configured; set `pearl-accounts' first")
           (completing-read "Switch to account: "
                            (mapcar #'car pearl-accounts) nil t))))
  (let ((ctx (pearl--resolve-account name)))
    (setq pearl-active-account name)
    (pearl--clear-account-scoped-state)
    (force-mode-line-update t)
    (let ((file (plist-get ctx :org-file)))
      (if (and file (file-exists-p file))
          (progn (find-file file)
                 (message "Switched to account %s" name))
        (message "Switched to account %s (no org file yet; run a fetch)" name)))))

;;; Core API Functions (Async-First Architecture)

(defun pearl--headers ()
  "Return headers for Linear API requests."
  (unless pearl-api-key
    (error "Linear API key not set.  Use M-x customize-variable RET pearl-api-key"))

  ;; For personal API keys, the format is: "Authorization: <API_KEY>"
  ;; No "Bearer" prefix for personal API keys
  `(("Content-Type" . "application/json")
    ("Authorization" . ,pearl-api-key)))

(defun pearl--log (format-string &rest args)
  "Log message with FORMAT-STRING and ARGS if debug is enabled."
  (when pearl-debug
    (apply #'message (concat "[Linear] " format-string) args)))

(defun pearl--progress (format-string &rest args)
  "Show a progress message built from FORMAT-STRING and ARGS.
Shown only when `pearl-progress-messages' is non-nil."
  (when pearl-progress-messages
    (apply #'message (concat "[Linear] " format-string) args)))

(defun pearl--wait-for (predicate)
  "Busy-wait until PREDICATE is non-nil or the request timeout elapses.
Return the final value of PREDICATE: non-nil when it succeeded, nil when
the wait timed out after `pearl-request-timeout' seconds.  This
keeps the synchronous wrappers from hanging Emacs when a callback never
fires."
  (let ((deadline (+ (float-time) pearl-request-timeout)))
    (while (and (not (funcall predicate))
                (< (float-time) deadline))
      (sleep-for 0.1))
    (funcall predicate)))

(defun pearl--graphql-request-async (query &optional variables success-fn error-fn)
  "Make an asynchronous GraphQL request to Linear API.
QUERY is the GraphQL query string.
VARIABLES is an optional alist of variables to include in the request.
SUCCESS-FN is called with the response data on success.
ERROR-FN is called with error information on failure.
If SUCCESS-FN or ERROR-FN are not provided, default handlers will be used."
  (pearl--log "Making async GraphQL request with query: %s" query)
  (when variables
    (pearl--log "Variables: %s" (prin1-to-string variables)))

  (unless success-fn
    (setq success-fn (lambda (data)
                       (pearl--log "Request completed: %s" (prin1-to-string data)))))

  (unless error-fn
    (setq error-fn (lambda (error-thrown _response data)
                     (message "Linear API error: %s" error-thrown)
                     (pearl--log "Error response: %s" (prin1-to-string data)))))

  ;; Snapshot the account context once, at dispatch.  Reuse the context already
  ;; bound by an enclosing `pearl--with-account-context' (pagination, a wrapping
  ;; command); otherwise resolve the active account now.  The macro binds the
  ;; legacy globals for the synchronous header build and is re-established around
  ;; each callback, so a mid-flight `pearl-switch-account' can't bleed into a
  ;; request that was already dispatched.  In legacy mode (no `pearl-accounts')
  ;; the context is nil and the macro is a passthrough.
  (let ((ctx (or pearl--account-context (pearl--current-account-context))))
    (pearl--with-account-context ctx
      (let ((request-data (json-encode `(("query" . ,query)
                                         ,@(when variables `(("variables" . ,variables))))))
            ;; Build headers before bumping the counter: `pearl--headers' signals
            ;; when the API key is unset, and that must happen before the increment
            ;; or no callback ever runs to decrement it (leaking the count).
            (headers (pearl--headers)))
        (pearl--log "Request payload: %s" request-data)
        (setq pearl--active-requests (1+ pearl--active-requests))

        (request
          pearl-graphql-url
          :type "POST"
          :headers headers
          :data request-data
          :parser 'json-read
          :success (cl-function
                    (lambda (&key data &allow-other-keys)
                      (setq pearl--active-requests (1- pearl--active-requests))
                      (pearl--log "Response received: %s" (prin1-to-string data))
                      (pearl--with-account-context ctx
                        (funcall success-fn data))))
          :error (cl-function
                  (lambda (&key error-thrown response data &allow-other-keys)
                    (setq pearl--active-requests (1- pearl--active-requests))
                    (pearl--log "Error: %s" error-thrown)
                    ;; Guard the status-code read: `response' can be nil on some
                    ;; transport failures, and the accessor errors on a non-struct.
                    (when (request-response-p response)
                      (pearl--log "Response status: %s"
                                         (request-response-status-code response)))
                    (when data
                      (pearl--log "Error response: %s" (prin1-to-string data)))
                    (pearl--with-account-context ctx
                      (funcall error-fn error-thrown response data)))))))))

(defun pearl--graphql-request (query &optional variables)
  "Synchronous wrapper for GraphQL requests (backward compatibility).
QUERY is the GraphQL query string.
VARIABLES is an optional alist of variables.
Returns the response data or nil on error.
This function blocks until the request completes."
  (pearl--log "Making synchronous GraphQL request (backward compatibility mode)")
  (let ((response nil)
        (error-response nil)
        (completed nil))

    (pearl--graphql-request-async
     query
     variables
     (lambda (data)
       (setq response data)
       (setq completed t))
     (lambda (error-thrown _response _data)
       (setq error-response error-thrown)
       (setq completed t)))

    ;; Legacy busy-wait: this wrapper predates `pearl--wait-for' and keeps its
    ;; own hardcoded 30s bound rather than honoring `pearl-request-timeout'.
    (let ((timeout 30)
          (start-time (current-time)))
      (while (and (not completed)
                  (< (float-time (time-subtract (current-time) start-time)) timeout))
        (sleep-for 0.1)))

    (if error-response
        (progn
          (message "Linear API error: %s" error-response)
          nil)
      response)))

;;; Team Management (Async)

(defun pearl-get-teams-async (&optional callback)
  "Asynchronously get a list of teams from Linear.
CALLBACK is called with the list of teams on success."
  (pearl--log "Fetching teams asynchronously")
  (pearl--progress "Fetching teams...")

  ;; Keep the field set in lockstep with `pearl--all-teams': both write the
  ;; same `pearl--cache-teams', so an async populate followed by a sync read
  ;; would leave the cache missing `key' and quietly break callers that filter
  ;; teams by key.
  (let* ((query "query { teams { nodes { id key name } } }")
         (success-fn (lambda (response)
                       (if response
                           (let ((teams (cdr (assoc 'nodes (assoc 'teams (assoc 'data response))))))
                             (pearl--log "Retrieved %d teams" (length teams))
                             (setq pearl--cache-teams teams)
                             (when callback
                               (funcall callback teams)))
                         (message "Failed to retrieve teams")
                         (when callback
                           (funcall callback nil)))))
         (error-fn (lambda (_error _response _data)
                     (message "Failed to retrieve teams")
                     (when callback
                       (funcall callback nil)))))

    (pearl--graphql-request-async query nil success-fn error-fn)))

(defun pearl-get-teams ()
  "Get a list of teams from Linear (synchronous for backward compatibility)."
  (let ((teams nil)
        (completed nil))

    (pearl-get-teams-async
     (lambda (result)
       (setq teams result)
       (setq completed t)))

    (pearl--wait-for (lambda () completed))

    teams))

(defun pearl-select-team-async (callback)
  "Asynchronously prompt user to select a team.
CALLBACK is called with the selected team."
  (if pearl--cache-teams
      ;; Use cached teams
      (let* ((team-names (mapcar (lambda (team)
                                   (cons (cdr (assoc 'name team)) team))
                                 pearl--cache-teams))
             (selected (completing-read "Select team: " team-names nil t)))
        (funcall callback (cdr (assoc selected team-names))))
    ;; Fetch teams first
    (pearl-get-teams-async
     (lambda (teams)
       (if teams
           (let* ((team-names (mapcar (lambda (team)
                                        (cons (cdr (assoc 'name team)) team))
                                      teams))
                  (selected (completing-read "Select team: " team-names nil t)))
             (funcall callback (cdr (assoc selected team-names))))
         (funcall callback nil))))))

(defun pearl-select-team ()
  "Prompt user to select a team (synchronous for backward compatibility)."
  (let ((result nil)
        (completed nil))

    (pearl-select-team-async
     (lambda (team)
       (setq result team)
       (setq completed t)))

    (pearl--wait-for (lambda () completed))

    result))

;;; Issue Filter DSL (Layer 1)

;; A pure compiler from an authoring plist to a Linear `IssueFilter' object (a
;; json-encodable alist passed as the `$filter' variable of an `issues(filter:)'
;; query).  Name->id resolution for `:project' / `:cycle' happens upstream; this
;; layer assumes resolved values and never touches the network.

(defconst pearl--open-state-types '("completed" "canceled" "duplicate")
  "Workflow-state types that count as not open.
`:open t' compiles to a `state.type' nin this list.  Linear's state types are
triage, backlog, unstarted, started, completed, canceled, and duplicate; the
first four are the open ones.")

(defconst pearl--priority-symbols
  '((none . 0) (urgent . 1) (high . 2) (medium . 3) (low . 4))
  "Alist mapping priority symbols to Linear's numeric priority values.")

(defconst pearl--filter-keys
  '(:assignee :assignee-id :open :state :state-type :project :team :labels
    :label-id :priority :cycle :sort :order)
  "Keys recognized in an issue-filter authoring plist.
`:sort' and `:order' steer result ordering, not the `IssueFilter' itself.
`:assignee-id' and `:label-id' are the rename-proof id-based forms used when
resolving a favorite to a filter; the name/email forms (`:assignee', `:labels')
remain for the ad-hoc builder where the user is choosing live.")

(defun pearl--eq (value)
  "Return a Linear comparator alist matching VALUE exactly."
  (list (cons "eq" value)))

(defun pearl--in (values)
  "Return a Linear comparator alist matching any of VALUES.
VALUES is a list, encoded as a JSON array."
  (list (cons "in" (vconcat values))))

(defun pearl--nin (values)
  "Return a Linear comparator alist matching none of VALUES.
VALUES is a list, encoded as a JSON array."
  (list (cons "nin" (vconcat values))))

(defun pearl--compile-priority (priority)
  "Return Linear's numeric value for PRIORITY.
PRIORITY is an integer 0-4 or a symbol in `pearl--priority-symbols'."
  (cond ((integerp priority) priority)
        ((assq priority pearl--priority-symbols)
         (cdr (assq priority pearl--priority-symbols)))
        (t (error "Invalid priority: %S" priority))))

(defun pearl--compile-state-filter (plist)
  "Return the state sub-filter alist for PLIST, or nil when no state key is set.
An explicit `:state' (a name or a list of names) or `:state-type' (one type or
a list) takes precedence over `:open', the broad not-closed predicate."
  (let ((state (plist-get plist :state))
        (state-type (plist-get plist :state-type))
        (open (plist-get plist :open)))
    (cond
     (state (list (cons "name" (if (listp state)
                                   (pearl--in state)
                                 (pearl--eq state)))))
     (state-type (list (cons "type"
                             (pearl--in (if (listp state-type)
                                                   state-type
                                                 (list state-type))))))
     (open (list (cons "type" (pearl--nin pearl--open-state-types))))
     (t nil))))

(defun pearl--build-issue-filter (plist)
  "Compile filter PLIST into a json-encodable Linear `IssueFilter' alist.
The result is meant for the `$filter' variable of an `issues(filter:)' query;
sibling keys are AND-ed by Linear.  This function is pure and assumes
`:project' / `:cycle' values are already resolved ids (see the resolution
helpers for name->id).  Recognized keys are `pearl--filter-keys', minus
the ordering keys `:sort' / `:order'."
  (let (filter)
    (let ((assignee (plist-get plist :assignee)))
      (cond ((eq assignee :me)
             (push (cons "assignee" (list (cons "isMe" (pearl--eq t)))) filter))
            ((stringp assignee)
             (push (cons "assignee" (list (cons "email" (pearl--eq assignee))))
                   filter))))
    (let ((state-filter (pearl--compile-state-filter plist)))
      (when state-filter (push (cons "state" state-filter) filter)))
    (let ((project (plist-get plist :project)))
      (when project
        (push (cons "project" (list (cons "id" (pearl--eq project)))) filter)))
    (let ((team (plist-get plist :team)))
      (when team
        (push (cons "team" (list (cons "key" (pearl--eq team)))) filter)))
    (let ((labels (plist-get plist :labels)))
      ;; v1 semantics: "carries any of these labels" -- labels.some.name in set.
      (when labels
        (push (cons "labels"
                    (list (cons "some" (list (cons "name" (pearl--in labels))))))
              filter)))
    (let ((priority (plist-get plist :priority)))
      (when priority
        (push (cons "priority"
                    (pearl--eq (pearl--compile-priority priority)))
              filter)))
    (let ((cycle (plist-get plist :cycle)))
      (when cycle
        (push (cons "cycle" (list (cons "id" (pearl--eq cycle)))) filter)))
    (let ((assignee-id (plist-get plist :assignee-id)))
      (when assignee-id
        (push (cons "assignee" (list (cons "id" (pearl--eq assignee-id)))) filter)))
    (let ((label-id (plist-get plist :label-id)))
      (when label-id
        (push (cons "labels"
                    (list (cons "some" (list (cons "id" (pearl--in (list label-id)))))))
              filter)))
    (nreverse filter)))

;;; Reverse-compile: Linear filterData -> Pearl authoring plist (copy-down)
;;
;; Linear stores a Custom View's filter as `filterData', a JSON `and'/`or' tree,
;; NOT the flat IssueFilter Pearl's compiler emits.  Copy-down reads it
;; (json-read shaped: symbol-keyed alists, vectors for arrays, t / :json-false /
;; nil for the JSON literals) and reverse-compiles it to a Pearl authoring plist
;; so the copied view is editable.  Contract: normalize-then-match -- flatten the
;; top-level `and', unwrap single-branch `and'/`or', read a one-element `in' as a
;; scalar, then match each conjunct to one authoring key.  Anything Pearl's
;; AND-only, singular-keyed model can't hold refuses with a structured reason.
;; Every helper returns `(ok . VALUE)' or `(refuse . REASON)'.

(defun pearl--rc-refuse (fmt &rest args)
  "Build a structured refusal result `(refuse . REASON)' from FMT and ARGS."
  (cons 'refuse (apply #'format fmt args)))

(defun pearl--rc-unwrap (node)
  "Collapse a single-branch `and'/`or' wrapper in dimension-condition NODE.
When NODE is `((and . [X]))' or `((or . [X]))' with exactly one branch, return X
unwrapped.  A multi-branch wrapper is a real conjunction/disjunction and is
returned as-is for the matcher to refuse.  Other NODEs pass through."
  (let ((wrap (and (consp node) (= 1 (length node))
                   (or (assq 'and node) (assq 'or node)))))
    (if wrap
        (let ((branches (cdr wrap)))
          (if (and (vectorp branches) (= 1 (length branches)))
              (pearl--rc-unwrap (aref branches 0))
            node))
      node)))

(defun pearl--rc-scalar (opnode dim)
  "Extract a singular scalar from operator OPNODE for dimension DIM.
Accepts `eq' or a one-element `in'.  A multi-value `in' or any other operator
refuses -- Pearl's singular keys hold one value, and silently narrowing a
multi-value filter would change which issues match."
  (cond
   ((not (consp opnode)) (pearl--rc-refuse "%s has an unexpected shape" dim))
   ((assq 'eq opnode) (cons 'ok (cdr (assq 'eq opnode))))
   ((assq 'in opnode)
    (let ((v (cdr (assq 'in opnode))))
      (cond
       ((and (vectorp v) (= 1 (length v))) (cons 'ok (aref v 0)))
       ((and (vectorp v) (> (length v) 1))
        (pearl--rc-refuse
         "%s filters on several values; Pearl has no plural key for it" dim))
       (t (pearl--rc-refuse "%s has an empty or malformed `in'" dim)))))
   (t (pearl--rc-refuse
       "%s uses an operator (%s) Pearl can't represent"
       dim (mapconcat (lambda (p) (symbol-name (car p))) opnode "/")))))

(defun pearl--rc-match-assignee (cnode)
  "Match an assignee condition CNODE to an authoring fragment."
  (let ((node (pearl--rc-unwrap cnode)))
    (cond
     ((or (assq 'and node) (assq 'or node))
      (pearl--rc-refuse "assignee uses OR logic Pearl can't represent"))
     ((assq 'isMe node)
      (if (eq (cdr (assq 'eq (cdr (assq 'isMe node)))) t)
          (cons 'ok (list :assignee :me))
        (pearl--rc-refuse "assignee.isMe is negated")))
     ((assq 'id node)
      (let ((r (pearl--rc-scalar (cdr (assq 'id node)) "assignee.id")))
        (if (eq (car r) 'ok) (cons 'ok (list :assignee-id (cdr r))) r)))
     ((assq 'email node)
      (let ((r (pearl--rc-scalar (cdr (assq 'email node)) "assignee.email")))
        (if (eq (car r) 'ok) (cons 'ok (list :assignee (cdr r))) r)))
     (t (pearl--rc-refuse "assignee uses a field Pearl can't represent")))))

(defun pearl--rc-match-state (cnode)
  "Match a state condition CNODE to `:state', `:state-type', or `:open'."
  (let ((node (pearl--rc-unwrap cnode)))
    (cond
     ((or (assq 'and node) (assq 'or node))
      (pearl--rc-refuse "state uses OR logic Pearl can't represent"))
     ((assq 'name node)
      ;; :state is plural-capable (a name or a list), like :state-type:
      ;; name.eq / name.in[one] -> scalar, name.in[many] -> list.
      (let ((op (cdr (assq 'name node))))
        (cond
         ((assq 'eq op) (cons 'ok (list :state (cdr (assq 'eq op)))))
         ((assq 'in op)
          (let ((vals (append (cdr (assq 'in op)) nil)))
            (cond
             ((null vals) (pearl--rc-refuse "state.name has an empty `in'"))
             ((= 1 (length vals)) (cons 'ok (list :state (car vals))))
             (t (cons 'ok (list :state vals))))))
         (t (pearl--rc-refuse "state.name uses an operator Pearl can't represent")))))
     ((assq 'type node)
      (let ((op (cdr (assq 'type node))))
        (cond
         ((assq 'nin op)
          (let ((vals (append (cdr (assq 'nin op)) nil)))
            (if (and (= (length vals) (length pearl--open-state-types))
                     (cl-subsetp vals pearl--open-state-types :test #'string=)
                     (cl-subsetp pearl--open-state-types vals :test #'string=))
                (cons 'ok (list :open t))
              (pearl--rc-refuse
               "state.type uses a `nin' that isn't Pearl's open predicate"))))
         ((assq 'in op)
          (let ((vals (append (cdr (assq 'in op)) nil)))
            (cons 'ok (list :state-type (if (= 1 (length vals)) (car vals) vals)))))
         ((assq 'eq op)
          (cons 'ok (list :state-type (cdr (assq 'eq op)))))
         (t (pearl--rc-refuse "state.type uses an operator Pearl can't represent")))))
     (t (pearl--rc-refuse "state uses a field Pearl can't represent")))))

(defun pearl--rc-match-scalar-dim (cnode field dim authoring-key)
  "Match a single-field scalar dimension (project.id, team.key, cycle.id)."
  (let ((node (pearl--rc-unwrap cnode)))
    (cond
     ((or (assq 'and node) (assq 'or node))
      (pearl--rc-refuse "%s uses OR logic Pearl can't represent" dim))
     ((assq field node)
      (let ((r (pearl--rc-scalar (cdr (assq field node)) dim)))
        (if (eq (car r) 'ok) (cons 'ok (list authoring-key (cdr r))) r)))
     (t (pearl--rc-refuse "%s uses a field Pearl can't represent" dim)))))

(defun pearl--rc-match-labels (cnode)
  "Match a labels condition CNODE to `:labels' (names) or `:label-id' (one id)."
  (let ((node (pearl--rc-unwrap cnode)))
    (cond
     ((or (assq 'every node) (assq 'none node))
      (pearl--rc-refuse "labels uses `every'/`none'; Pearl only does `some'"))
     ((or (assq 'and node) (assq 'or node))
      (pearl--rc-refuse
       "labels uses nested and/or (e.g. a label parent) Pearl can't represent"))
     ((assq 'some node)
      (let ((some (pearl--rc-unwrap (cdr (assq 'some node)))))
        (cond
         ((or (assq 'and some) (assq 'or some))
          (pearl--rc-refuse
           "labels.some uses nested and/or Pearl can't represent"))
         ((assq 'name some)
          (let ((op (cdr (assq 'name some))))
            (if (assq 'in op)
                (cons 'ok (list :labels (append (cdr (assq 'in op)) nil)))
              (let ((r (pearl--rc-scalar op "labels.some.name")))
                (if (eq (car r) 'ok) (cons 'ok (list :labels (list (cdr r)))) r)))))
         ((assq 'id some)
          (let ((r (pearl--rc-scalar (cdr (assq 'id some)) "labels.some.id")))
            (if (eq (car r) 'ok) (cons 'ok (list :label-id (cdr r))) r)))
         (t (pearl--rc-refuse "labels.some uses a field Pearl can't represent")))))
     (t (pearl--rc-refuse "labels uses a shape Pearl can't represent")))))

(defun pearl--rc-match-priority (cnode)
  "Match a priority condition CNODE to canonical numeric `:priority' (0..4)."
  (let ((node (pearl--rc-unwrap cnode)))
    (if (assq 'eq node)
        (let ((n (cdr (assq 'eq node))))
          (if (and (integerp n) (<= 0 n 4))
              (cons 'ok (list :priority n))
            (pearl--rc-refuse "priority %S is outside 0..4" n)))
      (pearl--rc-refuse "priority uses an operator Pearl can't represent"))))

(defun pearl--rc-match-conjunct (conjunct)
  "Match one CONJUNCT (a one-key alist) to an authoring plist fragment."
  (if (or (not (consp conjunct)) (not (= 1 (length conjunct))))
      (pearl--rc-refuse "a filter clause has an unexpected shape")
    (let ((dim (caar conjunct))
          (cnode (cdar conjunct)))
      (pcase dim
        ('assignee (pearl--rc-match-assignee cnode))
        ('state    (pearl--rc-match-state cnode))
        ('project  (pearl--rc-match-scalar-dim cnode 'id "project" :project))
        ('team     (pearl--rc-match-scalar-dim cnode 'key "team" :team))
        ('cycle    (pearl--rc-match-scalar-dim cnode 'id "cycle" :cycle))
        ('labels   (pearl--rc-match-labels cnode))
        ('priority (pearl--rc-match-priority cnode))
        (_ (pearl--rc-refuse
            "filters on `%s', a dimension Pearl can't represent" dim))))))

(defun pearl--rc-conjuncts (filter-data)
  "Return `(ok . CONJUNCTS)' or `(refuse . REASON)' from FILTER-DATA.
Flattens a top-level `and' (the real Linear shape) and the flat sibling-keyed
object Pearl's own compiler emits; refuses a top-level `or' or an empty filter."
  (cond
   ((null filter-data) (pearl--rc-refuse "the Linear view has no filter"))
   ((not (consp filter-data))
    (pearl--rc-refuse "the Linear view filter has an unexpected shape"))
   ((and (assq 'and filter-data) (= 1 (length filter-data)))
    (let ((branches (append (cdr (assq 'and filter-data)) nil)))
      (if branches (cons 'ok branches)
        (pearl--rc-refuse "the Linear view has no filter"))))
   ((and (assq 'or filter-data) (= 1 (length filter-data)))
    (pearl--rc-refuse "the Linear view uses top-level OR logic Pearl can't represent"))
   (t (cons 'ok (mapcar (lambda (pair) (list pair)) filter-data)))))

(defun pearl--reverse-compile-issue-filter (filter-data)
  "Reverse-compile Linear FILTER-DATA (json-read shaped) to an authoring plist.
Returns `(ok . PLIST)' on success, or `(refuse . REASON)' when the view's filter
is outside Pearl's AND-only, singular-keyed authoring model.  The REASON names
the offending construct so the command can tell the user what to do instead."
  (let ((conj (pearl--rc-conjuncts filter-data)))
    (if (eq (car conj) 'refuse) conj
      (catch 'done
        (let ((plist nil))
          (dolist (c (cdr conj))
            (let ((m (pearl--rc-match-conjunct c)))
              (when (eq (car m) 'refuse) (throw 'done m))
              (setq plist (append plist (cdr m)))))
          (cons 'ok plist))))))

(defun pearl--validate-issue-filter (plist)
  "Validate issue-filter PLIST, signaling a `user-error' on any problem.
Return t when PLIST is well-formed.  Checks plist shape, unknown keys, the
`:priority' range/symbol, the `:assignee' form, the `:order' value, empty
strings, and the `:labels' type.  Name ambiguity (a project or state name that
needs team context) is resolved upstream, not here."
  (unless (and (listp plist) (cl-evenp (length plist)))
    (user-error "Issue filter must be a plist"))
  (cl-loop for (key _val) on plist by #'cddr
           unless (memq key pearl--filter-keys)
           do (user-error "Unknown issue-filter key: %S" key))
  (let ((priority (plist-get plist :priority)))
    (when priority
      (cond ((integerp priority)
             (unless (<= 0 priority 4)
               (user-error "Priority integer must be 0-4, got %d" priority)))
            ((not (assq priority pearl--priority-symbols))
             (user-error "Invalid :priority %S (use 0-4 or none/urgent/high/medium/low)"
                         priority)))))
  (let ((assignee (plist-get plist :assignee)))
    (when (and assignee (not (eq assignee :me)) (not (stringp assignee)))
      (user-error ":assignee must be :me or an email string, got %S" assignee)))
  (let ((order (plist-get plist :order)))
    (when (and order (not (memq order '(asc desc))))
      (user-error ":order must be `asc' or `desc', got %S" order)))
  (dolist (key '(:project :team :cycle :assignee-id :label-id))
    (let ((val (plist-get plist key)))
      (when (and (stringp val) (string-empty-p val))
        (user-error "%s must not be an empty string" key))))
  (let ((labels (plist-get plist :labels)))
    (when (and labels
               (or (not (listp labels))
                   (cl-some (lambda (x) (not (and (stringp x) (not (string-empty-p x)))))
                            labels)))
      (user-error ":labels must be a list of non-empty strings")))
  ;; :state is a single name OR a list of non-empty names (mirrors :labels).
  (let ((state (plist-get plist :state)))
    (cond
     ((null state))
     ((stringp state)
      (when (string-empty-p state)
        (user-error ":state must not be an empty string")))
     ((listp state)
      (when (cl-some (lambda (x) (not (and (stringp x) (not (string-empty-p x)))))
                     state)
        (user-error ":state must be a name or a list of non-empty names")))
     (t (user-error ":state must be a name or a list of names, got %S" state))))
  t)

;;; Issue Model Normalization

;; Convert raw Linear response alists (json-read shaped: symbol keys, vectors
;; for arrays, t / `:json-false' booleans, and a missing key for an absent
;; field) into flat internal plists, so rendering, filtering, and command code
;; never has to know the transport shape.

(defun pearl--node-list (connection)
  "Return CONNECTION's nodes as a list.
CONNECTION is an alist with a `nodes' key holding a vector, a list, or nil."
  (let ((nodes (cdr (assoc 'nodes connection))))
    (cond ((vectorp nodes) (append nodes nil))
          ((listp nodes) nodes)
          (t nil))))

(defun pearl--normalize-user (raw)
  "Normalize a Linear user alist RAW to a plist, or nil when RAW is nil."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :name (or (cdr (assoc 'name raw)) (cdr (assoc 'displayName raw)))
          :email (cdr (assoc 'email raw)))))

(defun pearl--normalize-state (raw)
  "Normalize a Linear workflow-state alist RAW to a plist, or nil."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :name (cdr (assoc 'name raw))
          :type (cdr (assoc 'type raw)))))

(defun pearl--normalize-team (raw)
  "Normalize a Linear team alist RAW to a plist, or nil."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :key (cdr (assoc 'key raw))
          :name (cdr (assoc 'name raw)))))

(defun pearl--normalize-project (raw)
  "Normalize a Linear project alist RAW to a plist, or nil."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :name (cdr (assoc 'name raw)))))

(defun pearl--normalize-labels (raw)
  "Normalize an issue's labels connection RAW to a list of (:id :name) plists."
  (mapcar (lambda (label)
            (list :id (cdr (assoc 'id label)) :name (cdr (assoc 'name label))))
          (pearl--node-list raw)))

;;; Favorites layer (spec: docs/issue-sources-spec.org)

(defun pearl--favorite-entity-id (node entity-key)
  "Pick ENTITY-KEY's id from favorite NODE, or nil if absent."
  (cdr (assoc 'id (cdr (assoc entity-key node)))))

(defun pearl--normalize-favorite (node)
  "Normalize a Linear Favorite NODE alist to a typed plist for dispatch.
Returns (:kind KIND :title T :url U :sort-order N :id ID [:identifier IDENT]).
KIND is one of `view', `project', `cycle', `label', `user', `team', `issue',
`document', `dashboard', or `other' (a favorite type Pearl cannot dispatch into
a list source).  For an issue favorite, `:identifier' carries the human key
like ENG-1; everything else carries only `:id'.  =label= and =projectLabel=
both normalize to `:kind label' so the dispatch collapses them."
  (let* ((type (cdr (assoc 'type node)))
         (title (or (cdr (assoc 'title node)) ""))
         (url (cdr (assoc 'url node)))
         (sort-order (cdr (assoc 'sortOrder node)))
         (kind+id
          (pcase type
            ("customView"   (cons 'view      (pearl--favorite-entity-id node 'customView)))
            ("project"      (cons 'project   (pearl--favorite-entity-id node 'project)))
            ("cycle"        (cons 'cycle     (pearl--favorite-entity-id node 'cycle)))
            ("label"        (cons 'label     (pearl--favorite-entity-id node 'label)))
            ("projectLabel" (cons 'label     (pearl--favorite-entity-id node 'projectLabel)))
            ("user"         (cons 'user      (pearl--favorite-entity-id node 'user)))
            ("team"         (cons 'team      (pearl--favorite-entity-id node 'team)))
            ("issue"        (cons 'issue     (pearl--favorite-entity-id node 'issue)))
            ("document"     (cons 'document  (pearl--favorite-entity-id node 'document)))
            ("dashboard"    (cons 'dashboard (pearl--favorite-entity-id node 'dashboard)))
            (_              (cons 'other     nil))))
         (base (list :kind (car kind+id) :title title :url url
                     :sort-order sort-order :id (cdr kind+id))))
    (if (eq (car kind+id) 'issue)
        (append base (list :identifier
                           (cdr (assoc 'identifier (cdr (assoc 'issue node))))))
      base)))

(defun pearl--favorite->source (fav)
  "Resolve a normalized FAV into a runnable source plist for the existing
query/render path, or a browser action `(:browser t :url U :title T :kind K)'
when the favorite is not a list source in v1 (issue / team / document /
dashboard / other)."
  (let ((kind (plist-get fav :kind))
        (title (plist-get fav :title))
        (url (plist-get fav :url))
        (id (plist-get fav :id)))
    (pcase kind
      ('view    (list :type 'view :name title :id id :url url))
      ('project (list :type 'filter :name title
                      :filter (list :project id :open t)))
      ('cycle   (list :type 'filter :name title
                      :filter (list :cycle id :open t)))
      ('label   (list :type 'filter :name title
                      :filter (list :label-id id :open t)))
      ('user    (list :type 'filter :name title
                      :filter (list :assignee-id id :open t)))
      (_ (list :browser t :url url :title title :kind kind)))))

(defconst pearl--favorites-query
  "query Favorites($after: String) {
  favorites(first: 100, after: $after) {
    nodes { id type title url sortOrder
            customView { id } project { id } cycle { id }
            label { id } user { id } issue { id identifier }
            team { id } projectLabel { id } document { id } dashboard { id } }
    pageInfo { hasNextPage endCursor } } }"
  "GraphQL query for the viewer's favorites; paged with first/after.")

(defun pearl--favorites-async (callback)
  "Fetch the viewer's favorites and call CALLBACK with a list of normalized
favorite plists (Linear sort-order preserved).  Paged via first/after; on a
transport/GraphQL error, CALLBACK receives whatever was collected so far so the
picker can fall back to local views rather than hanging."
  (let (acc)
    (cl-labels
        ((collect (data)
           (let* ((favs (cdr (assoc 'favorites (cdr (assoc 'data data)))))
                  (nodes (append (cdr (assoc 'nodes favs)) nil))
                  (page (cdr (assoc 'pageInfo favs))))
             (dolist (n nodes)
               (push (pearl--normalize-favorite n) acc))
             (if (eq (cdr (assoc 'hasNextPage page)) t)
                 (pearl--graphql-request-async
                  pearl--favorites-query
                  (list (cons "after" (cdr (assoc 'endCursor page))))
                  #'collect
                  (lambda (&rest _) (funcall callback (nreverse acc))))
               (funcall callback (nreverse acc))))))
      (pearl--graphql-request-async
       pearl--favorites-query nil #'collect
       (lambda (&rest _)
         ;; HP5: a fetch error is not "no favorites" -- message it so the
         ;; picker's fallback to local views doesn't masquerade as success.
         (message "Pearl: favorites fetch failed; showing local views only")
         (funcall callback (nreverse acc)))))))

(defun pearl--normalize-comment (raw)
  "Normalize a Linear comment alist RAW to a plist.
The author falls back through user, then botActor, then externalUser, because
`Comment.user' is null for integration and bot comments."
  (let ((user (pearl--normalize-user (cdr (assoc 'user raw))))
        (bot (cdr (assoc 'botActor raw)))
        (ext (cdr (assoc 'externalUser raw))))
    (list :id (cdr (assoc 'id raw))
          :body (cdr (assoc 'body raw))
          :created-at (cdr (assoc 'createdAt raw))
          :author-id (when user (plist-get user :id))
          :author (cond (user (plist-get user :name))
                        (bot (or (cdr (assoc 'name bot)) "automation"))
                        (ext (or (cdr (assoc 'name ext)) "external"))
                        (t nil)))))

(defun pearl--normalize-cycle (raw)
  "Normalize a Linear cycle alist RAW to a plist, or nil."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :number (cdr (assoc 'number raw))
          :name (cdr (assoc 'name raw)))))

(defun pearl--normalize-issue (raw)
  "Normalize a Linear issue node RAW to a flat internal plist, or nil.
Vectors become lists and absent/`:json-false' fields become nil.  Nested
objects (state, assignee, team, project, labels, cycle, comments) are
normalized in turn; comments are omitted unless the fetch requested them."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :identifier (cdr (assoc 'identifier raw))
          :title (cdr (assoc 'title raw))
          :description (cdr (assoc 'description raw))
          :priority (cdr (assoc 'priority raw))
          :url (cdr (assoc 'url raw))
          :updated-at (cdr (assoc 'updatedAt raw))
          :state (pearl--normalize-state (cdr (assoc 'state raw)))
          :assignee (pearl--normalize-user (cdr (assoc 'assignee raw)))
          :team (pearl--normalize-team (cdr (assoc 'team raw)))
          :project (pearl--normalize-project (cdr (assoc 'project raw)))
          :labels (pearl--normalize-labels (cdr (assoc 'labels raw)))
          :cycle (pearl--normalize-cycle (cdr (assoc 'cycle raw)))
          :comments (let ((comments (assoc 'comments raw)))
                      (when comments
                        (mapcar #'pearl--normalize-comment
                                (pearl--node-list (cdr comments))))))))

(defun pearl--normalize-custom-view (raw)
  "Normalize a Linear custom-view alist RAW to a plist, or nil.
A workspace-wide view has a nil `:team'; `:shared' is a real boolean."
  (when raw
    (list :id (cdr (assoc 'id raw))
          :name (cdr (assoc 'name raw))
          :description (cdr (assoc 'description raw))
          :shared (eq t (cdr (assoc 'shared raw)))
          :icon (cdr (assoc 'icon raw))
          :color (cdr (assoc 'color raw))
          :team (pearl--normalize-team (cdr (assoc 'team raw)))
          :owner (pearl--normalize-user (cdr (assoc 'owner raw))))))

;;; Query Result Shape

;; A small tagged result so callers can tell apart success-with-issues,
;; success-with-none, an invalid filter (caught before the request), a
;; transport failure, and a GraphQL-level failure, instead of collapsing them
;; all to nil.  A result is a plist: (:status SYM :issues LIST :message STR
;; :truncated BOOL).  The fetch layer builds one; commands read it to message
;; the user precisely.

(defun pearl--make-query-result (status &rest props)
  "Build a query-result plist with STATUS and optional PROPS.
STATUS is one of `ok', `empty', `invalid-filter', `request-failed', or
`graphql-failed'.  PROPS may set `:issues', `:message', and `:truncated'."
  (append (list :status status) props))

(defun pearl--query-result-status (result)
  "Return the status symbol of query RESULT."
  (plist-get result :status))

(defun pearl--query-result-issues (result)
  "Return the issues list carried by query RESULT."
  (plist-get result :issues))

(defun pearl--query-result-message (result)
  "Return the user-facing message carried by query RESULT, if any."
  (plist-get result :message))

(defun pearl--query-result-truncated-p (result)
  "Return non-nil when query RESULT was cut off at the page cap."
  (plist-get result :truncated))

(defun pearl--query-result-ok-p (result)
  "Return non-nil when RESULT is a successful query (issues or empty)."
  (memq (pearl--query-result-status result) '(ok empty)))

(defun pearl--query-result-error-p (result)
  "Return non-nil when RESULT is a failure rather than a result set."
  (memq (pearl--query-result-status result)
        '(invalid-filter request-failed graphql-failed)))

(defun pearl--graphql-error-message (response)
  "Return the first GraphQL error message in RESPONSE, or nil.
RESPONSE's `errors' may be a vector (live API) or a list (test fixtures)."
  (let ((errors (cdr (assoc 'errors response))))
    (when errors
      (let ((first (if (vectorp errors)
                       (and (> (length errors) 0) (aref errors 0))
                     (car errors))))
        (cdr (assoc 'message first))))))

(defun pearl--classify-response (response &optional issues truncated)
  "Classify a raw GraphQL RESPONSE into a query-result plist.
A nil RESPONSE, or one without a `data' key, is a transport failure; a RESPONSE
carrying `errors' is a GraphQL failure.  Otherwise the result is `ok', or
`empty' when ISSUES is empty, carrying ISSUES and the TRUNCATED flag.  ISSUES
is the already-extracted (normalized) list, so this stays pure."
  (cond
   ((null response)
    (pearl--make-query-result 'request-failed
                                     :message "No response from Linear"))
   ((assoc 'errors response)
    (pearl--make-query-result
     'graphql-failed
     :message (or (pearl--graphql-error-message response)
                  "Linear returned an error")))
   ((not (assoc 'data response))
    (pearl--make-query-result 'request-failed
                                     :message "Malformed response from Linear"))
   (t (pearl--make-query-result (if issues 'ok 'empty)
                                       :issues issues
                                       :truncated (and truncated t)))))

(defun pearl--invalid-filter-result (message)
  "Return an `invalid-filter' query-result carrying MESSAGE."
  (pearl--make-query-result 'invalid-filter :message message))

;;; General Issue Query (Layer 2a)

;; The general fetch: a top-level `issues(filter:)' query paged through a
;; reusable accumulator, returning a tagged query-result.  Issues come back as
;; raw nodes (the query fetches the full field superset); normalization happens
;; at the render boundary, not here.

(defcustom pearl-fetch-comments-in-list t
  "When non-nil, the bulk list and Custom View fetch each issue's recent comments.
A populated list then renders the latest few comments per issue with a
`shown/total' marker on the Comments heading, instead of looking like
nothing has comments.  Set to nil to keep the list fetch light (comments load
only on a single-issue refresh)."
  :type 'boolean
  :group 'pearl)

(defcustom pearl-list-comments-shown 5
  "How many of an issue's most recent comments render in the bulk list.
The single-issue refresh always shows the full thread; this caps only the
list/view view.  See `pearl-fetch-comments-in-list'."
  :type 'integer
  :group 'pearl)

(defcustom pearl-list-comments-count-cap 25
  "Ceiling for the exact comment total shown in the bulk list marker.
The fetch pulls one more than this so the marker can show an exact total up to
the cap (`5/18') and a `+' beyond it (`5/25+').  A higher cap means an
exact count for busier issues at the cost of a larger fetch."
  :type 'integer
  :group 'pearl)

(defconst pearl--comment-node-fields
  "id body createdAt user { id name displayName } botActor { name } externalUser { name }"
  "The comment node field selection shared by every query that pulls comments.")

(defun pearl--list-comments-fragment ()
  "Return the GraphQL comments fragment for the bulk/view list, or empty string.
Fetches one more than `pearl-list-comments-count-cap', newest first, so the
renderer can show an exact total up to the cap and a `+' beyond it.  Empty when
`pearl-fetch-comments-in-list' is nil, so the list fetch stays light."
  (if pearl-fetch-comments-in-list
      (format "comments(first: %d, orderBy: createdAt) { nodes { %s } }"
              (1+ pearl-list-comments-count-cap)
              pearl--comment-node-fields)
    ""))

(defun pearl--issues-query ()
  "GraphQL query for a filtered, ordered page of issues.
Pulls each issue's recent comments (see `pearl--list-comments-fragment') so a
populated list renders them, not just the single-issue refresh."
  (format "query Issues($filter: IssueFilter, $first: Int!, $after: String, $orderBy: PaginationOrderBy) {
  issues(filter: $filter, first: $first, after: $after, orderBy: $orderBy) {
    nodes {
      id identifier title description priority url updatedAt
      state { id name type }
      assignee { id name displayName email }
      team { id key name }
      project { id name }
      labels { nodes { id name } }
      cycle { id number name }
      %s
    }
    pageInfo { hasNextPage endCursor }
  }
}" (pearl--list-comments-fragment)))

(defconst pearl--single-issue-query
  "query Issue($id: String!) {
  issue(id: $id) {
    id identifier title description priority url updatedAt
    state { id name type }
    assignee { id name displayName email }
    team { id key name }
    project { id name }
    labels { nodes { id name } }
    cycle { id number name }
    comments { nodes { id body createdAt user { id name displayName } botActor { name } externalUser { name } } }
  }
}"
  "GraphQL query for one issue by id.
The single-issue refresh path: pulls the full comment thread uncapped (unlike
the bulk list, which caps via `pearl--list-comments-fragment').")

(defun pearl--fetch-issue-async (issue-id callback)
  "Fetch the full issue node for ISSUE-ID, calling CALLBACK with the outcome.
CALLBACK receives one of: the raw issue node (normalized at the render
boundary, as on the list path); `:missing' when the request succeeded but the
issue is null (deleted, or no access); or `:error' on a GraphQL or transport
failure.  Separating missing from error lets the caller tell \"the issue is
gone\" apart from \"the API call failed.\""
  (pearl--graphql-request-async
   pearl--single-issue-query
   `(("id" . ,issue-id))
   (lambda (response)
     (if (or (null response)
             (assoc 'errors response)
             (not (assoc 'data response)))
         (funcall callback :error)
       (let ((issue (cdr (assoc 'issue (cdr (assoc 'data response))))))
         (funcall callback (or issue :missing)))))
   (lambda (_error _response _data) (funcall callback :error))))

(defconst pearl--default-issue-sort
  (vector '(("updatedAt" ("order" . "Descending"))))
  "Fallback issue sort for a Custom View whose configured ordering pearl can't
reproduce: most-recently-updated first, matching the default `pearl-list-issues'
uses.  Keeps a view from falling through to Linear's createdAt-desc API default,
which reads as random next to the rest of pearl.")

(defconst pearl--view-sortable-orderings
  '("priority" "estimate" "title" "label" "slaStatus" "createdAt" "updatedAt"
    "completedAt" "dueDate" "accumulatedStateUpdatedAt" "cycle" "milestone"
    "assignee" "project" "team" "manual" "workflowState")
  "Linear `viewOrdering' values that also exist as `IssueSortInput' keys, so
pearl can reproduce the view's sort server-side.  An ordering outside this set
falls back to `pearl--default-issue-sort'.")

(defun pearl--view-sort-arg (ordering direction)
  "Translate a Custom View's ORDERING and DIRECTION into an `IssueSortInput' list.
ORDERING is Linear's `viewOrdering' string; DIRECTION is `viewOrderingDirection'
(\"asc\", \"desc\", or nil).  Returns a one-element vector usable as the `sort'
query variable, or nil when ORDERING isn't one pearl can reproduce -- the caller
then falls back to `pearl--default-issue-sort'.  A nil DIRECTION defaults to
Descending, the field's natural order and what Linear's UI shows when no
direction is set."
  (when (member ordering pearl--view-sortable-orderings)
    (let ((order (if (equal direction "asc") "Ascending" "Descending")))
      (vector (list (cons ordering (list (cons "order" order))))))))

(defun pearl--view-issues-query ()
  "GraphQL query running a Custom View's own filter server-side, by view id.
Pulls each issue's recent comments (see `pearl--list-comments-fragment') so a
view-populated list renders them.  The `sort' variable orders the issues; see
`pearl--view-sort-arg' and `pearl--default-issue-sort'."
  (format "query ViewIssues($id: String!, $first: Int!, $after: String, $sort: [IssueSortInput!]) {
  customView(id: $id) {
    issues(first: $first, after: $after, sort: $sort) {
      nodes {
        id identifier title description priority url updatedAt
        state { id name type }
        assignee { id name displayName email }
        team { id key name }
        project { id name }
        labels { nodes { id name } }
        cycle { id number name }
        %s
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}" (pearl--list-comments-fragment)))

(defun pearl--query-view-async (view-id callback &optional sort)
  "Run the Custom View VIEW-ID server-side, calling CALLBACK with a query-result.
The view applies its own stored filter on Linear's side; issues come back as
raw nodes (normalized at the render boundary), paged like the general fetch.
SORT is an `IssueSortInput' list (the `sort' variable); when nil the view runs
under `pearl--default-issue-sort' so its order matches the rest of pearl rather
than Linear's createdAt-desc API default."
  (let* ((sort (or sort pearl--default-issue-sort))
         (page-fn
         (lambda (after page-cb)
           (pearl--graphql-request-async
            (pearl--view-issues-query)
            `(("id" . ,view-id)
              ("first" . 100)
              ("sort" . ,sort)
              ,@(when after (list (cons "after" after))))
            (lambda (response)
              (if (or (null response)
                      (assoc 'errors response)
                      (not (assoc 'data response)))
                  (funcall page-cb
                           (list :error (pearl--classify-response response)))
                (let* ((conn (cdr (assoc 'issues
                                        (cdr (assoc 'customView
                                                    (cdr (assoc 'data response)))))))
                       (nodes (pearl--node-list conn))
                       (info (cdr (assoc 'pageInfo conn))))
                  (funcall page-cb
                           (list :issues nodes
                                 :has-next-page (eq t (cdr (assoc 'hasNextPage info)))
                                 :end-cursor (cdr (assoc 'endCursor info)))))))
            (lambda (_error _response _data)
              (funcall page-cb
                       (list :error (pearl--make-query-result
                                     'request-failed
                                     :message "Failed to fetch view issues"))))))))
    (pearl--page-issues page-fn callback)))

(defconst pearl--linear-web-base "https://linear.app"
  "Base URL of the Linear web app, used to build Custom View links.
Distinct from `pearl-graphql-url' (the API endpoint): a view's web URL is
\"<base>/<workspace-url-key>/view/<view-id>\".")

(defun pearl--custom-views-query ()
  "GraphQL query listing the workspace's Custom Views.
Selects no `url' -- Linear's `CustomView' type has none, and requesting it
400s the whole query (see `pearl--view-url' for how the link is rebuilt)."
  "query CustomViews($first: Int!, $after: String) {
  customViews(first: $first, after: $after) {
  nodes { id name description shared team { id }
          viewPreferencesValues { viewOrdering viewOrderingDirection } }
  pageInfo { hasNextPage endCursor }
  }
  }")

(defun pearl--custom-views (&optional force)
  "Return the workspace's Custom Views, fetching once and caching.
Each node carries id/name/description/shared/team plus viewPreferencesValues
(the configured ordering, read by `pearl--view-sort-arg').  A non-nil FORCE
refetches."
  (or (and (not force) pearl--cache-views)
      (let* ((response (pearl--graphql-request (pearl--custom-views-query)
                                               '(("first" . 100))))
             (views (and response
                         (pearl--node-list
                          (cdr (assoc 'customViews (cdr (assoc 'data response))))))))
        (when views
          (setq pearl--cache-views views))
        views)))

(defun pearl--org-url-key (&optional force)
  "Return the workspace URL key (organization.urlKey), fetching once and caching.
A non-nil FORCE refetches.  Returns nil when the lookup fails, so callers that
build links degrade rather than emit a broken URL."
  (or (and (not force) pearl--cache-org-url-key)
      ;; Best-effort: a missing key or transient failure yields nil so a link
      ;; rebuild degrades rather than throwing -- notably, so a urlKey hiccup
      ;; right after a successful publish can't abort the record step and
      ;; orphan the freshly-created view.
      (let* ((response (ignore-errors
                         (pearl--graphql-request "query { organization { urlKey } }")))
             (url-key (cdr (assoc 'urlKey
                                  (cdr (assoc 'organization
                                              (cdr (assoc 'data response))))))))
        (when (and url-key (not (string-empty-p url-key)))
          (setq pearl--cache-org-url-key url-key)))))

(defun pearl--view-url (view-id)
  "Build the Linear web URL for the Custom View VIEW-ID, or nil when unknown.
Linear's `CustomView' type exposes no `url' field, so the link is rebuilt from
the workspace URL key and the view id -- the same shape Linear's own favorite
URLs carry (the full view UUID, not the slug id).  Returns nil when VIEW-ID is
empty or the workspace URL key is unavailable, so callers degrade instead of
emitting a malformed link."
  (let ((url-key (pearl--org-url-key)))
    (when (and view-id (not (string-empty-p view-id)) url-key)
      (format "%s/%s/view/%s" pearl--linear-web-base url-key view-id))))

(defconst pearl--customview-payload-fields "id name shared team { id key name }"
  "Field selection for a `CustomView' returned by the create/update mutations.
Selects no `url' -- the type has none, and requesting it 400s the mutation; the
link is rebuilt by `pearl--view-url' from the returned id.")

(defun pearl--customview-create-async (name team-id shared filter-data callback)
  "Create a Custom View on Linear.
NAME is the view name.  TEAM-ID is the team UUID or nil for a personal/
workspace view.  SHARED is t or nil.  FILTER-DATA is a compiled
`IssueFilter' alist (see `pearl--build-issue-filter') -- Linear's
`CustomViewCreateInput.filterData' accepts the same shape the issues
query takes.  CALLBACK is invoked with a plist
`(:success BOOL :view ALIST-OR-NIL :error STRING-OR-NIL)'."
  (let* ((query (format "mutation CustomViewCreate($input: CustomViewCreateInput!) {
  customViewCreate(input: $input) {
    success
    customView { %s }
  }
}" pearl--customview-payload-fields))
         (input (append (list (cons "name" name)
                              (cons "shared" (if shared t :json-false))
                              (cons "filterData" filter-data))
                        (when team-id (list (cons "teamId" team-id)))))
         (variables `(("input" . ,input)))
         (success-fn
          (lambda (response)
            (let* ((cvc (cdr (assoc 'customViewCreate
                                    (cdr (assoc 'data response)))))
                   (success (eq t (cdr (assoc 'success cvc))))
                   (view (cdr (assoc 'customView cvc))))
              (funcall callback
                       (list :success (and success (not (null view)))
                             :view view)))))
         (error-fn
          (lambda (error _response _data)
            (funcall callback
                     (list :success nil
                           :error (format "%s" error))))))
    (pearl--graphql-request-async query variables success-fn error-fn)))

(defun pearl--customview-delete-async (view-id callback)
  "Delete a Custom View on Linear by VIEW-ID.
CALLBACK is invoked with a plist
`(:success BOOL :error STRING-OR-NIL)'.  Linear's `customViewDelete' is
a soft delete that drops the view into the workspace trash (recoverable
within Linear's standard window)."
  (let* ((query "mutation CustomViewDelete($id: String!) {
  customViewDelete(id: $id) {
    success
  }
}")
         (variables `(("id" . ,view-id)))
         (success-fn
          (lambda (response)
            (let* ((cvd (cdr (assoc 'customViewDelete
                                    (cdr (assoc 'data response)))))
                   (success (eq t (cdr (assoc 'success cvd)))))
              (funcall callback (list :success success)))))
         (error-fn
          (lambda (error _response _data)
            (funcall callback
                     (list :success nil
                           :error (format "%s" error))))))
    (pearl--graphql-request-async query variables success-fn error-fn)))

(defun pearl--customview-update-async (view-id update-input callback)
  "Update a Custom View on Linear by VIEW-ID.
UPDATE-INPUT is an alist of `CustomViewUpdateInput' fields -- any subset
of `name', `shared', `filterData', `teamId'.  CALLBACK is invoked with a
plist `(:success BOOL :view ALIST-OR-NIL :error STRING-OR-NIL)'."
  (let* ((query (format "mutation CustomViewUpdate($id: String!, $input: CustomViewUpdateInput!) {
  customViewUpdate(id: $id, input: $input) {
    success
    customView { %s }
  }
}" pearl--customview-payload-fields))
         (variables `(("id" . ,view-id)
                      ("input" . ,update-input)))
         (success-fn
          (lambda (response)
            (let* ((cvu (cdr (assoc 'customViewUpdate
                                    (cdr (assoc 'data response)))))
                   (success (eq t (cdr (assoc 'success cvu))))
                   (view (cdr (assoc 'customView cvu))))
              (funcall callback
                       (list :success (and success (not (null view)))
                             :view view)))))
         (error-fn
          (lambda (error _response _data)
            (funcall callback
                     (list :success nil
                           :error (format "%s" error))))))
    (pearl--graphql-request-async query variables success-fn error-fn)))

(defun pearl--page-issues (page-fn callback &optional max-pages)
  "Accumulate issues across pages via PAGE-FN, then call CALLBACK with a result.
PAGE-FN is called as (PAGE-FN AFTER PAGE-CB); it fetches one page and invokes
PAGE-CB with a plist (:issues LIST :has-next-page BOOL :end-cursor STR) on
success, or (:error RESULT) carrying a failure query-result.  CALLBACK receives
the final query-result.  Paging stops at MAX-PAGES (default
`pearl-max-issue-pages'), marking the result truncated."
  (let ((max (or max-pages pearl-max-issue-pages))
        (acc '())
        (page 1))
    (cl-labels
        ((fetch (after)
           (if (> page max)
               (funcall callback
                        (pearl--make-query-result (if acc 'ok 'empty)
                                                         :issues acc :truncated t))
             (funcall
              page-fn after
              (lambda (page-result)
                (let ((err (plist-get page-result :error)))
                  (if err
                      (funcall callback err)
                    (setq acc (append acc (plist-get page-result :issues)))
                    (if (plist-get page-result :has-next-page)
                        (progn
                          (setq page (1+ page))
                          (fetch (plist-get page-result :end-cursor)))
                      (funcall callback
                               (pearl--make-query-result
                                (if acc 'ok 'empty) :issues acc))))))))))
      (fetch nil))))

(defun pearl--query-issues-async (filter callback &optional order-by)
  "Fetch issues matching FILTER, calling CALLBACK with a query-result.
FILTER is a compiled `IssueFilter' alist (see
`pearl--build-issue-filter') or nil for no filter.  ORDER-BY is a
`PaginationOrderBy' symbol, default `updatedAt'.  Issues come back as raw
nodes; normalization happens at the render boundary."
  (let ((page-fn
         (lambda (after page-cb)
           (pearl--graphql-request-async
            (pearl--issues-query)
            `(,@(when filter (list (cons "filter" filter)))
              ("first" . 100)
              ,@(when after (list (cons "after" after)))
              ("orderBy" . ,(symbol-name (or order-by 'updatedAt))))
            (lambda (response)
              (if (or (null response)
                      (assoc 'errors response)
                      (not (assoc 'data response)))
                  (funcall page-cb
                           (list :error (pearl--classify-response response)))
                (let* ((conn (cdr (assoc 'issues (cdr (assoc 'data response)))))
                       (nodes (pearl--node-list conn))
                       (info (cdr (assoc 'pageInfo conn))))
                  (funcall page-cb
                           (list :issues nodes
                                 :has-next-page (eq t (cdr (assoc 'hasNextPage info)))
                                 :end-cursor (cdr (assoc 'endCursor info)))))))
            (lambda (_error _response _data)
              (funcall page-cb
                       (list :error (pearl--make-query-result
                                     'request-failed
                                     :message "Failed to fetch issues from Linear"))))))))
    (pearl--page-issues page-fn callback)))

;;; Issue Creation

(defun pearl--created-issue (response)
  "Return the created issue node from a create RESPONSE, or nil on failure.
Linear answers GraphQL-level failures with HTTP 200 and either an `errors'
body or `issueCreate.success' = false / `issue' = null.  Checking `success'
and the issue node here reports those as failures instead of a phantom
\"created\" issue."
  (let* ((issue-create (cdr (assoc 'issueCreate (cdr (assoc 'data response)))))
         (success (cdr (assoc 'success issue-create)))
         (issue (cdr (assoc 'issue issue-create))))
    (and success (not (eq success :json-false)) issue)))

(defun pearl-create-issue-async (title description team-id callback)
  "Asynchronously create a new issue.
TITLE is the issue title.
DESCRIPTION is the issue description.
TEAM-ID is the team to create the issue in.
CALLBACK is called with the created issue data."
  (pearl--log "Creating issue: %s" title)
  (pearl--progress "Creating issue...")

  (let* ((query "mutation CreateIssue($title: String!, $description: String, $teamId: String!) {
  issueCreate(input: {title: $title, description: $description, teamId: $teamId}) {
  success
  issue {
  id
  identifier
  title
  }
  }
  }")
         (variables `(("title" . ,title)
                      ("description" . ,description)
                      ("teamId" . ,team-id)))

         (success-fn (lambda (response)
                       (let ((issue (pearl--created-issue response)))
                         (if issue
                             (progn
                               (message "Created issue %s: %s"
                                        (cdr (assoc 'identifier issue))
                                        (cdr (assoc 'title issue)))
                               (when callback
                                 (funcall callback issue)))
                           (message "Failed to create issue")
                           (when callback
                             (funcall callback nil))))))

         (error-fn (lambda (_error _response _data)
                     (message "Failed to create issue")
                     (when callback
                       (funcall callback nil)))))

    (pearl--graphql-request-async query variables success-fn error-fn)))

(defun pearl--create-issue (title description team-id)
  "Create a new issue (synchronous wrapper for backward compatibility).
TITLE is the issue title.
DESCRIPTION is the issue description.
TEAM-ID is the team to create the issue in."
  (let ((issue nil)
        (completed nil))

    (pearl-create-issue-async
     title description team-id
     (lambda (result)
       (setq issue result)
       (setq completed t)))

    (pearl--wait-for (lambda () completed))

    issue))

;;; Issue State Management (Async)

(defun pearl-get-states-async (team-id callback)
  "Asynchronously get workflow states for TEAM-ID.
CALLBACK is called with the list of states."
  (pearl--log "Fetching workflow states for team %s" team-id)

  (let* ((query "query GetWorkflowStates($teamId: String!) {
  team(id: $teamId) {
  states {
  nodes {
  id
  name
  color
  }
  }
  }
  }")
         (variables `(("teamId" . ,team-id)))

         (success-fn (lambda (response)
                       (when response
                         (let ((states (cdr (assoc 'nodes (assoc 'states (assoc 'team (assoc 'data response)))))))
                           (when callback
                             (funcall callback states))))))

         (error-fn (lambda (_error _response _data)
                     (when callback
                       (funcall callback nil)))))

    (pearl--graphql-request-async query variables success-fn error-fn)))

(defun pearl-get-states (team-id)
  "Get workflow states for TEAM-ID (synchronous wrapper)."
  (let ((states nil)
        (completed nil))

    (pearl-get-states-async
     team-id
     (lambda (result)
       (setq states result)
       (setq completed t)))

    (pearl--wait-for (lambda () completed))

    states))

(defun pearl--team-states (team-id)
  "Return the workflow states for TEAM-ID, fetching once and caching.
Cached in `pearl--cache-states' keyed by TEAM-ID; org-state syncs
resolve a state per heading change, so the cache avoids a network round
trip on every one.  Clear the cache to force a refresh."
  (or (cdr (assoc team-id pearl--cache-states))
      (let* ((query "query GetTeamWorkflowStates($teamId: String!) {
  team(id: $teamId) {
  states {
  nodes {
  id
  name
  type
  position
  }
  }
  }
  }")
             (variables `(("teamId" . ,team-id)))
             (response (pearl--graphql-request query variables))
             (states (and response
                          (cdr (assoc 'nodes
                                      (cdr (assoc 'states
                                                  (cdr (assoc 'team
                                                              (cdr (assoc 'data response)))))))))))
        (when states
          (push (cons team-id states) pearl--cache-states))
        states)))

(defun pearl--get-state-id-by-name (state-name team-id)
  "Get the Linear state ID for the given STATE-NAME in TEAM-ID."
  (pearl--log "Looking up state ID for %s in team %s" state-name team-id)
  (let* ((states (pearl--team-states team-id))
         (state (and states
                     (seq-find (lambda (s)
                                 (string= (downcase (cdr (assoc 'name s)))
                                          (downcase state-name)))
                               states))))
    (if state
        (cdr (assoc 'id state))
      (message "Could not find state with name: %s in team %s" state-name team-id)
      nil)))

(defun pearl--all-teams ()
  "Return all teams, fetching once and caching in `pearl--cache-teams'.
The whole-file org sync resolves a team per heading, so caching here turns
N blocking lookups into one.  Shares the cache with the team selector.
`key' is fetched alongside `id' and `name' because the filter compiler
keys teams by `team.key.eq', so callers that need to map a stored filter
back to a team need the key handy."
  (or pearl--cache-teams
      (let* ((query "query {
  teams {
  nodes {
  id
  key
  name
  }
  }
  }")
             (response (pearl--graphql-request query))
             (teams (and response
                         (cdr (assoc 'nodes
                                     (cdr (assoc 'teams
                                                 (cdr (assoc 'data response)))))))))
        (when teams
          (setq pearl--cache-teams teams))
        teams)))

(defun pearl--get-team-id-by-name (team-name)
  "Get the Linear team ID for the given TEAM-NAME."
  (pearl--log "Looking up team ID for team %s" team-name)
  (let* ((teams (pearl--all-teams))
         (team (and teams
                    (seq-find (lambda (tm)
                                (string= (cdr (assoc 'name tm)) team-name))
                              teams))))
    (if team
        (cdr (assoc 'id team))
      ;; Log the available teams to help diagnose a name mismatch.
      (when teams
        (pearl--log "Available teams: %s"
                           (mapconcat (lambda (tm)
                                        (format "%s (%s)"
                                                (cdr (assoc 'name tm))
                                                (cdr (assoc 'id tm))))
                                      teams
                                      ", ")))
      (message "Could not find team with name: %s" team-name)
      nil)))

;;; Per-team Name -> ID Resolution

(defun pearl--team-collection (kind team-id &optional force)
  "Return the KIND collection for TEAM-ID, fetching once and caching.
KIND is one of `projects', `labels', `members', `cycles'.  Cached in
`pearl--cache-team-collections' keyed by (KIND . TEAM-ID); a non-nil
FORCE bypasses the cache and refetches.  Returns a list of node alists."
  (let ((cache-key (cons kind team-id)))
    (if (and (not force) (assoc cache-key pearl--cache-team-collections))
        (cdr (assoc cache-key pearl--cache-team-collections))
      (let* ((fields (pcase kind
                       ('members "id name displayName email")
                       ('cycles "id number name")
                       (_ "id name")))
             (query (format "query TeamCollection($teamId: String!) {
  team(id: $teamId) { %s { nodes { %s } } }
}" (symbol-name kind) fields))
             (response (pearl--graphql-request query `(("teamId" . ,team-id))))
             (coll (cdr (assoc kind (cdr (assoc 'team (cdr (assoc 'data response)))))))
             (nodes (pearl--node-list coll)))
        (when nodes
          (push (cons cache-key nodes) pearl--cache-team-collections))
        nodes))))

(defun pearl--node-label (kind node)
  "Return a human label for NODE of KIND, shown when disambiguating a match."
  (pcase kind
    ('members (or (cdr (assoc 'displayName node))
                  (cdr (assoc 'name node))
                  (cdr (assoc 'email node))))
    ('cycles (or (cdr (assoc 'name node))
                 (let ((n (cdr (assoc 'number node))) ) (and n (number-to-string n)))))
    (_ (cdr (assoc 'name node)))))

(defun pearl--node-matches-name-p (kind node name)
  "Return non-nil when NODE of KIND matches NAME.
Members match name, displayName, or email; cycles match name or number;
everything else matches name.  Comparison is case-insensitive."
  (let ((needle (downcase name)))
    (cl-flet ((eqp (field)
                (let ((v (cdr (assoc field node))))
                  (and (stringp v) (string= (downcase v) needle)))))
      (pcase kind
        ('members (or (eqp 'name) (eqp 'displayName) (eqp 'email)))
        ('cycles (or (eqp 'name)
                     (let ((n (cdr (assoc 'number node))))
                       (and n (string= (number-to-string n) name)))))
        (_ (eqp 'name))))))

(defun pearl--resolve-team-id (kind name team-id &optional force)
  "Resolve NAME to an id within the KIND collection of TEAM-ID, or nil.
Fetches (and caches) the collection via `pearl--team-collection'.  With
a single match, returns its id; with several, prompts the user to pick; with
none, returns nil.  FORCE refreshes the collection cache first."
  (let* ((nodes (pearl--team-collection kind team-id force))
         (matches (seq-filter (lambda (n) (pearl--node-matches-name-p kind n name))
                              nodes)))
    (pcase (length matches)
      (0 nil)
      (1 (cdr (assoc 'id (car matches))))
      (_ (let* ((choices (mapcar (lambda (n)
                                   (cons (format "%s (%s)"
                                                 (pearl--node-label kind n)
                                                 (cdr (assoc 'id n)))
                                         (cdr (assoc 'id n))))
                                 matches))
                (pick (completing-read (format "Multiple matches for %s: " name)
                                       choices nil t)))
           (cdr (assoc pick choices)))))))

;;;###autoload
(defun pearl-clear-cache ()
  "Clear the Linear lookup caches (teams, states, per-team collections, views).
Use after renaming things in Linear, or to force the next lookup to refetch."
  (interactive)
  (pearl--clear-account-scoped-state)
  (message "Linear caches cleared"))

(defun pearl-update-issue-state (issue-id state-name team-id)
  "Update the state of Linear issue with ISSUE-ID to STATE-NAME for TEAM-ID."
  (pearl--log "Updating issue %s state to %s for team %s" issue-id state-name team-id)
  ;; Resolve the state name to an ID first; bail out clearly if the team has
  ;; no such state rather than firing a mutation with a null stateId.
  (let ((state-id (pearl--get-state-id-by-name state-name team-id)))
    (if (null state-id)
        (message "Cannot update issue %s: no Linear state named %s in team %s"
                 issue-id state-name team-id)
      (let* ((query "mutation UpdateIssueState($issueId: String!, $stateId: String!) {
  issueUpdate(id: $issueId, input: {stateId: $stateId}) {
  success
  issue {
  id
  identifier
  state {
  id
  name
  }
  }
  }
  }")
             (variables `(("issueId" . ,issue-id)
                          ("stateId" . ,state-id)))
             (response (pearl--graphql-request query variables)))
        (if response
            (let ((success (and (assoc 'data response)
                                (assoc 'issueUpdate (assoc 'data response))
                                (cdr (assoc 'success (assoc 'issueUpdate (assoc 'data response)))))))
              (if success
                  (message "Updated issue %s state to %s" issue-id state-name)
                (pearl--log "Failed to update issue state: %s" (prin1-to-string response))
                (message "Failed to update issue %s state" issue-id)))
          (message "Failed to update issue %s state: API error" issue-id))))))

;;; Team Member and Project Management

(defun pearl-get-team-members (team-id)
  "Get members for the given TEAM-ID."
  (pearl--log "Fetching team members for team %s" team-id)
  (let* ((query "query GetTeamMembers($teamId: String!) {
  team(id: $teamId) {
  members {
  nodes {
  id
  name
  displayName
  }
  }
  }
  }")
         (variables `(("teamId" . ,team-id)))
         (response (pearl--graphql-request query variables)))
    (when response
      (let ((members (cdr (assoc 'nodes (assoc 'members (assoc 'team (assoc 'data response)))))))
        (pearl--log "Retrieved %d team members" (length members))
        (let ((formatted-members
               (mapcar (lambda (member)
                         (cons (or (cdr (assoc 'displayName member))
                                   (cdr (assoc 'name member)))
                               (cdr (assoc 'id member))))
                       members)))
          (pearl--log "Formatted team members: %s" (prin1-to-string formatted-members))
          formatted-members)))))

(defun pearl-get-projects (team-id)
  "Get a list of projects for the given TEAM-ID."
  (pearl--log "Fetching projects for team %s" team-id)
  (let* ((query "query GetProjects($teamId: String!) {
  team(id: $teamId) {
    projects {
      nodes {
        id
        name
        description
        state
      }
    }
  }
}")
         (variables `(("teamId" . ,team-id)))
         (response (pearl--graphql-request query variables)))
    (when response
      (let ((projects (cdr (assoc 'nodes (assoc 'projects (assoc 'team (assoc 'data response)))))))
        ;; Convert vector to list if needed
        (when (vectorp projects)
          (setq projects (append projects nil)))
        (pearl--log "Retrieved %d projects" (length projects))
        projects))))

(defun pearl-select-project (team-id)
  "Prompt user to select a project from TEAM-ID."
  (let* ((projects (pearl-get-projects team-id))
         (project-names (when projects
                          (mapcar (lambda (project)
                                    (cons (cdr (assoc 'name project)) project))
                                  projects)))
         (selected (when project-names
                     (completing-read "Select project (optional): "
                                      (cons "None" project-names) nil t nil nil "None"))))
    ;; Guard the nil case explicitly: a team with no projects (or a failed
    ;; fetch) leaves SELECTED nil, so only consult the choice when one was made.
    (when (and selected (not (string= selected "None")))
      (cdr (assoc selected project-names)))))

;;; Other Issue Attributes

(defun pearl-get-priorities ()
  "Get priority options for Linear issues."
  ;; Linear uses integers for priorities: 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low)
  '(("No priority" . 0)
    ("Urgent" . 1)
    ("High" . 2)
    ("Medium" . 3)
    ("Low" . 4)))

(defun pearl-get-issue-types (team-id)
  "Get issue types for the given TEAM-ID."
  (pearl--log "Fetching issue types for team %s" team-id)
  (let* ((query "query GetIssueTypes($teamId: String!) {
  team(id: $teamId) {
  labels {
  nodes {
  id
  name
  color
  }
  }
  }
  }")
         (variables `(("teamId" . ,team-id)))
         (response (pearl--graphql-request query variables)))
    (when response
      (let ((labels (cdr (assoc 'nodes (assoc 'labels (assoc 'team (assoc 'data response)))))))
        (mapcar (lambda (label)
                  (cons (cdr (assoc 'name label))
                        (cdr (assoc 'id label))))
                labels)))))

;;; Org Mode Integration

(defun pearl--extract-org-heading-properties ()
  "Extract Linear issue properties from the org entry at point.
Returns a plist with :todo-state, :issue-id, :issue-identifier, and :team-id,
read from the entry's LINEAR-* property drawer via org APIs.  Works from
anywhere inside the entry and at any heading depth, and reads by property name
rather than scanning lines, so body text or nested sub-entries don't confuse
it.  Returns nil when point is not within a heading; the id fields are nil for
a non-issue heading.  The team id is read directly from `LINEAR-TEAM-ID', so
there is no network lookup here."
  (save-excursion
    (when (ignore-errors (org-back-to-heading t) t)
      (list :todo-state (org-get-todo-state)
            :issue-id (org-entry-get nil "LINEAR-ID")
            :issue-identifier (org-entry-get nil "LINEAR-IDENTIFIER")
            :team-id (org-entry-get nil "LINEAR-TEAM-ID")))))


;;; Mapping Functions

(defun pearl--state-name-to-keyword (name)
  "Slugify a Linear state NAME to an Org TODO keyword.
Upcased, each run of non-alphanumerics replaced by a single hyphen (alnum is
Unicode-aware, so accented and non-Latin letters survive), with leading and
trailing hyphens trimmed.  An all-symbol name (empty slug) falls back to
\"TODO\".  This is the workspace-faithful replacement for the former static
state-name-to-keyword mapping."
  (let ((slug (string-trim
               (replace-regexp-in-string "[^[:alnum:]]+" "-" (upcase (or name "")))
               "-+" "-+")))
    (if (string-empty-p slug) "TODO" slug)))

(defun pearl--label-name-to-tag (name)
  "Slugify a Linear label NAME to an Org tag.
Downcased, each run of characters outside [[:alnum:]_] replaced by a single
underscore (alnum is Unicode-aware, so accented and non-Latin letters survive),
with leading and trailing underscores trimmed.  Org tags allow no hyphens or
spaces, unlike the TODO keywords `pearl--state-name-to-keyword' builds.  A name
that slugifies to empty (all punctuation) returns the empty string; the caller
drops it from the heading and keeps it in the `:LINEAR-LABELS:' drawer."
  (string-trim
   (replace-regexp-in-string "[^[:alnum:]_]+" "_" (downcase (or name "")))
   "_+" "_+"))

(defun pearl--label-tags (labels)
  "Return the ordered, de-duplicated Org tags for a list of LABEL plists.
Each label's `:name' is slugified via `pearl--label-name-to-tag'; empty slugs
are dropped and duplicates removed, first occurrence winning, so two label
names that slugify to the same tag render it once at the first's position."
  (let ((seen (make-hash-table :test 'equal))
        (tags '()))
    (dolist (label labels)
      (let ((tag (pearl--label-name-to-tag (plist-get label :name))))
        (unless (or (string-empty-p tag) (gethash tag seen))
          (puthash tag t seen)
          (push tag tags))))
    (nreverse tags)))

(defun pearl--derive-todo-line (states)
  "Build the `#+TODO:' keyword string from an ordered STATES list.
Each state is a plist with at least :name and :type.  States whose :type is
completed / canceled / duplicate go after the `|' (the done side); the rest go
before it.  The caller's order is preserved within each side; keywords are
slugified (`pearl--state-name-to-keyword') and de-duplicated by slug, first-seen
winning.  An empty STATES list returns the hardcoded default so the rendered
file always has a valid `#+TODO:' line."
  (if (null states)
      "TODO IN-PROGRESS IN-REVIEW BACKLOG BLOCKED | DONE"
    (let ((active '()) (done '()) (seen (make-hash-table :test 'equal)))
      (dolist (s states)
        (let ((kw (pearl--state-name-to-keyword (plist-get s :name))))
          (unless (gethash kw seen)
            (puthash kw t seen)
            (if (member (plist-get s :type) '("completed" "canceled" "duplicate"))
                (push kw done)
              (push kw active)))))
      (let ((active-str (string-join (nreverse active) " "))
            (done-str (string-join (nreverse done) " ")))
        (concat active-str " |"
                (if (string-empty-p done-str) "" (concat " " done-str)))))))

(defun pearl--map-linear-priority-to-org (priority-num)
  "Convert Linear PRIORITY-NUM to an Org priority cookie, or \"\" for none.
PRIORITY-NUM is 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low.  None (0), nil, and
any unknown value map to no cookie -- 1:1 with the cookie so a None issue does
not collide with Medium, which the save-model relies on for dirty detection."
  (cond
   ((eq priority-num 1) "[#A]") ; Urgent -> A
   ((eq priority-num 2) "[#B]") ; High -> B
   ((eq priority-num 3) "[#C]") ; Medium -> C
   ((eq priority-num 4) "[#D]") ; Low -> D
   (t "")))                ; None / nil / unknown -> no cookie

(defun pearl--get-linear-priority-name (priority-num)
  "Convert Linear PRIORITY-NUM to a readable name.
PRIORITY-NUM is 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low."
  (cond
   ((eq priority-num 1) "Urgent")
   ((eq priority-num 2) "High")
   ((eq priority-num 3) "Medium")
   ((eq priority-num 4) "Low")
   (t "None")))

(defun pearl--md-emphasis-to-org (s)
  "Convert markdown links / bold / italic in S to Org markup.
S must contain no inline code spans -- those are handled by the caller, which
splits them out so their contents stay verbatim."
  ;; [text](url) -> [[url][text]]
  (setq s (replace-regexp-in-string
           "\\[\\([^]]+\\)\\](\\([^) ]+\\))" "[[\\2][\\1]]" s))
  ;; **bold** -> *bold*
  (setq s (replace-regexp-in-string "\\*\\*\\([^*\n]+?\\)\\*\\*" "*\\1*" s))
  ;; _italic_ -> /italic/, word-bounded so identifiers like foo_bar are left alone
  (setq s (replace-regexp-in-string
           "\\(^\\|[^[:alnum:]_]\\)_\\([^_\n]+?\\)_\\([^[:alnum:]_]\\|$\\)"
           "\\1/\\2/\\3" s))
  s)

(defun pearl--md-line-to-org (line)
  "Convert inline markdown in LINE to Org markup.
Handles links, inline code, bold, and underscore italics; other inline markup
passes through unchanged.  Inline code spans are tokenized first and their
contents kept verbatim, so markdown-looking text in backticks (`**b**`,
`[l](u)`) renders as code rather than being converted."
  (let ((result "")
        (pos 0))
    (while (string-match "`\\([^`\n]+\\)`" line pos)
      ;; emphasis/links on the text before this code span, then the span verbatim
      (setq result (concat result
                           (pearl--md-emphasis-to-org
                            (substring line pos (match-beginning 0)))
                           "~" (match-string 1 line) "~"))
      (setq pos (match-end 0)))
    (concat result (pearl--md-emphasis-to-org (substring line pos)))))

(defun pearl--md-to-org (md)
  "Convert markdown MD to Org markup (the pure-elisp conversion tier).
Converts fenced code blocks to `#+begin_src'/`#+end_src', markdown headings to
bold lines (never Org headings), markdown bullets (`*' / `+') to `-', and the
inline markup in `pearl--md-line-to-org'.  Any other line that would
read as an Org heading is space-guarded.  Tables, HTML, and unrecognized
constructs pass through as literal text.  Returns the empty string for an empty
MD."
  (if (or (null md) (string-empty-p md))
      ""
    (let ((in-code nil) (out '()))
      (dolist (line (split-string md "\n"))
        (cond
         ;; fenced code fence: ``` or ```lang
         ((string-match "\\`[ \t]*```\\(.*\\)\\'" line)
          (if in-code
              (progn (push "#+end_src" out) (setq in-code nil))
            (push (format "#+begin_src %s" (string-trim (match-string 1 line))) out)
            (setq in-code t)))
         (in-code (push line out))
         ;; markdown heading -> bold line, not an Org heading
         ((string-match "\\`#+[ \t]+\\(.*\\)\\'" line)
          (push (format "*%s*" (string-trim (match-string 1 line))) out))
         ;; markdown bullet -> Org dash bullet
         ((string-match "\\`\\([ \t]*\\)[*+][ \t]+\\(.*\\)\\'" line)
          (push (concat (match-string 1 line) "- "
                        (pearl--md-line-to-org (match-string 2 line)))
                out))
         ;; guard any remaining line that Org would read as a heading
         ((string-match "\\`\\*+ " line)
          (push (concat " " (pearl--md-line-to-org line)) out))
         (t (push (pearl--md-line-to-org line) out))))
      (string-join (nreverse out) "\n"))))

(defun pearl--org-emphasis-to-md (s)
  "Convert Org links / bold / italic in S back to markdown.
S must contain no verbatim ~code~ spans -- the caller splits those out so their
contents stay literal.  Italics are word-bounded so paths and URLs are left
alone."
  ;; [[url][text]] -> [text](url)
  (setq s (replace-regexp-in-string
           "\\[\\[\\([^]]+\\)\\]\\[\\([^]]+\\)\\]\\]" "[\\2](\\1)" s))
  ;; [[url]] -> url
  (setq s (replace-regexp-in-string "\\[\\[\\([^]]+\\)\\]\\]" "\\1" s))
  ;; *bold* -> **bold**
  (setq s (replace-regexp-in-string "\\*\\([^*\n]+?\\)\\*" "**\\1**" s))
  ;; /italic/ -> _italic_, word-bounded so /usr/local paths are left alone
  (setq s (replace-regexp-in-string
           "\\(^\\|[^[:alnum:]/]\\)/\\([^/\n]+?\\)/\\([^[:alnum:]/]\\|$\\)"
           "\\1_\\2_\\3" s))
  s)

(defun pearl--org-line-to-md (line)
  "Convert inline Org markup in LINE back to markdown.
The inverse of `pearl--md-line-to-org': org links, verbatim, bold, and italics
become their markdown forms.  Verbatim ~code~ spans are tokenized first and
their contents kept literal (symmetric with the md->org direction), so a code
span containing markup round-trips exactly."
  (let ((result "")
        (pos 0))
    (while (string-match "~\\([^~\n]+\\)~" line pos)
      (setq result (concat result
                           (pearl--org-emphasis-to-md
                            (substring line pos (match-beginning 0)))
                           "`" (match-string 1 line) "`"))
      (setq pos (match-end 0)))
    (concat result (pearl--org-emphasis-to-md (substring line pos)))))

(defun pearl--org-to-md (org)
  "Convert Org markup ORG back to markdown (the push direction).
The symmetric inverse of `pearl--md-to-org': `#+begin_src'/`#+end_src'
become fenced code (language preserved, contents verbatim), `#+begin_quote'
blocks become `>'-prefixed lines, Org checkbox marks normalize to markdown
lowercase, and the inline markup in `pearl--org-line-to-md' is undone.
Tables, HTML, and unrecognized lines pass through literally.  Returns the
empty string for an empty ORG.

Two constructs are intentionally lossy and do not round-trip back to their
markdown source: a markdown `# heading' (rendered to a bold line on fetch)
stays a bold line, and single-asterisk markdown italics are unsupported on
fetch.  Both are documented in the conversion matrix."
  (if (or (null org) (string-empty-p org))
      ""
    (let ((in-code nil) (in-quote nil) (out '()))
      (dolist (line (split-string org "\n"))
        (cond
         ;; src block open: #+begin_src or #+begin_src lang
         ((string-match "\\`[ \t]*#\\+begin_src\\(.*\\)\\'" line)
          (push (format "```%s" (string-trim (match-string 1 line))) out)
          (setq in-code t))
         ((and in-code (string-match "\\`[ \t]*#\\+end_src[ \t]*\\'" line))
          (push "```" out) (setq in-code nil))
         (in-code (push line out))
         ;; quote block: drop the markers, prefix the contents with "> "
         ((string-match "\\`[ \t]*#\\+begin_quote[ \t]*\\'" line)
          (setq in-quote t))
         ((and in-quote (string-match "\\`[ \t]*#\\+end_quote[ \t]*\\'" line))
          (setq in-quote nil))
         (in-quote (push (concat "> " (pearl--org-line-to-md line)) out))
         ;; checkbox: normalize the uppercase Org mark to markdown lowercase
         ((string-match "\\`\\([ \t]*\\)- \\[\\([ xX]\\)\\] \\(.*\\)\\'" line)
          (push (concat (match-string 1 line)
                        "- [" (downcase (match-string 2 line)) "] "
                        (pearl--org-line-to-md (match-string 3 line)))
                out))
         (t (push (pearl--org-line-to-md line) out))))
      (string-join (nreverse out) "\n"))))

(defun pearl--format-comment (comment)
  "Format a normalized COMMENT plist as a level-4 Org entry.
The heading carries the author and timestamp; a property drawer carries the
comment id, the author's user id (empty for bot/external comments, which are
not editable), and a sha256 of the last-fetched body for the sync conflict
gate.  The body runs through the same markdown->org tier as the description.
A null author renders as `(unknown)'."
  (let ((author (or (plist-get comment :author) "(unknown)"))
        (created (or (plist-get comment :created-at) ""))
        (raw-body (or (plist-get comment :body) ""))
        (body (pearl--md-to-org (or (plist-get comment :body) ""))))
    (concat (format "**** %s — %s\n" author created)
            ":PROPERTIES:\n"
            (format ":LINEAR-COMMENT-ID:        %s\n" (or (plist-get comment :id) ""))
            (format ":LINEAR-COMMENT-AUTHOR-ID: %s\n" (or (plist-get comment :author-id) ""))
            (format ":LINEAR-COMMENT-SHA256:    %s\n" (secure-hash 'sha256 raw-body))
            (format ":LINEAR-COMMENT-ORG-SHA256: %s\n" (secure-hash 'sha256 (string-trim body)))
            ":END:\n"
            (if (string-empty-p body) "" (concat body "\n")))))

(defun pearl--comment-count-marker (count-info)
  "Render COUNT-INFO as a ` shown/total[+]' suffix, or the empty string.
COUNT-INFO is a plist (:shown N :total M :overflow BOOL) set on the bulk-list
path; nil (the single-issue thread) yields no marker.  The marker appends
to the `Comments' heading written by `pearl--format-comments'."
  (if count-info
      (format " %d/%d%s"
              (plist-get count-info :shown)
              (plist-get count-info :total)
              (if (plist-get count-info :overflow) "+" ""))
    ""))

(defcustom pearl-comment-sort-order 'newest-first
  "Order in which an issue's comments render under the Comments heading.
`newest-first' puts the most recent comment at the top, and a newly added
comment is inserted there.  `oldest-first' reads top-to-bottom, oldest to
newest, like an email thread, and a new comment appends at the bottom."
  :type '(choice (const :tag "Newest first (most recent on top)" newest-first)
                 (const :tag "Oldest first (chronological)" oldest-first))
  :group 'pearl)

(defun pearl--format-comments (comments &optional count-info)
  "Format COMMENTS (a list of normalized comment plists) as a Comments subtree.
Comments render under a level-3 `Comments' heading, ordered per
`pearl-comment-sort-order'.
Returns the empty string when COMMENTS is nil, so an issue with no comments
renders no subtree.  COUNT-INFO, when non-nil, appends a ` shown/total'
count to the heading (the bulk list passes the issue's `:comment-count')."
  (if (null comments)
      ""
    (let* ((newest-first (eq pearl-comment-sort-order 'newest-first))
           (sorted (sort (copy-sequence comments)
                         (lambda (a b)
                           (let ((ca (or (plist-get a :created-at) ""))
                                 (cb (or (plist-get b :created-at) "")))
                             (if newest-first (string> ca cb) (string< ca cb)))))))
      (concat "*** Comments" (pearl--comment-count-marker count-info) "\n"
              (mapconcat #'pearl--format-comment sorted "")))))

(defun pearl--format-issue-as-org-entry (issue)
  "Format a normalized ISSUE plist as an Org entry.
The heading carries the title; structured fields live in a namespaced
`LINEAR-*' property drawer (changed via commands, not by hand); the issue
description renders as the entry body.  `LINEAR-DESC-SHA256' (the markdown) and
`LINEAR-DESC-UPDATED-AT' record the description's provenance for the sync-back
conflict gates; `LINEAR-DESC-ORG-SHA256' hashes the rendered Org body so a
later refresh can tell a real local edit from a lossy md->org round-trip
without re-deriving the markdown.  `LINEAR-TITLE-SHA256' is the title's hash
(over the rendered title -- bracket-stripped and title-cased, without the
identifier prefix -- so an unedited heading is a no-op on title sync)."
  (let* ((description (or (plist-get issue :description) ""))
         (state (plist-get issue :state))
         (team (plist-get issue :team))
         (project (plist-get issue :project))
         (assignee (plist-get issue :assignee))
         (todo (pearl--state-name-to-keyword (plist-get state :name)))
         (priority (pearl--map-linear-priority-to-org (plist-get issue :priority)))
         (display-title (pearl--heading-title issue))
         (heading-title (pearl--heading-with-identifier
                         display-title (plist-get issue :identifier)))
         (label-names (mapconcat (lambda (l) (or (plist-get l :name) ""))
                                 (plist-get issue :labels) ", "))
         (label-ids (mapconcat (lambda (l) (or (plist-get l :id) ""))
                               (plist-get issue :labels) " "))
         (tags (pearl--label-tags (plist-get issue :labels)))
         (tag-string (if tags (concat " :" (string-join tags ":") ":") ""))
         (body-org (pearl--md-to-org description)))
    (concat
     (format "** %s %s%s%s\n" todo
             (if (string-empty-p priority) "" (concat priority " "))
             heading-title tag-string)
     ":PROPERTIES:\n"
     (format ":LINEAR-ID:               %s\n" (or (plist-get issue :id) ""))
     (format ":LINEAR-IDENTIFIER:       %s\n" (or (plist-get issue :identifier) ""))
     (format ":LINEAR-URL:              %s\n"
             (or (plist-get issue :url)
                 (format "https://linear.app/issue/%s" (or (plist-get issue :identifier) ""))))
     (format ":LINEAR-TEAM-ID:          %s\n" (or (plist-get team :id) ""))
     (format ":LINEAR-TEAM-NAME:        %s\n" (or (plist-get team :name) ""))
     (format ":LINEAR-PROJECT-ID:       %s\n" (or (plist-get project :id) ""))
     (format ":LINEAR-PROJECT-NAME:     %s\n" (or (plist-get project :name) ""))
     (format ":LINEAR-PRIORITY:         %s\n" (or (plist-get issue :priority) ""))
     (format ":LINEAR-STATE-ID:         %s\n" (or (plist-get state :id) ""))
     (format ":LINEAR-STATE-ID-SYNCED:  %s\n" (or (plist-get state :id) ""))
     (format ":LINEAR-STATE-NAME:       %s\n" (or (plist-get state :name) ""))
     (format ":LINEAR-STATE-TYPE:       %s\n" (or (plist-get state :type) ""))
     (format ":LINEAR-ASSIGNEE-ID:      %s\n" (or (plist-get assignee :id) ""))
     (format ":LINEAR-ASSIGNEE-ID-SYNCED: %s\n" (or (plist-get assignee :id) ""))
     (format ":LINEAR-ASSIGNEE-NAME:    %s\n" (or (plist-get assignee :name) ""))
     (format ":LINEAR-LABELS:           [%s]\n" label-names)
     (format ":LINEAR-LABEL-IDS:        %s\n" label-ids)
     (format ":LINEAR-LABEL-IDS-SYNCED: %s\n" label-ids)
     (format ":LINEAR-DESC-SHA256:      %s\n" (secure-hash 'sha256 description))
     (format ":LINEAR-DESC-ORG-SHA256:  %s\n" (secure-hash 'sha256 (string-trim body-org)))
     (format ":LINEAR-DESC-UPDATED-AT:  %s\n" (or (plist-get issue :updated-at) ""))
     (format ":LINEAR-TITLE-SHA256:     %s\n" (secure-hash 'sha256 display-title))
     ":END:\n"
     (if (string-empty-p body-org) "" (concat body-org "\n"))
     (pearl--format-comments (plist-get issue :comments)
                             (plist-get issue :comment-count)))))

;;; Description Sync-Back

(defun pearl--sync-decision (local-md stored-hash remote-md)
  "Decide how to sync a description edit.
LOCAL-MD is the current Org body rendered back to markdown.  STORED-HASH is
the sha256 of the markdown recorded when the issue was last fetched.  REMOTE-MD
is the description as it stands on Linear right now.  Returns:

- `:noop'     -- nothing to push (no local edit, or local already matches
                  remote),
- `:push'     -- a local edit against an unchanged remote: safe to push,
- `:conflict' -- both sides changed since the last fetch."
  (let ((local-hash (secure-hash 'sha256 (or local-md "")))
        (remote-hash (secure-hash 'sha256 (or remote-md ""))))
    (cond
     ((string= local-hash stored-hash) :noop)
     ((string= local-hash remote-hash) :noop)
     ((string= remote-hash stored-hash) :push)
     (t :conflict))))

;;; Conflict Resolution

;; When a description, title, or comment changed both locally and on Linear
;; since the last fetch, `pearl--sync-decision' returns `:conflict'.  Instead of
;; only refusing, the sync commands offer use-local / use-remote / rewrite (and
;; cancel).  The hard rule: no resolution silently discards the local edit, so
;; any destructive choice stashes it first (see `pearl--stash-conflict-text').

(defconst pearl--conflict-backup-buffer "*pearl-conflict-backup*"
  "Buffer holding stashed local text from destructive conflict resolutions.")

(defun pearl--stash-conflict-text (label text)
  "Stash TEXT so a destructive conflict resolution can't lose it.
Pushes TEXT onto the `kill-ring' (recover with `yank') and appends it to the
`pearl--conflict-backup-buffer' under a heading naming LABEL and the time.
Called before \"use remote\" or a rewrite replaces the local edit.  Empty TEXT
is a no-op -- there is nothing to lose."
  (when (and text (not (string-empty-p text)))
    (kill-new text)
    (with-current-buffer (get-buffer-create pearl--conflict-backup-buffer)
      (goto-char (point-max))
      (unless (bobp) (insert "\n"))
      (insert (format "## %s -- %s\n" label
                      (format-time-string "%Y-%m-%d %H:%M:%S")))
      (insert text)
      (unless (string-suffix-p "\n" text) (insert "\n")))))

(defun pearl--conflict-smerge-string (local remote)
  "Return a git-style merge-conflict string with LOCAL and REMOTE sections.
LOCAL is the user's current text, REMOTE is Linear's.  Each section is newline
terminated so the markers always start their own line; the result is meant to
drop into `smerge-mode' for resolution."
  (concat "<<<<<<< LOCAL (your edit)\n"
          local (unless (string-suffix-p "\n" local) "\n")
          "=======\n"
          remote (unless (string-suffix-p "\n" remote) "\n")
          ">>>>>>> REMOTE (Linear)\n"))

(defun pearl--read-conflict-resolution (label)
  "Prompt for how to resolve the conflict on LABEL, returning a symbol.
One of `use-local' (push mine, overwrite Linear), `use-remote' (take Linear's,
stash mine), `rewrite' (merge both in a buffer), or `cancel'.  A bare RET
defaults to `cancel', leaving everything untouched."
  (let* ((choices '(("cancel -- leave both untouched" . cancel)
                    ("use local -- push my version, overwrite Linear" . use-local)
                    ("use remote -- take Linear's, stash mine" . use-remote)
                    ("rewrite -- merge both in a buffer" . rewrite)))
         (default (caar choices))
         (pick (completing-read
                (format "Conflict on %s (RET cancels): " label)
                (mapcar #'car choices) nil t nil nil default)))
    (cdr (assoc pick choices))))

(defun pearl--set-entry-body-at-point (org-text)
  "Replace the body of the org entry at point with ORG-TEXT.
The body is the region after the entry's drawers and before its first child
heading, so a Comments subtree is left intact.  ORG-TEXT is org markup (already
converted from markdown); an empty string clears the body.  Used to write a
resolved description or comment back into the buffer."
  (save-excursion
    (org-back-to-heading t)
    (org-end-of-meta-data t)
    (let ((beg (point))
          (end (save-excursion (outline-next-heading) (point))))
      (delete-region beg end)
      (goto-char beg)
      (unless (string-empty-p org-text)
        (insert org-text "\n")))))

(defun pearl--resolve-conflict (label local-md remote-md marker stored-prop apply-fn push-fn &optional outcome-cb)
  "Interactively resolve a sync conflict on LABEL.
LOCAL-MD and REMOTE-MD are the two diverged versions.  MARKER anchors the org
entry; STORED-PROP is the provenance property advanced on resolution (such as
\"LINEAR-DESC-SHA256\").  APPLY-FN takes a text string and writes it into the
buffer (re-rendering the body, title, or comment); PUSH-FN takes a text string
and a callback invoked with non-nil on a successful push.

Resolutions (see `pearl--read-conflict-resolution'): `cancel' leaves both
untouched; `use-local' pushes the local text and advances the hash on success;
`use-remote' stashes the local text, writes Linear's version in, and advances
the hash with no push (the remote is already current).  `rewrite' opens an
smerge buffer; the reconciled text is applied and pushed on commit, or the
field is left in conflict on abort (the local text is stashed either way).

OUTCOME-CB, when given, is called once with (STATUS REASON) after the
resolution settles, for the save engine: `cancel' -> (conflict cancelled),
`use-local' -> (pushed nil) or (failed push-failed), `use-remote' ->
\(resolved-remote nil), `rewrite' commit -> (pushed nil) or (failed
push-failed), `rewrite' abort -> (conflict aborted)."
  (pcase (pearl--read-conflict-resolution label)
    ('cancel
     (message "Left %s untouched (refresh to see Linear's version)" label)
     (when outcome-cb (funcall outcome-cb 'conflict 'cancelled)))
    ('use-local
     (funcall push-fn local-md
              (lambda (ok)
                (if ok
                    (progn
                      (org-entry-put marker stored-prop
                                     (secure-hash 'sha256 local-md))
                      (message "Pushed your %s to Linear" label)
                      (when outcome-cb (funcall outcome-cb 'pushed nil)))
                  (message "Failed to push %s" label)
                  (when outcome-cb (funcall outcome-cb 'failed 'push-failed))))))
    ('use-remote
     (pearl--stash-conflict-text label local-md)
     (funcall apply-fn remote-md)
     (org-entry-put marker stored-prop (secure-hash 'sha256 remote-md))
     (message "Took Linear's %s; your version is on the kill ring and in %s"
              label pearl--conflict-backup-buffer)
     (when outcome-cb (funcall outcome-cb 'resolved-remote nil)))
    ('rewrite
     (pearl--stash-conflict-text label local-md)
     (pearl--resolve-conflict-in-smerge
      label local-md remote-md
      (lambda (reconciled)
        (funcall apply-fn reconciled)
        (funcall push-fn reconciled
                 (lambda (ok)
                   (if ok
                       (progn
                         (org-entry-put marker stored-prop
                                        (secure-hash 'sha256 reconciled))
                         (message "Synced merged %s to Linear" label)
                         (when outcome-cb (funcall outcome-cb 'pushed nil)))
                     (message "Failed to push merged %s" label)
                     (when outcome-cb (funcall outcome-cb 'failed 'push-failed))))))
      (lambda () (when outcome-cb (funcall outcome-cb 'conflict 'aborted)))))))

(defun pearl--read-atomic-conflict-resolution (label)
  "Prompt for resolving an atomic-field conflict on LABEL, returning a symbol.
One of `use-local' (push mine, overwrite Linear), `use-remote' (take Linear's),
or `cancel'.  There is no merge option -- an enum or relation value can't be
combined.  A bare RET defaults to `cancel'."
  (let* ((choices '(("cancel -- leave the field in conflict" . cancel)
                    ("use local -- push my value, overwrite Linear" . use-local)
                    ("use remote -- take Linear's value" . use-remote)))
         (default (caar choices))
         (pick (completing-read
                (format "Conflict on %s (RET cancels): " label)
                (mapcar #'car choices) nil t nil nil default)))
    (cdr (assoc pick choices))))

(defun pearl--resolve-atomic-conflict
    (label local-display remote-display push-local-fn take-remote-fn outcome-cb)
  "Resolve an atomic-field (enum/relation) conflict on LABEL interactively.
The sibling of `pearl--resolve-conflict' for fields whose value is a single
id or scalar, not mergeable text -- so there is no smerge/rewrite branch and no
SHA hash is written.

LOCAL-DISPLAY and REMOTE-DISPLAY are human-readable values for the prompt.
PUSH-LOCAL-FN takes a callback invoked with non-nil on a successful push of the
local value (the caller advances the baseline on success).  TAKE-REMOTE-FN
adopts Linear's value locally and advances the baseline, with no push.
OUTCOME-CB is called once with (STATUS REASON): `cancel' -> (conflict
cancelled); `use-local' -> (pushed nil) or (failed push-failed); `use-remote'
-> (resolved-remote nil)."
  (pcase (pearl--read-atomic-conflict-resolution label)
    ('cancel
     (message "Left %s in conflict (refresh to see Linear's %s)" label remote-display)
     (funcall outcome-cb 'conflict 'cancelled))
    ('use-local
     (funcall push-local-fn
              (lambda (ok)
                (if ok
                    (progn
                      (message "Pushed your %s (%s) to Linear" label local-display)
                      (funcall outcome-cb 'pushed nil))
                  (message "Failed to push %s" label)
                  (funcall outcome-cb 'failed 'push-failed)))))
    ('use-remote
     (funcall take-remote-fn)
     (message "Took Linear's %s (%s)" label remote-display)
     (funcall outcome-cb 'resolved-remote nil))))

;;; Compose Buffer
;;
;; A focused Org buffer for composing multi-line text (comments, descriptions)
;; that's awkward in the one-line minibuffer.  A read-only instructional header
;; sits at the top, like a git commit template; the editable body is below it.
;; C-c C-c hands the body to an armed callback, C-c C-k aborts.  The shared
;; sibling of the smerge conflict buffer below.

(defvar-local pearl--compose-on-finish nil
  "Callback invoked with the composed Org body when a compose buffer submits.")

(defvar-local pearl--compose-body-start nil
  "Marker at the start of the editable body, just past the read-only header.")

(defconst pearl--compose-comment-instructions
  "# Write a comment below, then C-c C-c to send or C-c C-k to cancel.
# This is Org markup; it is converted to Markdown for Linear.
"
  "Read-only header shown atop the comment compose buffer.")

(defconst pearl--compose-description-instructions
  "# Edit the description below, then C-c C-c to sync or C-c C-k to cancel.
# This is Org markup; it is converted to Markdown for Linear.
# The usual conflict check still applies on sync.
"
  "Read-only header shown atop the description compose buffer.")

(defun pearl--compose-body ()
  "Return the trimmed editable body of the current compose buffer.
The text below the read-only header, from `pearl--compose-body-start' on."
  (string-trim
   (buffer-substring-no-properties pearl--compose-body-start (point-max))))

(defun pearl--compose-submit ()
  "Submit the compose buffer: hand the body to the armed callback, kill the buffer."
  (interactive)
  (let ((body (pearl--compose-body))
        (callback pearl--compose-on-finish))
    (kill-buffer (current-buffer))
    (when callback (funcall callback body))))

(defun pearl--compose-abort ()
  "Abort the compose buffer without submitting."
  (interactive)
  (kill-buffer (current-buffer))
  (message "Compose canceled"))

(defun pearl--compose-in-buffer (label instructions initial on-finish)
  "Pop an Org compose buffer for LABEL with a read-only INSTRUCTIONS header.
INITIAL is the editable body (Org markup, may be empty).  \\<global-map>C-c C-c
\(`pearl--compose-submit') hands the body to ON-FINISH and kills the buffer;
C-c C-k (`pearl--compose-abort') cancels.  ON-FINISH receives the Org body and
is responsible for any markdown conversion.  The shared multi-line composer,
sibling of `pearl--resolve-conflict-in-smerge'."
  (let ((buf (get-buffer-create (format "*pearl-compose: %s*" label))))
    (with-current-buffer buf
      (let ((inhibit-read-only t))
        (erase-buffer)
        ;; `org-mode' clears buffer-local vars, so set ours after it
        (org-mode)
        (insert instructions)
        (let ((end (point)))
          ;; the whole header is read-only; only its last char is rear-nonsticky
          ;; so the body inserted just after stays editable (the interior is not,
          ;; so edits inside the header are refused)
          (add-text-properties (point-min) end '(read-only t))
          (add-text-properties (1- end) end '(rear-nonsticky t))
          (setq pearl--compose-body-start (copy-marker end nil)))
        (insert (or initial "")))
      (setq-local pearl--compose-on-finish on-finish)
      (local-set-key (kbd "C-c C-c") #'pearl--compose-submit)
      (local-set-key (kbd "C-c C-k") #'pearl--compose-abort)
      (goto-char (point-max)))
    (pop-to-buffer buf (pearl--compose-display-action))
    buf))

(defvar-local pearl--conflict-on-finish nil
  "Callback invoked with the reconciled text when a conflict buffer commits.")

(defvar-local pearl--conflict-on-abort nil
  "Thunk invoked when a conflict buffer is aborted, for save-outcome reporting.")

(defun pearl--conflict-has-markers-p (text)
  "Return non-nil if any git-style conflict markers remain in TEXT.
Used to refuse a commit while the user has left a section unresolved."
  (and (string-match-p "^\\(<<<<<<<\\|=======\\|>>>>>>>\\)" text) t))

(defun pearl--resolve-conflict-in-smerge (label local remote on-finish &optional on-abort)
  "Open an smerge buffer to reconcile LOCAL vs REMOTE for LABEL.
The user resolves the conflict markers with the usual `smerge-mode' commands,
then \\[pearl--conflict-commit] hands the reconciled text to ON-FINISH and kills
the buffer, while \\[pearl--conflict-abort] cancels (the local text is already
stashed).  ON-FINISH runs only when no conflict markers remain.  ON-ABORT, when
given, is a thunk run on abort so the save engine can report the outcome."
  (require 'smerge-mode)
  (let ((buf (get-buffer-create (format "*pearl-merge: %s*" label))))
    (with-current-buffer buf
      (erase-buffer)
      (insert (pearl--conflict-smerge-string local remote))
      (goto-char (point-min))
      (smerge-mode 1)
      (setq-local pearl--conflict-on-finish on-finish)
      (setq-local pearl--conflict-on-abort on-abort)
      (local-set-key (kbd "C-c C-c") #'pearl--conflict-commit)
      (local-set-key (kbd "C-c C-k") #'pearl--conflict-abort)
      (setq-local header-line-format
                  (substitute-command-keys
                   "Resolve the conflict, then \\[pearl--conflict-commit] to push, \\[pearl--conflict-abort] to abort")))
    (pop-to-buffer buf (pearl--compose-display-action))))

(defun pearl--conflict-commit ()
  "Finish the current pearl conflict buffer, pushing the reconciled text.
Refuses while conflict markers remain; otherwise hands the buffer text to the
armed ON-FINISH callback and kills the buffer."
  (interactive)
  (let ((text (buffer-string)))
    (when (pearl--conflict-has-markers-p text)
      (user-error "Unresolved conflict markers remain; resolve them or abort with C-c C-k"))
    (let ((cb pearl--conflict-on-finish))
      (kill-buffer (current-buffer))
      (when cb (funcall cb text)))))

(defun pearl--conflict-abort ()
  "Abort the current pearl conflict buffer without pushing.
The local text was stashed before the buffer opened, so nothing is lost.  Runs
the armed `pearl--conflict-on-abort' thunk (if any) so the save engine can
report the field as left in conflict."
  (interactive)
  (let ((cb pearl--conflict-on-abort))
    (kill-buffer (current-buffer))
    (message "Conflict resolution aborted; your text is on the kill ring and in %s"
             pearl--conflict-backup-buffer)
    (when cb (funcall cb))))

(defun pearl--entry-body-at-point ()
  "Return the body of the Org entry at point, before any child heading.
The body is the text after the property drawer and before the first child
heading (so an issue's Comments subtree is excluded), trimmed of surrounding
whitespace.  Returns the empty string when the entry has no body.  Used for
both issue descriptions and comment bodies -- hence \"entry\", not \"issue\"."
  (save-excursion
    (org-back-to-heading t)
    ;; Fix the body's end (the next heading: a Comments child or the next
    ;; issue) from the heading itself, before `org-end-of-meta-data' moves
    ;; point.  For an empty body that call skips blank lines and lands on the
    ;; next heading, so without this clamp the body would overshoot into the
    ;; next issue's whole subtree.
    (let ((end (save-excursion (outline-next-heading) (point))))
      (org-end-of-meta-data t)
      (if (>= (point) end)
          ""
        (string-trim (buffer-substring-no-properties (point) end))))))

(defun pearl--fetch-issue-description-async (issue-id callback)
  "Fetch ISSUE-ID's current description and timestamp from Linear.
CALLBACK is called with a plist (:description STR :updated-at STR) on success,
or nil on error."
  (let ((query "query IssueDescription($id: String!) {
  issue(id: $id) {
  description
  updatedAt
  }
  }")
        (variables `(("id" . ,issue-id))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let ((issue (cdr (assoc 'issue (assoc 'data data)))))
         (funcall callback
                  (when issue
                    (list :description (or (cdr (assoc 'description issue)) "")
                          :updated-at (cdr (assoc 'updatedAt issue)))))))
     (lambda (_error _response _data) (funcall callback nil)))))

(defun pearl--update-issue-description-async (issue-id markdown callback)
  "Push MARKDOWN as ISSUE-ID's description via issueUpdate.
CALLBACK is called with a plist (:success BOOL :updated-at STR)."
  (let ((query "mutation UpdateIssueDescription($id: String!, $description: String!) {
  issueUpdate(id: $id, input: {description: $description}) {
  success
  issue {
  id
  updatedAt
  }
  }
  }")
        (variables `(("id" . ,issue-id) ("description" . ,markdown))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let* ((payload (cdr (assoc 'issueUpdate (assoc 'data data))))
              (success (eq t (cdr (assoc 'success payload))))
              (issue (cdr (assoc 'issue payload))))
         (funcall callback
                  (list :success success
                        :updated-at (cdr (assoc 'updatedAt issue))))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

(defun pearl--fetch-issue-title-async (issue-id callback)
  "Fetch ISSUE-ID's current title and timestamp from Linear.
CALLBACK is called with a plist (:title STR :updated-at STR) on success, or nil
on error."
  (let ((query "query IssueTitle($id: String!) {
  issue(id: $id) {
  title
  updatedAt
  }
  }")
        (variables `(("id" . ,issue-id))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let ((issue (cdr (assoc 'issue (assoc 'data data)))))
         (funcall callback
                  (when issue
                    (list :title (or (cdr (assoc 'title issue)) "")
                          :updated-at (cdr (assoc 'updatedAt issue)))))))
     (lambda (_error _response _data) (funcall callback nil)))))

(defun pearl--update-issue-title-async (issue-id title callback)
  "Push TITLE as ISSUE-ID's title via issueUpdate.
CALLBACK is called with a plist (:success BOOL :updated-at STR)."
  (let ((query "mutation UpdateIssueTitle($id: String!, $title: String!) {
  issueUpdate(id: $id, input: {title: $title}) {
  success
  issue {
  id
  updatedAt
  }
  }
  }")
        (variables `(("id" . ,issue-id) ("title" . ,title))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let* ((payload (cdr (assoc 'issueUpdate (assoc 'data data))))
              (success (eq t (cdr (assoc 'success payload))))
              (issue (cdr (assoc 'issue payload))))
         (funcall callback
                  (list :success success
                        :updated-at (cdr (assoc 'updatedAt issue))))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

(defun pearl--issue-title-at-point ()
  "Return the title of the Linear issue heading at point.
Strips the TODO keyword, priority cookie, and tags, then strips the
`IDENT: ' identifier prefix the renderer may have added, leaving the bare
title text (the form the renderer hashed into `LINEAR-TITLE-SHA256')."
  (save-excursion
    (org-back-to-heading t)
    (pearl--strip-identifier-prefix
     (org-get-heading t t t t)
     (org-entry-get nil "LINEAR-IDENTIFIER"))))

(defun pearl--goto-heading-or-error (&optional message)
  "Move point to the enclosing heading, or signal a `user-error'.
The shared guard for the issue-at-point commands.  MESSAGE overrides the
default \"Not on a Linear issue heading\" (e.g. for a comment subtree).
Callers wrap this in `save-excursion' when they must not move point."
  (unless (ignore-errors (org-back-to-heading t) t)
    (user-error "%s" (or message "Not on a Linear issue heading"))))

(defun pearl--issue-id-at-point ()
  "Return the `LINEAR-ID' of the issue heading enclosing point, or nil.
Climbs ancestors: from inside a comment subtree (a heading carrying
`LINEAR-COMMENT-ID' but no `LINEAR-ID') it walks up to the issue heading.  Does
not move point or signal."
  (save-excursion
    (when (ignore-errors (org-back-to-heading t) t)
      (while (and (not (org-entry-get nil "LINEAR-ID"))
                  (org-up-heading-safe)))
      (org-entry-get nil "LINEAR-ID"))))

(defun pearl--goto-issue-heading-or-error ()
  "Move point to the enclosing issue heading (one carrying `LINEAR-ID'), or error.
The guard for issue-scoped commands that must work from anywhere inside an
issue subtree, including from a comment heading or body: it climbs out of the
comment to the issue heading.  Signals a `user-error' when no ancestor heading
carries `LINEAR-ID'."
  (pearl--goto-heading-or-error)
  (while (and (not (org-entry-get nil "LINEAR-ID"))
              (org-up-heading-safe)))
  (unless (org-entry-get nil "LINEAR-ID")
    (user-error "Not on a Linear issue heading")))

;;;###autoload
(defun pearl-sync-current-issue ()
  "Push the description edited in the Org body of the issue at point to Linear.
Works from anywhere inside an issue subtree.  A thin wrapper over the save
engine's description saver: an unchanged body sends nothing; an edit against an
unchanged remote is pushed and both description hashes advance; a both-changed
case is offered conflict resolution (cancel leaves it untouched)."
  (interactive)
  (save-excursion
    (pearl--goto-heading-or-error)
    (unless (org-entry-get nil "LINEAR-ID")
      (user-error "Not on a Linear issue heading"))
    (let ((buf (current-buffer)))
      (pearl--progress "Saving description...")
      (pearl--save-description-field
       (point-marker)
       (lambda (outcome) (pearl--report-save-outcome outcome buf))))))

;;;###autoload
(defun pearl-sync-current-issue-title ()
  "Push the title edited in the heading of the issue at point to Linear.
A thin wrapper over the save engine's title saver, sharing the conflict gate
with the description sync and working from anywhere inside an issue subtree.
The title is lossy: the renderer strips square brackets, so the heading holds
the stripped form and a push sends that stripped title."
  (interactive)
  (save-excursion
    (pearl--goto-heading-or-error)
    (unless (org-entry-get nil "LINEAR-ID")
      (user-error "Not on a Linear issue heading"))
    (let ((buf (current-buffer)))
      (pearl--progress "Saving title...")
      (pearl--save-title-field
       (point-marker)
       (lambda (outcome) (pearl--report-save-outcome outcome buf))))))

(defun pearl--replace-issue-subtree-at-point (issue)
  "Replace the issue subtree at point with a freshly formatted ISSUE entry.
ISSUE is a normalized issue plist.  The whole subtree (heading, drawer, body,
and any comment children) is rewritten from the entry, so the rendered result
matches a first fetch."
  (save-excursion
    (org-back-to-heading t)
    (let ((beg (point))
          (end (save-excursion (org-end-of-subtree t t) (point))))
      (delete-region beg end)
      (goto-char beg)
      (insert (pearl--format-issue-as-org-entry issue))
      ;; Close the rewritten subtree's drawer(s) but leave the issue itself
      ;; expanded -- a single-issue refresh keeps the user on the issue they
      ;; were looking at, unlike a full repopulation which re-folds the page.
      (when pearl-fold-after-update
        (save-excursion
          (goto-char beg)
          (save-restriction
            (org-narrow-to-subtree)
            (pearl--hide-or-tidy-drawers)))))))

;;;###autoload
(defun pearl-refresh-current-issue ()
  "Re-fetch the issue at point from Linear and rewrite its subtree in place.
Works from anywhere inside an issue subtree.  If the description body has
unpushed local edits, they are stashed first (kill ring + the conflict-backup
buffer) so the refresh can't silently lose them (decision 4), then the refresh
proceeds and the subtree is replaced with Linear's version."
  (interactive)
  (pearl--require-account-context)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let ((issue-id (org-entry-get nil "LINEAR-ID"))
          (marker (point-marker)))
      (progn
        ;; Stash an unpushed edit before the overwrite rather than refusing, so
        ;; an explicit single-issue refresh always proceeds without data loss.
        ;; Use the Org-hash-first dirty check (`pearl--subtree-dirty-p') so a
        ;; clean description whose markdown is lossy under org->md isn't falsely
        ;; flagged dirty and stashed -- the same fix the merge refresh uses.
        (when (pearl--subtree-dirty-p)
          (pearl--stash-conflict-text
           (format "%s description (pre-refresh)" issue-id)
           (pearl--org-to-md (pearl--entry-body-at-point))))
        (pearl--progress "Refreshing %s from Linear..." issue-id)
        (pearl--fetch-issue-async
         issue-id
         (lambda (result)
           (pcase result
             ((or :error (pred null))
              (message "Linear returned an error fetching %s; not refreshing" issue-id))
             (:missing
              (message "Issue %s is no longer on Linear (deleted or no access); not refreshing"
                       issue-id))
             (raw
              ;; The fetch may complete after the buffer was killed; only
              ;; rewrite it when it's still live.
              (if (buffer-live-p (marker-buffer marker))
                  (progn
                    (save-excursion
                      (goto-char marker)
                      (pearl--replace-issue-subtree-at-point
                       (pearl--normalize-issue raw)))
                    (pearl-highlight-comments)
                    (pearl--surface-buffer (marker-buffer marker))
                    (message "Refreshed %s from Linear" issue-id))
                (message "Refreshed %s; its buffer was closed" issue-id))))))))))

(defun pearl--create-comment-async (issue-id body callback)
  "Create a comment with BODY on ISSUE-ID via commentCreate.
CALLBACK is called with the normalized comment plist on success, or nil on a
GraphQL/transport failure or a non-success payload."
  (let ((query "mutation CommentCreate($issueId: String!, $body: String!) {
  commentCreate(input: {issueId: $issueId, body: $body}) {
  success
  comment {
  id body createdAt
  user { id name displayName }
  botActor { name }
  externalUser { name }
  }
  }
  }")
        (variables `(("issueId" . ,issue-id) ("body" . ,body))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let* ((payload (cdr (assoc 'commentCreate (assoc 'data data))))
              (success (eq t (cdr (assoc 'success payload))))
              (comment (cdr (assoc 'comment payload))))
         (funcall callback
                  (and success comment (pearl--normalize-comment comment)))))
     (lambda (_error _response _data) (funcall callback nil)))))

(defun pearl--bump-comments-count-marker ()
  "Increment the ` N/M[+]' count on the Comments heading at point, if present.
A locally added comment grows both the shown and total counts by one.  A heading
that carries no count marker (the single-issue view) is left untouched."
  (save-excursion
    (let ((eol (line-end-position)))
      (beginning-of-line)
      (when (re-search-forward " \\([0-9]+\\)/\\([0-9]+\\)\\(\\+?\\)[ \t]*$" eol t)
        (replace-match (format " %d/%d%s"
                               (1+ (string-to-number (match-string 1)))
                               (1+ (string-to-number (match-string 2)))
                               (match-string 3))
                       t t)))))

(defun pearl--append-comment-to-issue (comment)
  "Insert COMMENT (a normalized plist) under the issue subtree at point.
A new comment is the newest, so it lands where `pearl-comment-sort-order' puts
the newest: at the top of the `Comments' subtree (just under the heading) for
`newest-first', or after the last comment for `oldest-first'.  Creates the
subtree at the end of the issue when it does not exist yet."
  (save-excursion
    (org-back-to-heading t)
    (let* ((issue-end (save-excursion (org-end-of-subtree t t) (point)))
           (comments-pos
            (save-excursion
              ;; Match the new no-emoji form, the prior `💬 ' leading-glyph
              ;; layout (rendered between 2026-05-26 and the de-emoji
              ;; revert), and the pre-2026-05 trailing-glyph layout
              ;; (`Comments 💬 N/N').  Buffers rendered in any of the three
              ;; states locate their Comments heading.
              (when (re-search-forward "^\\*+ \\(?:💬 \\)?Comments\\(?:[ \t].*\\)?$" issue-end t)
                (match-beginning 0)))))
      (if comments-pos
          (progn
            (goto-char comments-pos)
            (if (eq pearl-comment-sort-order 'newest-first)
                (forward-line 1)        ; just under the heading, before the first comment
              (org-end-of-subtree t t)) ; after the last comment
            (let ((start (point)))
              (insert (pearl--format-comment comment))
              (pearl--hide-drawers-in-region start (point)))
            ;; the new comment grows the shown/total count on the heading
            (goto-char comments-pos)
            (pearl--bump-comments-count-marker))
        ;; no Comments subtree yet: this is the first comment, so it is 1/1
        (goto-char issue-end)
        (let ((start (point)))
          (insert "*** Comments 1/1\n" (pearl--format-comment comment))
          (pearl--hide-drawers-in-region start (point)))))))

;;;###autoload
(defun pearl--create-and-append-comment (issue-id marker body)
  "Create a comment with BODY on ISSUE-ID, appending it at MARKER on success.
MARKER points at the issue heading; the append, comment highlighting, and
buffer surfacing all run in the marker's buffer, so it works even when the
create callback fires with another buffer current (the compose path)."
  (pearl--progress "Adding comment to %s..." issue-id)
  (pearl--create-comment-async
   issue-id body
   (lambda (comment)
     (if (null comment)
         (message "Failed to add comment to %s" issue-id)
       (let ((buf (marker-buffer marker)))
         (when (buffer-live-p buf)
           (with-current-buffer buf
             (save-excursion
               (goto-char marker)
               (pearl--append-comment-to-issue comment))
             (pearl-highlight-comments))
           (pearl--surface-buffer buf)))
       (message "Added comment to %s" issue-id)))))

;;;###autoload
(defun pearl-create-comment (&optional body)
  "Add a comment to the Linear issue at point.
Interactively, opens an Org compose buffer (C-c C-c sends, C-c C-k cancels) and
converts the composed Org to Markdown before sending -- room to write a real
comment instead of the one-line minibuffer.  BODY, when supplied
non-interactively, is sent as-is.  Works from anywhere inside an issue subtree;
the new comment is the viewer's own, so it renders editable."
  (interactive (list nil))
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let ((issue-id (org-entry-get nil "LINEAR-ID"))
          (marker (point-marker)))
      (if body
          (pearl--create-and-append-comment issue-id marker body)
        (pearl--compose-in-buffer
         (format "comment on %s" issue-id)
         pearl--compose-comment-instructions ""
         (lambda (org)
           (pearl--create-and-append-comment
            issue-id marker (pearl--org-to-md org))))))))

;;;###autoload
(defun pearl-edit-description ()
  "Edit the description of the Linear issue at point in an Org compose buffer.
Pops the current description into a focused buffer; C-c C-c writes it back into
the issue body and syncs to Linear through the usual conflict gate, C-c C-k
cancels.  An alternative to editing the description inline for anyone who wants
a dedicated buffer.  Works from anywhere inside an issue subtree."
  (interactive)
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let ((issue-id (org-entry-get nil "LINEAR-ID"))
          (marker (point-marker)))
      (pearl--compose-in-buffer
       (format "description for %s" issue-id)
       pearl--compose-description-instructions
       (org-with-point-at marker (pearl--entry-body-at-point))
       (lambda (org)
         (org-with-point-at marker
           (pearl--set-entry-body-at-point org)
           (pearl-sync-current-issue)))))))

;;;###autoload
(defun pearl-open-current-issue ()
  "Open the Linear issue at point in the browser.
Reads the `LINEAR-URL' property of the enclosing issue heading and hands it to
`browse-url'.  Works from anywhere inside the issue subtree."
  (interactive)
  (let ((url (save-excursion
               (pearl--goto-issue-heading-or-error)
               (org-entry-get nil "LINEAR-URL"))))
    (unless (and url (not (string-empty-p url)))
      (user-error "No LINEAR-URL on the issue at point"))
    (browse-url url)))

;;;###autoload
(defun pearl-copy-issue-url ()
  "Copy the Linear URL of the issue at point to the kill ring and clipboard.
Reads the `LINEAR-URL' property of the enclosing issue heading.  Works from
anywhere inside the issue subtree and makes no network call.  `kill-new' adds
the URL to the kill ring and, through `interprogram-cut-function', the system
clipboard."
  (interactive)
  (let ((url (save-excursion
               (pearl--goto-issue-heading-or-error)
               (org-entry-get nil "LINEAR-URL"))))
    (unless (and url (not (string-empty-p url)))
      (user-error "No LINEAR-URL on the issue at point"))
    (kill-new url)
    (message "Copied %s" url)))

(defun pearl--delete-issue-async (issue-id callback)
  "Delete ISSUE-ID on Linear via issueDelete, calling CALLBACK with the outcome.
CALLBACK receives a plist (:success BOOL).  Linear's `issueDelete' is a soft
delete: it moves the issue to Trash (recoverable for about 30 days), not a
permanent purge."
  (let ((query "mutation IssueDelete($id: String!) {
  issueDelete(id: $id) { success }
  }")
        (variables `(("id" . ,issue-id))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let ((payload (cdr (assoc 'issueDelete (assoc 'data data)))))
         (funcall callback
                  (list :success (eq t (cdr (assoc 'success payload)))))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

;;;###autoload
(defun pearl-delete-current-issue ()
  "Delete the Linear issue at point after confirmation, removing its subtree.
Works from anywhere inside an issue subtree.  Confirms first, then issues a
soft delete (Linear moves the issue to Trash, recoverable for about 30 days);
on success the issue's Org subtree is removed from the buffer."
  (interactive)
  (pearl--require-account-context t)
  (let* ((marker (save-excursion (pearl--goto-issue-heading-or-error) (point-marker)))
         (issue-id (org-entry-get marker "LINEAR-ID"))
         (ident (or (org-entry-get marker "LINEAR-IDENTIFIER") "this issue")))
    (when (yes-or-no-p (format "Delete %s from Linear (moves it to Trash)? " ident))
      (pearl--delete-issue-async
       issue-id
       (lambda (result)
         (if (plist-get result :success)
             (progn
               (save-excursion
                 (goto-char marker)
                 (org-back-to-heading t)
                 (delete-region (point)
                                (progn (org-end-of-subtree t t) (point))))
               (message "Deleted %s (moved to Trash on Linear)" ident)
               (pearl--surface-buffer (marker-buffer marker)))
           (message "Failed to delete %s" ident)))))))

;;; Command-managed Drawer Fields

(defun pearl--update-issue-async (issue-id input callback)
  "Push INPUT (an `IssueUpdateInput' alist) to ISSUE-ID via issueUpdate.
INPUT is an alist of field names to values, such as a single
\"priority\"/2 or \"stateId\"/id pair, json-encoded into the input object.
CALLBACK is called with a plist of :success BOOL and :updated-at STR.  This is
the generic mutation the field commands share."
  (let ((query "mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
  issueUpdate(id: $id, input: $input) {
  success
  issue { id updatedAt }
  }
  }")
        (variables `(("id" . ,issue-id) ("input" . ,input))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let* ((payload (cdr (assoc 'issueUpdate (assoc 'data data))))
              (success (eq t (cdr (assoc 'success payload))))
              (issue (cdr (assoc 'issue payload))))
         (funcall callback
                  (list :success success
                        :updated-at (cdr (assoc 'updatedAt issue))))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

(defun pearl--set-priority-cookie (priority-num)
  "Set the Org priority cookie on the heading at point from PRIORITY-NUM.
1-4 map to #A-#D; 0 (None) removes the cookie.  The priority range is bound
locally so #D is accepted regardless of the user's `org-priority' settings."
  (save-excursion
    (org-back-to-heading t)
    (let ((org-priority-highest ?A)
          (org-priority-lowest ?D))
      (pcase priority-num
        (1 (org-priority ?A))
        (2 (org-priority ?B))
        (3 (org-priority ?C))
        (4 (org-priority ?D))
        (_ (org-priority 'remove))))))


(defun pearl--set-heading-state (state-name state-id)
  "Update the heading at point to STATE-NAME / STATE-ID.
Rewrites the TODO keyword (the slug of STATE-NAME, matching the derived
`#+TODO' header) and the LINEAR-STATE-NAME / LINEAR-STATE-ID drawer properties.
`org-after-todo-state-change-hook' is bound to nil during the keyword change so
programmatically setting the keyword does not fire any todo-change hooks the
user has installed."
  (save-excursion
    (org-back-to-heading t)
    (org-entry-put nil "LINEAR-STATE-NAME" state-name)
    (org-entry-put nil "LINEAR-STATE-ID" state-id)
    (let ((org-after-todo-state-change-hook nil))
      (org-todo (pearl--state-name-to-keyword state-name)))))

;;;###autoload
(defun pearl-edit-state (state-name)
  "Set the workflow state of the issue at point to STATE-NAME in the buffer.
Completes over the issue team's workflow states and writes the keyword, name,
and id.  The change is reconciled and pushed at the next save, not immediately.
Works from anywhere inside an issue subtree.  This picker reaches any state,
including one a TODO-keyword cycle can't express."
  (interactive
   (let ((team-id (save-excursion
                    (when (ignore-errors (org-back-to-heading t) t)
                      (org-entry-get nil "LINEAR-TEAM-ID")))))
     (list (completing-read
            "State: "
            (mapcar (lambda (s) (cdr (assoc 'name s)))
                    (and team-id (pearl--team-states team-id)))
            nil t))))
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let* ((team-id (org-entry-get nil "LINEAR-TEAM-ID"))
           (states (and team-id (pearl--team-states team-id)))
           (state (seq-find (lambda (s) (string= (cdr (assoc 'name s)) state-name))
                            states))
           (state-id (and state (cdr (assoc 'id state)))))
      (unless state-id
        (user-error "No workflow state named %s in this team" state-name))
      (pearl--set-heading-state state-name state-id)
      (message "Set state to %s (save to push)" state-name))))

(defun pearl--team-collection-names (kind team-id)
  "Return the display labels of the KIND collection for TEAM-ID, for completion."
  (mapcar (lambda (n) (pearl--node-label kind n))
          (and team-id (pearl--team-collection kind team-id))))

;;;###autoload
(defun pearl-edit-assignee (assignee-name)
  "Set the assignee of the issue at point to ASSIGNEE-NAME in the buffer.
Completes over the issue team's members, resolves the name to a user id, and
writes the assignee drawer; the change is reconciled and pushed at the next
`pearl-save-issue' / `pearl-save-all', not immediately.  Works from anywhere
inside an issue subtree."
  (interactive
   (let ((team-id (save-excursion
                    (when (ignore-errors (org-back-to-heading t) t)
                      (org-entry-get nil "LINEAR-TEAM-ID")))))
     (list (completing-read "Assignee: "
                            (pearl--team-collection-names 'members team-id)
                            nil t))))
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let* ((team-id (org-entry-get nil "LINEAR-TEAM-ID"))
           (assignee-id (and team-id
                             (pearl--resolve-team-id 'members assignee-name team-id))))
      (unless assignee-id
        (user-error "No team member matching %s" assignee-name))
      (org-entry-put nil "LINEAR-ASSIGNEE-NAME" assignee-name)
      (org-entry-put nil "LINEAR-ASSIGNEE-ID" assignee-id)
      (message "Set assignee to %s (save to push)" assignee-name))))

(defun pearl--set-heading-label-tags (tags)
  "Replace the Org tags on the issue heading at point with TAGS, a list of strings.
Only the heading's tag set changes: the TODO keyword, priority cookie, title,
identifier prefix, body, and drawer are preserved.  Pearl owns the entire
issue-heading tag set, so any hand-added tags are dropped.  An empty TAGS list
clears the heading's tags.  Point must be on or inside the issue heading."
  (save-excursion
    (org-back-to-heading t)
    (org-set-tags tags)))

;;;###autoload
(defun pearl-edit-labels (label-names)
  "Set the labels of the issue at point to LABEL-NAMES in the buffer.
Completes (multiple) over the issue team's labels; an empty selection clears
them.  Resolves each name to a label id and writes the labels drawer plus the
`LINEAR-LABEL-IDS' live set; the change is reconciled and pushed at the next
`pearl-save-issue' / `pearl-save-all', not immediately.  Works from anywhere
inside an issue subtree."
  (interactive
   (let ((team-id (save-excursion
                    (when (ignore-errors (org-back-to-heading t) t)
                      (org-entry-get nil "LINEAR-TEAM-ID")))))
     (list (completing-read-multiple
            "Labels (comma-separated, empty to clear): "
            (pearl--team-collection-names 'labels team-id)))))
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let* ((team-id (org-entry-get nil "LINEAR-TEAM-ID"))
           (label-ids (mapcar
                       (lambda (name)
                         (or (and team-id
                                  (pearl--resolve-team-id 'labels name team-id))
                             (user-error "No label matching %s" name)))
                       label-names)))
      (org-entry-put nil "LINEAR-LABELS"
                     (format "[%s]" (mapconcat #'identity label-names ", ")))
      (org-entry-put nil "LINEAR-LABEL-IDS" (string-join label-ids " "))
      (pearl--set-heading-label-tags
       (pearl--label-tags (mapcar (lambda (n) (list :name n)) label-names)))
      (message "Set labels to %s (save to push)"
               (if label-names (mapconcat #'identity label-names ", ") "none")))))

;;; User-facing Commands (Async)

(defun pearl--source-name (source)
  "Return the display name of a SOURCE descriptor, or a default."
  (or (plist-get source :name) "Linear issues"))

(defun pearl--summarize-filter (filter)
  "Return a short human-readable summary of a FILTER authoring plist.
An empty FILTER summarizes as \"all issues\"."
  (if (null filter)
      "all issues"
    (let (parts)
      (cl-loop for (key val) on filter by #'cddr do
               (push (pcase key
                       (:assignee (format "assignee: %s"
                                          (if (eq val :me) "me" val)))
                       (:open (if val "open" "any state"))
                       (:labels (format "labels: %s"
                                        (mapconcat #'identity
                                                   (if (listp val) val (list val))
                                                   ", ")))
                       (_ (format "%s: %s" (substring (symbol-name key) 1) val)))
                     parts))
      (mapconcat #'identity (nreverse parts) ", "))))

(defun pearl--read-active-source ()
  "Read the active source descriptor from the current buffer's header, or nil.
Parses the `#+LINEAR-SOURCE:' keyword that `pearl--build-org-content'
writes."
  (save-excursion
    (goto-char (point-min))
    (when (re-search-forward "^#\\+LINEAR-SOURCE: \\(.*\\)$" nil t)
      (ignore-errors (car (read-from-string (match-string 1)))))))

(defun pearl--gather-header-states (issues)
  "Collect the ordered workflow states for the ISSUES' teams, for the header.
Teams in first-seen order across ISSUES; within a team, states by Linear
`position'.  Each team's full state set is fetched (cached) via
`pearl--team-states'.  A team whose fetch fails is skipped, but every displayed
issue's own state is appended afterward so it is still declared (the coverage
guarantee).  Returns a list of (:name :type :position) plists;
`pearl--derive-todo-line' de-duplicates by slug, so the appended issue states
only add the ones a failed team fetch left out."
  (let ((team-ids '()) (seen (make-hash-table :test 'equal)))
    (dolist (issue issues)
      (let ((tid (plist-get (plist-get issue :team) :id)))
        (when (and tid (not (gethash tid seen)))
          (puthash tid t seen)
          (push tid team-ids))))
    (let ((team-states
           (apply #'append
                  (mapcar
                   (lambda (tid)
                     (mapcar
                      (lambda (node)
                        (list :name (cdr (assoc 'name node))
                              :type (cdr (assoc 'type node))
                              :position (cdr (assoc 'position node))))
                      (sort (copy-sequence (or (ignore-errors (pearl--team-states tid)) '()))
                            (lambda (a b)
                              (< (or (cdr (assoc 'position a)) most-positive-fixnum)
                                 (or (cdr (assoc 'position b)) most-positive-fixnum))))))
                   (nreverse team-ids))))
          (issue-states
           (delq nil
                 (mapcar (lambda (issue)
                           (let ((st (plist-get issue :state)))
                             (when (plist-get st :name)
                               (list :name (plist-get st :name)
                                     :type (plist-get st :type)
                                     :position (plist-get st :position)))))
                         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 Help\" 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 Help\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--preamble-region ()
  "Return (BEG . END) for the `#+' keyword preamble of the current buffer.
BEG is `point-min'; END is the start of the first heading.  nil when the buffer
has no heading."
  (save-excursion
    (goto-char (point-min))
    (when (re-search-forward "^\\*+ " nil t)
      (cons (point-min) (match-beginning 0)))))

(defun pearl--preamble-keyword (keyword)
  "Return the value of file KEYWORD (e.g. \"LINEAR-COUNT\") in the buffer, or nil."
  (save-excursion
    (goto-char (point-min))
    (when (re-search-forward (format "^#\\+%s: \\(.*\\)$" (regexp-quote keyword))
                             nil t)
      (string-trim (match-string 1)))))

(defun pearl--preamble-summary ()
  "Compose the one-line preamble summary for the current Linear buffer.
\"Pearl - <view> · <count> · <time>\", read from `#+LINEAR-SOURCE' (its name),
`#+LINEAR-COUNT', and the time portion of `#+LINEAR-RUN-AT'.  Missing fields are
omitted.  Leads with \"Pearl\" so the line doubles as the buffer's identity."
  (let* ((src (pearl--read-active-source))
         (name (or (and src (plist-get src :name)) "Linear"))
         (count (pearl--preamble-keyword "LINEAR-COUNT"))
         (runat (pearl--preamble-keyword "LINEAR-RUN-AT"))
         (time (and runat (car (last (split-string runat))))))
    (concat "Pearl - " name
            (and count (format " · %s" count))
            (and time (format " · %s" time)))))

(defun pearl--hide-preamble (&optional buffer)
  "Collapse the `#+' keyword preamble of BUFFER to a styled one-line summary.
When `pearl-hide-preamble' is non-nil, lay (or refresh) a single overlay over
the preamble region (`pearl--preamble-region') whose `display' is
`pearl--preamble-summary' in `pearl-preamble-summary' face.  Idempotent: removes
any prior pearl overlay first, so re-rendering never stacks duplicates; when the
option is nil it just removes it.  Buffer text is untouched, so parsing and the
merge rewrites keep working."
  (with-current-buffer (or buffer (current-buffer))
    (dolist (o (overlays-in (point-min) (point-max)))
      (when (overlay-get o 'pearl-preamble)
        (delete-overlay o)))
    (when pearl-hide-preamble
      (let ((region (pearl--preamble-region)))
        (when region
          (let ((ov (make-overlay (car region) (cdr region))))
            (overlay-put ov 'pearl-preamble t)
            (overlay-put ov 'evaporate t)
            (overlay-put ov 'display
                         (propertize (concat (pearl--preamble-summary) "\n")
                                     'face 'pearl-preamble-summary))))))))

(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
`pearl-refresh-current-view' can re-run it; TRUNCATED marks that the page cap
was hit.  STATES is the ordered workflow-state list (see
`pearl--gather-header-states') the `#+TODO:' line is derived from; a nil STATES
yields the hardcoded default.  ACCOUNT, when non-nil, is the Linear account name
stamped as `#+LINEAR-ACCOUNT' so the buffer guard can tell which workspace owns
this file; nil (legacy single-account mode) omits the marker.  Pure function,
no side effects."
  (let* ((src (or source '(:type filter :name "Linear issues" :filter nil)))
         (name (pearl--source-name src))
         (filter (plist-get src :filter)))
    (with-temp-buffer
      ;; The view name renders verbatim, matching Linear's own capitalization;
      ;; `pearl-title-case-headings' governs issue headings only.
      (insert (format "#+title: Linear — %s\n" name))
      (insert "#+STARTUP: show3levels\n")
      (insert (format "#+TODO: %s\n" (pearl--derive-todo-line states)))
      ;; Source-tracking metadata: the serialized source drives refresh; the
      ;; rest is human-readable provenance.
      (when account
        (insert (format "#+LINEAR-ACCOUNT: %s\n" account)))
      (insert (format "#+LINEAR-SOURCE: %s\n" (prin1-to-string src)))
      (insert (format "#+LINEAR-RUN-AT: %s\n" (format-time-string "%Y-%m-%d %H:%M")))
      (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")))
      ;; 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
      ;; show3levels fold has a level-1 root.  Named after the view.
      (insert (format "* %s\n" name))

      (dolist (issue issues)
        (insert (pearl--format-issue-as-org-entry issue)))

      (buffer-string))))

(defun pearl--dirty-refresh-choice (path)
  "Ask how to refresh PATH when its buffer has unsaved changes.
Returns one of ?d (discard the edits and rebuild), ?m (merge by LINEAR-ID,
keeping unpushed edits), or ?q (cancel and leave the buffer untouched)."
  (read-char-choice
   (format (concat "%s has unsaved changes — "
                   "(d)iscard & refresh, (m)erge keeping edits, (q) cancel? ")
           (file-name-nondirectory path))
   '(?d ?m ?q)))

(defun pearl--update-org-from-issues (issues &optional source truncated)
  "Update `pearl-org-file-path' with rendered ISSUES, buffer-aware.
SOURCE and TRUNCATED are threaded into the header (see
`pearl--build-org-content').

Behavior depends on whether the file is currently visited in a buffer:

- No buffer visiting the file: write atomically to disk via `with-temp-file',
  then visit it so there is a buffer to show.
- Buffer exists and is unmodified: replace its contents in place and save,
  preserving point and avoiding a modtime mismatch warning.
- Buffer exists and has unsaved edits: a full rebuild would discard them, so
  prompt (see `pearl--dirty-refresh-choice') to discard and rebuild, merge by
  LINEAR-ID keeping the edits, or cancel.

In every case the resulting buffer is surfaced (see `pearl--surface-buffer'),
so a fetch run from a menu or dashboard actually shows the issues instead of
just writing the file and leaving it off-screen."
  (let* ((org-file-path pearl-org-file-path)
         (account (and pearl--account-context
                       (plist-get pearl--account-context :name)))
         (states (pearl--gather-header-states issues))
         (new-content (pearl--build-org-content issues source truncated states account))
         (existing-buf (find-buffer-visiting org-file-path)))
    (cond
     ;; Branch A: no buffer visits the file -- atomic file write, then visit.
     ((not existing-buf)
      (pearl--log "Writing %d issues to %s (no buffer)"
                         (length issues) org-file-path)
      (make-directory (file-name-directory org-file-path) t)
      (with-temp-file org-file-path
        (insert new-content))
      (message "Updated Linear issues in %s with %d active issues"
               org-file-path (length issues))
      (let ((buf (find-file-noselect org-file-path)))
        (with-current-buffer buf
          (pearl-mode 1)
          (pearl--restore-page-visibility)
          (pearl-highlight-comments))
        (pearl--surface-buffer buf)))

     ;; Branch B: buffer exists and is clean -- replace contents in place.
     ((not (buffer-modified-p existing-buf))
      (pearl--log "Writing %d issues to %s (clean buffer)"
                         (length issues) org-file-path)
      (with-current-buffer existing-buf
        (let ((recorded-point (point))
              (inhibit-read-only t))
          (erase-buffer)
          (insert new-content)
          (save-buffer)
          (goto-char (min recorded-point (point-max)))
          (pearl--restore-page-visibility)
          (pearl-highlight-comments)
          (pearl--hide-preamble)))
      (message "Updated Linear issues in %s with %d active issues"
               org-file-path (length issues))
      (pearl--surface-buffer existing-buf))

     ;; Branch C: buffer is dirty -- a full rebuild would discard unsaved work,
     ;; so ask before clobbering rather than silently deferring.
     (t
      (pcase (pearl--dirty-refresh-choice org-file-path)
        (?d                             ; discard the edits, rebuild in place
         (with-current-buffer existing-buf
           (let ((inhibit-read-only t))
             (set-buffer-modified-p nil)
             (erase-buffer)
             (insert new-content)
             (save-buffer)
             (goto-char (point-min))
             (pearl--restore-page-visibility)
             (pearl-highlight-comments)
             (pearl--hide-preamble)))
         (message "Updated Linear issues in %s with %d active issues"
                  org-file-path (length issues))
         (pearl--surface-buffer existing-buf))
        (?m                             ; merge by LINEAR-ID, keeping edits
         (with-current-buffer existing-buf
           (let ((counts (pearl--merge-issues-into-buffer issues)))
             (pearl--update-source-header (length issues) truncated)
             (pearl--update-derived-todo-header (pearl--gather-header-states issues))
             (pearl-highlight-comments)
             (pearl--hide-preamble)
             ;; Fold only the subtrees the merge re-rendered or appended; leave
             ;; the rest of the page (and point) as the user had them, so an
             ;; edit-then-merge flow doesn't collapse the subtree they were
             ;; editing.
             (pearl--fold-touched-subtrees (plist-get counts :touched-markers))
             (message "Merged into %s: %d updated, %d added, %d dropped%s"
                      (file-name-nondirectory org-file-path)
                      (plist-get counts :updated)
                      (plist-get counts :added)
                      (plist-get counts :dropped)
                      (let ((s (plist-get counts :skipped)))
                        (if (> s 0) (format ", %d kept (unpushed edits)" s) "")))))
         (pearl--surface-buffer existing-buf))
        (_                              ; cancel
         (message "Linear refresh cancelled; %s left unchanged"
                  (file-name-nondirectory org-file-path))
         (pearl--surface-buffer existing-buf)))))))

(defcustom pearl-local-views nil
  "Named local views, run with `pearl-run-local-view'.
Each entry is (NAME . SPEC) where SPEC is a plist with `:filter' (an authoring
filter plist), and optional `:sort' (`updated', `created', `priority', or
`title') and `:order' (`asc' or `desc', default `desc').  AND-only in v1; use a
Linear Custom View for OR logic."
  :type '(alist :key-type string :value-type plist)
  :group 'pearl)

(defcustom pearl-default-view nil
  "Local view `pearl-open-default-view' opens, or nil for my open issues.
A durable preference for what the hot key shows.  nil means the built-in
\"my open issues\" fetch (`pearl-list-issues' with no project -- today's
behavior); a string names a local view in `pearl-local-views'.

In multi-account mode the active account's `:default-view' key (see
`pearl-accounts') takes precedence and this global is unused; it applies in
legacy single-account mode.  To default to a Linear Custom View, save it
locally first with `pearl-save-linear-view-locally' and name the resulting
local view here.  Set it durably through `pearl-set-default-view'."
  :type '(choice (const :tag "My open issues" nil)
                 (string :tag "Local view name"))
  :group 'pearl)

(defun pearl--sort-issues (issues sort order)
  "Return ISSUES sorted by SORT (a symbol) in ORDER (`asc' or `desc').
SORT is one of `updated', `priority', `title', or nil (no client-side sort).
ORDER defaults to descending.  Sorting happens after fetch so a refresh always
produces the same heading order rather than reshuffling into noise."
  (let ((key (pcase sort
               ('updated (lambda (i) (or (plist-get i :updated-at) "")))
               ('priority (lambda (i) (or (plist-get i :priority) 99)))
               ('title (lambda (i) (downcase (or (plist-get i :title) ""))))
               (_ nil))))
    (if (null key)
        issues
      (let* ((lessp (if (eq sort 'priority)
                        (lambda (a b) (< (funcall key a) (funcall key b)))
                      (lambda (a b) (string< (funcall key a) (funcall key b)))))
             (ascending (sort (copy-sequence issues) lessp)))
        (if (eq order 'asc) ascending (nreverse ascending))))))

(defun pearl--sort->order-by (sort)
  "Map a SORT symbol to the server `orderBy' value.
`created' uses `createdAt'; everything else (including `updated') uses
`updatedAt', the only other field Linear's public ordering supports."
  (if (eq sort 'created) 'createdAt 'updatedAt))

;;; Sentinel infrastructure for filter / pick-one prompts
;;
;; These sentinel constants and helpers back the prompt UX shared by
;; `pearl-run-local-view', `pearl-delete-local-view',
;; `pearl-list-issues-filtered', `pearl-pick-source', and
;; `pearl-publish-local-view'.  Defined ahead of those commands so
;; the byte-compiler resolves the references in order.

(defconst pearl--filter-any "[ Any. ]"
  "Sentinel candidate shown at the top of filter-dimension prompts.
Picking it means \"no constraint on this dimension\" -- i.e. *any* value
matches.  Earlier drafts read \"[ None. ]\", which described what the user
picked rather than what the filter does; the dimension's not absent, it's
unconstrained.  Always rendered first so the choice is visible rather
than a hidden empty-input idiom.")

(defconst pearl--filter-cancel "[ Cancel. ]"
  "Sentinel candidate shown at the top of pick-an-existing-thing prompts
(delete a local view, run a local view) where the opt-out reads as
\"don't do this\" rather than \"no constraint.\"  Cancelling these
prompts is a real choice, not a missing one.")

(defun pearl--filter-sentinel-value-p (value)
  "Return non-nil when VALUE is a sentinel (any opt-out marker) or empty.
A nil, an empty string, `pearl--filter-any', or `pearl--filter-cancel'
all mean the user opted out (of constraining, or of acting)."
  (or (null value)
      (and (stringp value)
           (or (string-empty-p value)
               (string= value pearl--filter-any)
               (string= value pearl--filter-cancel)))))

(defun pearl--with-sentinel (sentinel candidates)
  "Return CANDIDATES with SENTINEL prepended as the first option."
  (cons sentinel candidates))

(defun pearl--completion-table-keep-order (candidates)
  "Return a completion table over CANDIDATES that preserves input order.
The framework-side sort (vertico-sort-function, prescient, ivy, etc.)
re-sorts alphabetically by default, which clobbers the sentinel as the
topmost option whenever a real candidate sorts ahead of \"[\".  Setting
the table's `display-sort-function' to `identity' is the standard Emacs
hook for \"these are pre-sorted, leave them alone\"."
  (lambda (string pred action)
    (if (eq action 'metadata)
        '(metadata (display-sort-function . identity)
                   (cycle-sort-function . identity))
      (complete-with-action action candidates string pred))))

(defun pearl--read-yes-no (prompt &optional default)
  "Ask PROMPT as a completing-read over (\"yes\" \"no\") and return t / nil.
DEFAULT is the value RET picks without typing; \"yes\" if omitted.  The
candidate list is ordered with the default first so the most-common
choice is what the user sees at the top, consistent with
`pearl--with-sentinel'.  Use this for non-destructive prompts where
RET-through the defaults is a feature; keep `yes-or-no-p' for destructive
prompts (delete, overwrite) where typing \"yes\" is a safety affordance."
  (let* ((d (or default "yes"))
         (other (if (string= d "yes") "no" "yes"))
         (choice (completing-read prompt
                                  (pearl--completion-table-keep-order
                                   (list d other))
                                  nil t nil nil d)))
    (string= "yes" choice)))

;;;###autoload
(defun pearl-run-local-view (name)
  "Run the local view NAME from `pearl-local-views'.
Interactively, completes over the configured query names.  Compiles the stored
filter, fetches, sorts per the query's `:sort'/`:order', and renders into the
active file with the query recorded as the source."
  (interactive
   (list (if (null pearl-local-views)
             (user-error "No local views configured")
           (completing-read
            "Local view: "
            (pearl--completion-table-keep-order
             (pearl--with-sentinel pearl--filter-cancel
              (mapcar #'car pearl-local-views)))
            nil t))))
  (when (pearl--filter-sentinel-value-p name)
    (user-error "Cancelled; no local view run"))
  (let ((entry (assoc name pearl-local-views)))
    (unless entry
      (user-error "No local view named %s" name))
    (let* ((spec (cdr entry))
           (filter-plist (plist-get spec :filter))
           (sort (plist-get spec :sort))
           (order (plist-get spec :order))
           (source (list :type 'filter :name name :filter filter-plist
                         :sort sort :order order)))
      ;; Account guard, checked before any filter compilation or network call:
      ;; a view tagged for another account would otherwise resolve its team /
      ;; state / label names against the wrong workspace.  Inert in legacy mode
      ;; and for an untagged (shared) view.
      (pearl--require-local-view-account name spec)
      ;; Validate the local view's authoring plist at the command boundary so
      ;; a typo'd key or bad value surfaces as a clear user-error instead of
      ;; being silently dropped or failing deeper in the compiler.
      (pearl--validate-issue-filter filter-plist)
      (pearl--progress "Running local view %s..." name)
      (pearl--query-issues-async
       (pearl--build-issue-filter filter-plist)
       (lambda (result) (pearl--render-query-result result source))
       (pearl--sort->order-by sort)))))

;;; pearl-pick-source -- the unified source picker (favorites + local views)

(defun pearl--saved-query-scope-label (spec teams)
  "Return the scope display label for SPEC (a saved-query plist).
Returns nil for a local-only entry (no `:linear-view-id'), \"Personal\"
for a synced entry with no team scope, the team name when SPEC's
`:linear-view-team-id' resolves against TEAMS, or \"?\" when the team
id is set but missing from TEAMS (which surfaces a stale link to the
user rather than silently mis-labelling)."
  (let ((view-id (plist-get spec :linear-view-id))
        (team-id (plist-get spec :linear-view-team-id)))
    (when view-id
      (cond ((null team-id) "Personal")
            ((null teams) "?")
            (t (or (cdr (assoc 'name
                               (seq-find
                                (lambda (tm)
                                  (equal team-id (cdr (assoc 'id tm))))
                                teams)))
                   "?"))))))

(defun pearl--pick-source-candidates (favorites saved-queries &optional teams)
  "Build the picker's candidate alist `((DISPLAY . SOURCE-OR-ACTION) ...)'.
FAVORITES is a list of normalized favorite plists; SAVED-QUERIES is the
`pearl-local-views' alist; TEAMS resolves the scope name of a tracked local
view.  Favorites come first in ascending `:sort-order'; local views follow
alphabetically.

Each DISPLAY is one of:
  `[KIND] TITLE'                    for a non-view favorite (opens in browser)
  `[linear] TITLE'                  for a Linear view favorite
  `[local] NAME'                    for a local-only local view
  `[local \\u2192 Linear:SCOPE] NAME'      for a published (tracked) local view
where SCOPE is the team name resolved from `:linear-view-team-id' against
TEAMS, \"Personal\" when there's no team scope, or \"?\" when the team id is
stale or TEAMS is nil.

Dispatch follows the source-of-truth rule (decision 16): EVERY local view --
tracked or not -- dispatches as `:type filter' and runs its LOCAL authoring
filter via `pearl--query-issues-async', never the Linear mirror.  A tracked
entry carries its `:linear-view-url' as `:url' so the rendered buffer can
still open the mirror.  A native Linear view favorite dispatches as
`:type view'.

Cross-store dedup: a Linear view favorite whose `customView' id matches a
tracked local view's `:linear-view-id' is dropped, so the editable local
entry is the one shown.  Local and Linear views that merely share a NAME stay
distinct (their labels differ).  Display strings are made unique by appending
` (#N)' on a true collision."
  (let* ((tracked-ids
          (delq nil (mapcar (lambda (sq) (plist-get (cdr sq) :linear-view-id))
                            saved-queries)))
         (fav-sorted (sort (copy-sequence favorites)
                           (lambda (a b)
                             (< (or (plist-get a :sort-order) 0.0)
                                (or (plist-get b :sort-order) 0.0)))))
         (saved-sorted (sort (copy-sequence saved-queries)
                             (lambda (a b) (string< (car a) (car b)))))
         (alist nil)
         (seen (make-hash-table :test 'equal)))
    (cl-labels
        ((push-unique
          (display source)
          (let ((d display) (n 2))
            (while (gethash d seen)
              (setq d (format "%s (#%d)" display n))
              (cl-incf n))
            (puthash d t seen)
            (push (cons d source) alist))))
      (dolist (fav fav-sorted)
        (let* ((kind (plist-get fav :kind))
               (title (plist-get fav :title))
               (source (pearl--favorite->source fav))
               (fav-view-id (and (eq (plist-get source :type) 'view)
                                 (plist-get source :id))))
          ;; Cross-store dedup: drop a Linear view favorite already mirrored by
          ;; a tracked local view, so the editable local entry is what's shown.
          (unless (and fav-view-id (member fav-view-id tracked-ids))
            (push-unique
             (if (eq kind 'view)
                 (format "[linear] %s" title)
               (format "[%s] %s" (symbol-name kind) title))
             source))))
      (dolist (sq saved-sorted)
        (let* ((name (car sq))
               (spec (cdr sq))
               (view-id (plist-get spec :linear-view-id))
               (scope-label (pearl--saved-query-scope-label spec teams))
               (display (if view-id
                            (format "[local → Linear:%s] %s" scope-label name)
                          (format "[local] %s" name)))
               ;; Decision 16: every local view runs its LOCAL filter, tracked
               ;; or not.  :url carries the mirror so open-in-linear still works.
               (source (append
                        (list :type 'filter :name name
                              :filter (plist-get spec :filter)
                              :sort (plist-get spec :sort)
                              :order (plist-get spec :order))
                        (let ((u (plist-get spec :linear-view-url)))
                          (when u (list :url u))))))
          (push-unique display source))))
    (nreverse alist)))

(defun pearl--open-favorite-url (action)
  "Open ACTION's `:url' in the browser, or refuse with a clear `user-error'
when the URL is nil or empty.  Messages \"Opened KIND favorite in browser: TITLE\"
on success so the user sees what happened."
  (let ((url (plist-get action :url))
        (kind (plist-get action :kind))
        (title (plist-get action :title)))
    (unless (and url (stringp url) (not (string-empty-p url)))
      (user-error "Favorite has no URL to open"))
    (browse-url url)
    (message "Opened %s favorite in browser: %s"
             (if kind (symbol-name kind) "linear") title)))

;;;###autoload
(defun pearl-pick-source ()
  "Pick a Linear favorite or local view and fetch it into the active file.
Favorites are listed first in Linear's sort order, then local views
alphabetically.  Non-list favorites (issue, document, ...) open in the browser
instead.  On a favorites-fetch failure the picker still offers any local saved
queries -- favorites-failure is not the same user state as \"no favorites\".
With neither favorites nor local views, signals a `user-error' naming the
missing setup."
  (interactive)
  (pearl--progress "Fetching favorites...")
  (let ((saved pearl-local-views))
    (pearl--favorites-async
     (lambda (favorites)
       ;; Only fetch teams when at least one local view is synced -- scope
       ;; resolution is the only thing teams data feeds, and an all-local
       ;; configuration has no scopes to resolve.
       (let* ((teams (and (cl-some (lambda (sq)
                                     (plist-get (cdr sq) :linear-view-id))
                                   saved)
                          (pearl--all-teams)))
              (cands (pearl--pick-source-candidates favorites saved teams)))
         (unless cands
           (user-error
            "No favorites or local views -- star views in Linear, or set `pearl-local-views'"))
         (let* ((display (completing-read "Source: " (mapcar #'car cands) nil t))
                (source (cdr (assoc display cands))))
           (cond
            ((plist-get source :browser)
             (pearl--open-favorite-url source))
            ((eq (plist-get source :type) 'view)
             (pearl--progress "Running view %s..." (plist-get source :name))
             (pearl--query-view-async
              (plist-get source :id)
              (lambda (result) (pearl--render-query-result result source))))
            (t
             (let ((filter (plist-get source :filter)))
               (pearl--validate-issue-filter filter)
               (pearl--progress "Running %s..." (plist-get source :name))
               (pearl--query-issues-async
                (pearl--build-issue-filter filter)
                (lambda (result) (pearl--render-query-result result source))
                (pearl--sort->order-by (plist-get source :sort))))))))))))

;;; Copy down: save a Linear view as a local view (see the reverse-compile above)

(defun pearl--customview-filterdata-async (view-id callback)
  "Fetch the `filterData' of Custom View VIEW-ID and call CALLBACK with it.
CALLBACK receives the json-read-shaped filter object, or nil on a transport /
GraphQL error or a view with no readable filter."
  (pearl--graphql-request-async
   "query ViewFilter($id: String!) { customView(id: $id) { filterData } }"
   `(("id" . ,view-id))
   (lambda (response)
     (let* ((cv (cdr (assq 'customView (cdr (assq 'data response)))))
            (fd (and cv (cdr (assq 'filterData cv)))))
       (funcall callback fd)))
   (lambda (&rest _) (funcall callback nil))))

(defun pearl--linear-view-favorites (favorites)
  "Return `((TITLE . VIEW-ID) ...)' for the view-kind entries in FAVORITES.
These are the copy-down candidates -- only a favorited Linear view carries a
Custom View id and a readable filter."
  (delq nil
        (mapcar (lambda (fav)
                  (when (eq (plist-get fav :kind) 'view)
                    (cons (plist-get fav :title) (plist-get fav :id))))
                favorites)))

(defun pearl--save-linear-view-locally-finish (title view-id filter-data)
  "Reverse-compile FILTER-DATA for Linear view TITLE/VIEW-ID and save a fork.
On a refusal, signal a `user-error' naming the construct and pointing at
`pearl-run-linear-view'.  On success, save a forked local view (no tracking
link, `:copied-from-view-id' provenance only) and report the independence."
  (when (null filter-data)
    (user-error
     "Couldn't read a filter for \"%s\" (it may have none, or the fetch failed); try again or run it with `pearl-run-linear-view'"
     title))
  (let ((rc (pearl--reverse-compile-issue-filter filter-data)))
    (if (eq (car rc) 'refuse)
        (user-error
         "Can't copy \"%s\" down: %s.  Run it with `pearl-run-linear-view' instead"
         title (cdr rc))
      (let* ((filter (cdr rc))
             (name (pearl--resolve-local-view-name
                    (read-string "Name for the local view: " title))))
        (unless name (user-error "Cancelled; no local view created"))
        (pearl--save-local-view name filter)
        ;; Record provenance for reference only -- this is a fork, not a sync
        ;; link, so it carries no :linear-view-id.
        (let ((entry (assoc name pearl-local-views)))
          (when entry
            (setcdr entry (plist-put (cdr entry) :copied-from-view-id view-id))
            (ignore-errors
              (customize-save-variable 'pearl-local-views pearl-local-views))))
        (message
         "Saved Linear view %s as independent local view %s; edits won't update the original until you publish it back"
         title name)))))

;;;###autoload
(defun pearl-save-linear-view-locally ()
  "Copy a favorited Linear view down into a new, editable local view.
Lists your favorited Linear views, fetches the chosen view's filter, reverse-
compiles it into a Pearl authoring filter, and saves a forked local view -- no
tracking link, so editing or renaming it never touches the Linear view.  The new
view is stamped with the active account.  When the view's filter is outside
Pearl's local model (OR logic, an unmodeled dimension, a multi-value filter),
refuses and names the construct; run such a view directly with
`pearl-run-linear-view'."
  (interactive)
  (pearl--require-account-context t)
  (pearl--progress "Fetching favorited Linear views...")
  (pearl--favorites-async
   (lambda (favorites)
     (let ((views (pearl--linear-view-favorites favorites)))
       (unless views
         (user-error
          "No favorited Linear views; favorite a view in Linear first, then copy it down"))
       (let* ((title (completing-read "Save Linear view locally: "
                                      (mapcar #'car views) nil t))
              (view-id (cdr (assoc title views))))
         (pearl--progress "Fetching filter for %s..." title)
         (pearl--customview-filterdata-async
          view-id
          (lambda (filter-data)
            (pearl--save-linear-view-locally-finish title view-id filter-data))))))))

(defun pearl--assemble-filter (team open state project labels assignee)
  "Assemble a filter authoring plist from the chosen dimensions.
The non-nil of TEAM, OPEN, STATE, PROJECT, LABELS, and ASSIGNEE appear (an
empty LABELS list is dropped), feeding `pearl--build-issue-filter'
with just what the user set."
  (append
   (when team (list :team team))
   (cond ((eq assignee :me) (list :assignee :me))
         ((stringp assignee) (list :assignee-id assignee)))
   (when open (list :open t))
   (when state (list :state state))
   (when project (list :project project))
   (when labels (list :labels labels))))

(defun pearl--read-filter-interactively ()
  "Build a filter plist by completing over the chosen team's fetched dimensions.
Picks a team first (scoping the rest), then offers open-only, state, project,
labels, and assignee.  Each prompt carries `pearl--filter-any' as the topmost
choice; selecting it means \"no constraint on this dimension.\"  The assignee
prompt offers `me' (the viewer), `member' (a specific teammate, resolved to
an id), or `pearl--filter-any' (any assignee, no scoping)."
  (let* ((teams (pearl--all-teams))
         (team-name (completing-read
                     "Team: "
                     (pearl--completion-table-keep-order
                      (pearl--with-sentinel pearl--filter-any
                       (mapcar (lambda (tm) (cdr (assoc 'name tm))) teams)))
                     nil t))
         (team-id (and (not (pearl--filter-sentinel-value-p team-name))
                       (pearl--get-team-id-by-name team-name)))
         (open (pearl--read-yes-no "Open issues only? "))
         ;; Multi-select, like the Labels prompt: pick one or several states.
         ;; One picked -> a string (`:state' scalar); several -> a list
         ;; (`state.name.in'); none -> no state constraint.
         (state (and team-id
                     (let ((picked
                            (cl-remove
                             pearl--filter-any
                             (completing-read-multiple
                              "States (comma-separated): "
                              (pearl--completion-table-keep-order
                               (pearl--with-sentinel pearl--filter-any
                                (mapcar (lambda (st) (cdr (assoc 'name st)))
                                        (pearl--team-states team-id))))
                              nil t)
                             :test #'string=)))
                       (cond ((null picked) nil)
                             ((= 1 (length picked)) (car picked))
                             (t picked)))))
         (project (and team-id
                       (let ((p (completing-read
                                 "Project: "
                                 (pearl--completion-table-keep-order
                                  (pearl--with-sentinel pearl--filter-any
                                   (pearl--team-collection-names 'projects team-id)))
                                 nil t)))
                         ;; The :project filter compiles to project.id.eq, so
                         ;; resolve the picked name to its id before passing.
                         (unless (pearl--filter-sentinel-value-p p)
                           (pearl--resolve-team-id 'projects p team-id)))))
         (labels (and team-id
                      ;; `[ Any. ]' alongside real labels is redundant, so
                      ;; filter the sentinel out of the result.  A result of
                      ;; only-sentinel (or empty) means "no label constraint."
                      (cl-remove pearl--filter-any
                                 (completing-read-multiple
                                  "Labels (comma-separated): "
                                  (pearl--completion-table-keep-order
                                   (pearl--with-sentinel pearl--filter-any
                                    (pearl--team-collection-names 'labels team-id)))
                                  nil t)
                                 :test #'string=)))
         (assignee (let ((choice (completing-read
                                  "Assignee: "
                                  (pearl--completion-table-keep-order
                                   (list pearl--filter-any "me" "member"))
                                  nil t)))
                     (pcase choice
                       ("me" :me)
                       ("member"
                        (and team-id
                             (let ((name (completing-read
                                          "Member: "
                                          (pearl--team-collection-names 'members team-id)
                                          nil t)))
                               (unless (string-empty-p name)
                                 (pearl--resolve-team-id 'members name team-id)))))
                       (_ nil)))))
    ;; The :team filter compiles to team.key.eq, so look the picked name up
    ;; in the teams alist and pass its key (not the display name).
    (pearl--assemble-filter
     (and (not (pearl--filter-sentinel-value-p team-name))
          (cdr (assoc 'key
                      (cl-find team-name teams
                               :key (lambda (tm) (cdr (assoc 'name tm)))
                               :test #'string=))))
     open state project labels assignee)))

(defun pearl--delete-saved-query-local (name)
  "Remove NAME from `pearl-local-views' and persist via Customize.
The unconditional persistence path shared by the local-only delete and
the synced-entry unlink branch."
  (setq pearl-local-views
        (cl-remove name pearl-local-views :key #'car :test #'string=))
  (customize-save-variable 'pearl-local-views pearl-local-views))

;;;###autoload
(defun pearl-delete-local-view (name)
  "Delete the local view NAME from `pearl-local-views' after confirmation.
Interactively, completes over the configured query names with
`pearl--filter-cancel' at the top.  Local-only entries are removed from
the customized list and persisted via `customize-save-variable'; entries
that carry a `:linear-view-id' (i.e. were synced up to Linear) trigger a
second yes-or-no prompt for whether to also delete the linked Linear
view (=customViewDelete=).  Picking NO at the second prompt unlinks the
entry but leaves the Linear view in place; picking YES calls
=customViewDelete= and, on API failure, asks whether to drop the local
entry anyway (which leaves the Linear view orphaned -- the message names
the id so it can be deleted by hand)."
  (interactive
   (list (if (null pearl-local-views)
             (user-error "No local views to delete")
           (completing-read
            "Delete local view: "
            (pearl--completion-table-keep-order
             (pearl--with-sentinel pearl--filter-cancel
              (mapcar #'car pearl-local-views)))
            nil t))))
  (cond
   ((pearl--filter-sentinel-value-p name)
    (message "Cancelled; no local view deleted"))
   ((not (assoc name pearl-local-views))
    (user-error "No local view named %s" name))
   ((progn
      ;; Refuse a cross-account entry before the confirm or any customViewDelete:
      ;; deleting under the wrong account could target the wrong remote workspace.
      (pearl--require-local-view-account name (cdr (assoc name pearl-local-views)))
      (not (yes-or-no-p (format "Delete local view %s? " name))))
    (message "Kept local view %s" name))
   (t
    (let ((view-id (plist-get (cdr (assoc name pearl-local-views))
                              :linear-view-id)))
      (cond
       ;; Local-only entry: unchanged behavior.
       ((null view-id)
        (pearl--delete-saved-query-local name)
        (message "Deleted local view %s" name))
       ;; Synced entry: ask whether to also drop the Linear view.
       ((yes-or-no-p
         (format "Also delete the linked Linear view (\"%s\")? " name))
        (pearl--delete-saved-query-do-linear-delete name view-id))
       (t
        ;; Unlink only: drop the local entry, leave the Linear view alone.
        (pearl--delete-saved-query-local name)
        (message "Deleted local view %s; Linear view kept (id %s)"
                 name view-id)))))))

(defun pearl--delete-saved-query-do-linear-delete (name view-id)
  "Call customViewDelete on VIEW-ID and remove NAME locally on success.
On API failure, ask whether to drop the local entry anyway; if accepted,
the message names the orphan view id so the user can delete it in Linear
by hand."
  (pearl--progress "Deleting Linear view for %s..." name)
  (let* ((result (pearl--sync-saved-query-await
                  #'pearl--customview-delete-async view-id))
         (success (plist-get result :success)))
    (cond
     (success
      (pearl--delete-saved-query-local name)
      (message "Deleted local view %s and removed view from Linear" name))
     ((plist-get result :timeout)
      (message
       "Delete of Linear view for %s timed out after %ds; local view left in place -- the delete may still have completed (view id %s) -- re-run after the network recovers."
       name pearl-request-timeout view-id))
     ((yes-or-no-p
       (format
        "Linear delete failed (%s).  Drop the local entry anyway? "
        (or (plist-get result :error) "unknown error")))
      (pearl--delete-saved-query-local name)
      (message
       "Deleted local view %s; Linear view is orphaned (id %s, delete manually)"
       name view-id))
     (t
      (message "Kept local view %s; Linear view also untouched" name)))))

(defun pearl--save-local-view (name filter-plist &optional sort order)
  "Save FILTER-PLIST as local view NAME, preserving an existing entry's metadata.
On an existing entry, replaces only `:filter' (and `:sort' / `:order' when
non-nil) and keeps every other key -- `:linear-view-id', `:linear-view-team-id',
`:linear-view-shared', `:linear-view-url', `:linear-view-synced-at', `:account',
and `:copied-from-view-id'.  A new entry is stamped with the active account's
name under `:account' when `pearl-accounts' is configured.  Persists
`pearl-local-views' via Customize.  This is the metadata-preserving writer;
unlike a naive rebuild it never drops a published view's tracking link."
  (let* ((existing (assoc name pearl-local-views))
         (spec (and existing (copy-sequence (cdr existing)))))
    (setq spec (plist-put spec :filter filter-plist))
    (when sort (setq spec (plist-put spec :sort sort)))
    (when order (setq spec (plist-put spec :order order)))
    (unless existing
      (when pearl-accounts
        (let ((active (plist-get (pearl--current-account-context) :name)))
          (when active (setq spec (plist-put spec :account active))))))
    (setq pearl-local-views
          (cons (cons name spec)
                (assoc-delete-all name (copy-sequence pearl-local-views))))
    (ignore-errors
      (customize-save-variable 'pearl-local-views pearl-local-views))))

(defun pearl--require-local-view-account (name spec)
  "Refuse when local view NAME (SPEC plist) belongs to a non-active account.
Inert in legacy single-account mode and for an untagged entry -- the same
guard `pearl-run-local-view' applies, shared so every read/mutate command
enforces it identically.  Returns the active account name, or nil in legacy
mode, so callers can stamp newly-created entries."
  (let ((v-account (plist-get spec :account)))
    (cond
     ((and pearl-accounts v-account)
      (let ((active (plist-get (pearl--current-account-context) :name)))
        (unless (string-equal v-account active)
          (user-error "Local view '%s' belongs to %s; switch accounts first"
                      name v-account))
        active))
     (pearl-accounts (plist-get (pearl--current-account-context) :name))
     (t nil))))

(defun pearl--resolve-local-view-name (proposed &optional current)
  "Resolve a local-view name collision for PROPOSED, returning the final name.
CURRENT, when given, is the entry's existing name -- keeping the same name on
an edit is not a collision.  When PROPOSED already names a different local
view, prompts Replace / Rename / Cancel (default Rename); Replace returns the
name to overwrite, Cancel returns nil.  Used by create, edit-rename, and
copy-down so the three share one collision policy."
  (let ((name proposed) (done nil) (result nil))
    (while (not done)
      (cond
       ((or (null name) (string-empty-p name))
        (setq done t result nil))
       ((or (and current (string-equal name current))
            (not (assoc name pearl-local-views)))
        (setq done t result name))
       (t
        (pcase (completing-read
                (format "Local view \"%s\" already exists: " name)
                '("Rename" "Replace" "Cancel") nil t nil nil "Rename")
          ("Replace" (setq done t result name))
          ("Cancel"  (setq done t result nil))
          (_ (setq name (read-string "New local-view name: ")))))))
    result))

;;; Saved-query -> Linear view sync (see docs/saved-query-sync-spec.org)

(defun pearl--sync-scope-label (team-name shared)
  "Return the display label for the scope identified by TEAM-NAME and SHARED.
TEAM-NAME is either \"Personal\" or a real team name.  SHARED is t
\(visible to the team) or nil (only the viewer).  The single source of
truth so the picker, the re-sync path, and the success message all
agree byte-for-byte."
  (if (equal team-name "Personal")
      "[ Personal, only I see it ]"
    (format "[ Team: %s, %s ]"
            team-name
            (if shared "visible to the team" "only I see it"))))

(defun pearl--sync-scope-candidates (teams filter-team-key)
  "Build the (DISPLAY . PLIST) candidate list for the scope-and-visibility prompt.
TEAMS is the team alist list returned by `pearl--all-teams' (each carries
`id', `key', `name').  FILTER-TEAM-KEY is the local view's filter `:team'
value (a team key string) or nil.

Each candidate's PLIST is `(:team-id ID-OR-NIL :team-name NAME :shared
BOOL)'.  The default candidate is first: `[ Team: <X>, visible to the
team ]' when FILTER-TEAM-KEY names a known team, else `[ Personal, only
I see it ]'.  Remaining candidates appear in a stable order -- the
Personal row, then each team alphabetically with the shared row first.
The meaningless `Personal + shared' combination is absent."
  (let* ((sorted-teams (sort (copy-sequence teams)
                             (lambda (a b)
                               (string< (or (cdr (assoc 'name a)) "")
                                        (or (cdr (assoc 'name b)) "")))))
         (filter-team
          (and filter-team-key
               (seq-find (lambda (tm)
                           (equal filter-team-key (cdr (assoc 'key tm))))
                         sorted-teams)))
         (personal-row
          (cons (pearl--sync-scope-label "Personal" nil)
                (list :team-id nil :team-name "Personal" :shared nil)))
         (team-rows
          (cl-mapcan
           (lambda (tm)
             (let ((name (cdr (assoc 'name tm)))
                   (id (cdr (assoc 'id tm))))
               (list
                (cons (pearl--sync-scope-label name t)
                      (list :team-id id :team-name name :shared t))
                (cons (pearl--sync-scope-label name nil)
                      (list :team-id id :team-name name :shared nil)))))
           sorted-teams))
         (all-rows (cons personal-row team-rows))
         (default-display
          (if filter-team
              (pearl--sync-scope-label (cdr (assoc 'name filter-team)) t)
            (car personal-row)))
         (default-row (cl-find default-display all-rows
                               :key #'car :test #'string=)))
    (if default-row
        (cons default-row (cl-remove default-row all-rows :test #'eq))
      all-rows)))

(defun pearl--find-view-by-name-in-scope (views name team-id shared)
  "Return the first VIEW in VIEWS whose name, team scope, and shared flag match.
NAME is the view name.  TEAM-ID is the team UUID the candidate should be
scoped to (nil for a personal/workspace view).  SHARED is t or nil.
Returns the matching view alist or nil."
  (let ((shared-canonical (if shared t :json-false)))
    (seq-find
     (lambda (v)
       (and (string= name (or (cdr (assoc 'name v)) ""))
            (let ((view-team-id (cdr (assoc 'id (cdr (assoc 'team v))))))
              (equal view-team-id team-id))
            (let ((view-shared (cdr (assoc 'shared v))))
              ;; Linear returns `t' or `:json-false'; either match the canonical
              ;; form, OR nil counts as personal/private.
              (cond ((eq shared-canonical t) (eq view-shared t))
                    (t (or (eq view-shared :json-false) (null view-shared)))))))
     views)))

(defun pearl--save-query-mark-synced (name team-id shared view-id &optional view-url)
  "Persist the sync metadata for local view NAME.
TEAM-ID is the team UUID or nil (personal scope).  SHARED is t or nil.
VIEW-ID is the Linear custom view UUID returned by the API.  VIEW-URL,
when provided, is the view's Linear web URL so
`pearl-open-current-view-in-linear' can open the rendered buffer's
source view in the browser; omit on a re-sync where the URL is
unavailable to leave the prior `:linear-view-url' untouched.

Adds or overwrites `:linear-view-id', `:linear-view-team-id',
`:linear-view-shared', `:linear-view-synced-at', and (when VIEW-URL is
non-nil) `:linear-view-url' on the entry, then persists
`pearl-local-views' via Customize.  Signals `user-error' when NAME
isn't in `pearl-local-views'."
  (let ((entry (assoc name pearl-local-views)))
    (unless entry
      (user-error "No local view named %s" name))
    ;; Copy the existing spec and plist-put each sync key on top.  Earlier
    ;; versions rebuilt the spec from `:filter', `:sort', `:order' + the four
    ;; sync keys, which silently dropped any other key on the entry -- a
    ;; future `:description', a user-added annotation, or any new schema
    ;; field would vanish on every re-sync.  Copy-then-put preserves
    ;; everything the user (or future pearl code) attached.
    (let* ((synced-at (format-time-string "%Y-%m-%dT%H:%M:%SZ" nil t))
           (new-spec (copy-sequence (cdr entry))))
      (setq new-spec (plist-put new-spec :linear-view-id view-id))
      (setq new-spec (plist-put new-spec :linear-view-team-id team-id))
      (setq new-spec (plist-put new-spec :linear-view-shared shared))
      (setq new-spec (plist-put new-spec :linear-view-synced-at synced-at))
      ;; Only touch :linear-view-url when this call supplied one; a re-sync
      ;; whose API response somehow lacks the URL must not erase the prior.
      (when view-url
        (setq new-spec (plist-put new-spec :linear-view-url view-url)))
      (setq pearl-local-views
            (cons (cons name new-spec)
                  (assoc-delete-all name (copy-sequence pearl-local-views))))
      (customize-save-variable 'pearl-local-views pearl-local-views))))

(defun pearl--sync-record-or-orphan-error (name team-id shared view-id verb
                                                &optional scope-label view-url)
  "Persist sync metadata for NAME, or report an orphan view on persist failure.
TEAM-ID, SHARED, VIEW-ID match the just-completed sync (see
`pearl--save-query-mark-synced').  VERB is the past-tense action word
shown in the success message (\"Synced\" for create, \"Updated\" for
update).  SCOPE-LABEL is the optional scope-and-visibility display
string appended in brackets.  VIEW-URL, when provided, is the view's
Linear web URL stored alongside the rest of the sync metadata so
`pearl-open-current-view-in-linear' can dispatch to it.

Returns t on success, nil on failure.  On failure the message names
VIEW-ID explicitly so the user can find the orphan in Linear or re-sync
with Replace to reconcile -- the API call already succeeded; only the
local link couldn't be saved."
  (condition-case err
      (progn
        (pearl--save-query-mark-synced name team-id shared view-id view-url)
        (message "%s %s to Linear (view id %s)%s"
                 verb name view-id
                 (if scope-label (format " [%s]" scope-label) ""))
        t)
    (error
     (message
      "View %s on Linear as %s but local link couldn't be saved (%s). Re-run `pearl-publish-local-view' and pick Replace to reconcile."
      (if (string= verb "Updated") "updated" "created")
      view-id (error-message-string err))
     nil)))

(defun pearl--sync-saved-query-pick-scope (filter-plist)
  "Prompt the user for the destination scope of a sync-up.
FILTER-PLIST is the local view's authoring filter (used to derive the
default candidate).  Returns `(DISPLAY . PLIST)', or nil when the user
cancels via the cancel sentinel.  DISPLAY is the candidate string the
user picked; PLIST is `(:team-id ID-OR-NIL :team-name NAME :shared
BOOL)'.  Returning both halves saves the caller from rebuilding the
candidate list to look the display string back up via rassoc."
  (let* ((teams (pearl--all-teams))
         (cands (pearl--sync-scope-candidates teams (plist-get filter-plist :team)))
         (displays (mapcar #'car cands))
         (choice (completing-read
                  "Where does this view live? "
                  (pearl--completion-table-keep-order
                   (pearl--with-sentinel pearl--filter-cancel displays))
                  nil t)))
    (unless (pearl--filter-sentinel-value-p choice)
      (assoc choice cands))))

(defun pearl--sync-saved-query-collision-action (name)
  "Prompt the user when a view named NAME already exists in the chosen scope.
Returns one of the symbols `replace', `rename', `cancel'."
  (let ((choice (completing-read
                 (format "A view named %s already exists in this scope; what now? "
                         name)
                 (pearl--completion-table-keep-order
                  (list "Replace" "Rename" "Cancel"))
                 nil t nil nil "Replace")))
    (pcase choice
      ("Replace" 'replace)
      ("Rename" 'rename)
      (_ 'cancel))))

(defun pearl--sync-saved-query-await (async-fn &rest args)
  "Run the async helper ASYNC-FN with ARGS, busy-waiting for its callback.
ASYNC-FN is one of the `pearl--customview-*-async' helpers (create,
update, or delete) -- each ends by invoking a callback appended to ARGS
with a result plist.  Returns that plist on completion, or
`(:success nil :timeout t)' if the wait elapsed without the callback
firing -- callers can distinguish a timeout from a Linear-side rejection
so the user isn't told the API refused something that never reached it."
  (let ((done nil) (result nil))
    (apply async-fn
           (append args
                   (list (lambda (r) (setq result r done t)))))
    (pearl--wait-for (lambda () done))
    (if done result (list :success nil :timeout t))))

;;;###autoload
(defun pearl-publish-local-view (name)
  "Publish the local view NAME to Linear as a Custom View.
First publish prompts for the destination scope (team and visibility),
then calls `customViewCreate'.  Re-publishing an already-published entry calls
`customViewUpdate' against the stored view id -- the stored team and
shared flag stay (use Replace/Rename below to reset them).  A same-name
collision in the chosen scope prompts Replace / Rename / Cancel.  On
success the entry is extended with the four `:linear-view-*' keys via
`customize-save-variable'.  On a successful API call followed by a
persist failure, the message names the orphan view's id explicitly so
the user can re-publish with Replace to reconcile."
  (interactive
   (list (if (null pearl-local-views)
             (user-error "No local views to publish")
           (completing-read
            "Publish local view: "
            (pearl--completion-table-keep-order
             (pearl--with-sentinel pearl--filter-cancel
                                   (mapcar #'car pearl-local-views)))
            nil t))))
  (when (pearl--filter-sentinel-value-p name)
    (user-error "Cancelled; no local view published"))
  (pearl--require-account-context t)
  (let ((entry (assoc name pearl-local-views)))
    (unless entry
      (user-error "No local view named %s" name))
    ;; Refuse a cross-account entry before any customViewCreate/Update: publishing
    ;; under the wrong account would create the view in the wrong workspace.
    (pearl--require-local-view-account name (cdr entry))
    (let* ((spec (cdr entry))
           (filter-plist (plist-get spec :filter))
           (existing-view-id (plist-get spec :linear-view-id))
           (existing-team-id (plist-get spec :linear-view-team-id))
           ;; Normalize to a strict boolean.  Stored values can be t, nil, or
           ;; `:json-false' (from a prior cycle through the JSON layer); the
           ;; downstream `(if shared t :json-false)' encoder treats every
           ;; non-nil value as truthy, so an unnormalized `:json-false' would
           ;; silently flip a personal view to team-shared.
           (existing-shared (eq (plist-get spec :linear-view-shared) t))
           (filter-data (pearl--build-issue-filter filter-plist))
           (target-name name))
      ;; Linear's CustomViewCreateInput.filterData expects a JSON object.  An
      ;; empty filter plist compiles to nil, which JSON-encodes as `null' and
      ;; the API rejects with an opaque error.  Refuse early -- before we
      ;; prompt the user for scope -- so they see what's wrong instead of
      ;; clicking through the scope picker only to hit "Linear refused".
      (unless filter-data
        (user-error
         "Local view %s has no filter constraints; Linear views need at least one constraint -- add one and re-sync"
         name))
      (let ((scope-pair
             (if existing-view-id
                 ;; Re-sync: build the scope pair from stored metadata,
                 ;; resolving the team name from id (defaults to "Personal"
                 ;; when team-id is nil OR the team is no longer in the
                 ;; cache).  The label comes from the same helper the
                 ;; picker uses so the success message matches what the
                 ;; user would have seen on first sync.
                 (let* ((team-name (or (and existing-team-id
                                            (cdr (assoc 'name
                                                        (seq-find
                                                         (lambda (tm)
                                                           (equal existing-team-id
                                                                  (cdr (assoc 'id tm))))
                                                         (pearl--all-teams)))))
                                       "Personal")))
                   (cons (pearl--sync-scope-label team-name existing-shared)
                         (list :team-id existing-team-id
                               :team-name team-name
                               :shared existing-shared)))
               ;; First-time sync: pick-scope returns (display . plist) or
               ;; nil (cancel).
               (pearl--sync-saved-query-pick-scope filter-plist))))
        (unless scope-pair
          (user-error "Cancelled; no local view published"))
        ;; Validate the filter at the boundary so a malformed entry surfaces
        ;; before the API call.
        (pearl--validate-issue-filter filter-plist)
        (let* ((scope-label (car scope-pair))
               (scope (cdr scope-pair))
               (team-id (plist-get scope :team-id))
               (shared (plist-get scope :shared)))
          (cond
           ;; First-time sync: check for a same-name collision in the chosen
           ;; scope and either update-by-id (Replace), re-prompt (Rename), or
           ;; bail (Cancel).
           ((null existing-view-id)
            (let* ((collision (pearl--find-view-by-name-in-scope
                               (pearl--custom-views t)
                               target-name team-id shared))
                   (action (and collision
                                (pearl--sync-saved-query-collision-action
                                 target-name))))
              (pcase action
                ('cancel
                 (message "Cancelled; %s left unpublished" target-name))
                ('rename
                 (setq target-name
                       (read-string (format "New view name (was %s): " name)))
                 (when (or (null target-name) (string-empty-p target-name))
                   (user-error "Cancelled; no name entered"))
                 (pearl--sync-saved-query-do-create
                  name target-name team-id shared filter-data scope-label))
                ('replace
                 (pearl--sync-saved-query-do-update
                  name (cdr (assoc 'id collision))
                  team-id shared filter-data scope-label))
                (_
                 ;; No collision -- straight create.
                 (pearl--sync-saved-query-do-create
                  name target-name team-id shared filter-data scope-label)))))
           ;; Re-sync: update by stored id; no collision check (the id targets
           ;; the existing view directly).
           (t
            (pearl--sync-saved-query-do-update
             name existing-view-id team-id shared filter-data scope-label))))))))

(defun pearl--sync-saved-query-do-create (name target-name team-id shared
                                               filter-data scope-label)
  "Create a Linear view from local view NAME, persisting the link on success.
TARGET-NAME is the view name to send to Linear (usually NAME, but may
differ when the user picked Rename to dodge a collision).  TEAM-ID,
SHARED, FILTER-DATA are the Linear API inputs.  SCOPE-LABEL is the
scope-and-visibility display string for the success message."
  (pearl--progress "Creating Linear view %s..." target-name)
  (let* ((result (pearl--sync-saved-query-await
                  #'pearl--customview-create-async
                  target-name team-id shared filter-data))
         (success (plist-get result :success))
         (view (and success (plist-get result :view)))
         (view-id (and view (cdr (assoc 'id view))))
         (view-url (and view-id (pearl--view-url view-id))))
    (cond
     ((and success view-id)
      (pearl--sync-record-or-orphan-error
       name team-id shared view-id "Published" scope-label view-url))
     ((plist-get result :timeout)
      (message
       "Publish of %s timed out after %ds; the create may still complete on Linear -- re-run and pick Replace to reconcile if a duplicate appears."
       name pearl-request-timeout))
     (t
      (message "Failed to publish %s: %s" name
               (or (plist-get result :error) "Linear refused the create"))))))

;;;###autoload
(defun pearl-publish-current-view ()
  "Publish the active buffer's local view to Linear as a Custom View.
Convenience wrapper.  Reads `#+LINEAR-SOURCE' from the current buffer.
When it's a `:type filter' source whose `:name' matches a local view,
dispatches to `pearl-publish-local-view' with that name pre-filled.
Otherwise refuses with a clear message: the source is already a Linear
view (no publish needed), the filter is transient (no name to publish
under), or no local view matches the recorded name.

Bound under \\='C-; L f P\\=' inside `pearl-mode' buffers; reachable
through the transient as the `U' (upload) entry in the Fetch group."
  (interactive)
  (pearl--require-account-context t)
  (let* ((source (pearl--read-active-source))
         (type (and source (plist-get source :type)))
         (name (and source (plist-get source :name))))
    (cond
     ((null source)
      (user-error "No active source header in this buffer; nothing to publish"))
     ((eq type 'view)
      (user-error "Source is already a Linear view (%s); no publish needed"
                  (or name "<unnamed>")))
     ((not (eq type 'filter))
      (user-error "Unsupported source type %s; only filter sources can be published"
                  type))
     ((or (null name) (and (stringp name) (string-blank-p name)))
      (user-error "Source has no name; save it first via pearl-list-issues-filtered then re-publish"))
     ((not (assoc name pearl-local-views))
      (user-error "No local view named %s; save it first via pearl-list-issues-filtered"
                  name))
     (t
      (pearl-publish-local-view name)))))

(defun pearl--sync-saved-query-do-update (name view-id team-id shared
                                               filter-data scope-label)
  "Update an existing Linear view from local view NAME by VIEW-ID.
TEAM-ID, SHARED, FILTER-DATA are the Linear API inputs.  SCOPE-LABEL is
the scope-and-visibility display string for the success message."
  (pearl--progress "Updating Linear view %s..." name)
  (let* ((update-input (append (list (cons "filterData" filter-data)
                                     (cons "shared" (if shared t :json-false)))
                               (when team-id
                                 (list (cons "teamId" team-id)))))
         (result (pearl--sync-saved-query-await
                  #'pearl--customview-update-async
                  view-id update-input))
         (success (plist-get result :success))
         (view-url (and view-id (pearl--view-url view-id))))
    (cond
     (success
      (pearl--sync-record-or-orphan-error
       name team-id shared view-id "Updated" scope-label view-url))
     ((plist-get result :timeout)
      (message
       "Update of Linear view for %s timed out after %ds; the update may still apply -- refresh in Linear to confirm."
       name pearl-request-timeout))
     (t
      (message "Failed to update Linear view for %s: %s" name
               (or (plist-get result :error) "Linear refused the update"))))))

;;;###autoload
(defun pearl-list-issues-filtered (filter-plist &optional save-name)
  "Build an ad-hoc issue filter interactively, run it, and render it.
Interactively, completes each dimension from the chosen team's fetched
projects/states/labels (so a typo can't produce a confusing empty result), and
offers to save it as a local view.  FILTER-PLIST is the authoring filter;
SAVE-NAME, when given, persists it via `pearl--save-local-view'.  For a
deliberate create use `pearl-create-local-view'; this is the ad-hoc path with
a save offer at the end."
  (interactive
   (list (pearl--read-filter-interactively)
         (when (pearl--read-yes-no "Save this as a local view so you can re-run it (not published to Linear)? ")
           (read-string "Name for this local view: "))))
  ;; Validate before saving or running, so a bad filter never gets persisted
  ;; or run -- the command boundary is where the clear error belongs.
  (pearl--validate-issue-filter filter-plist)
  (when (and save-name (not (string-empty-p save-name)))
    (pearl--save-local-view save-name filter-plist))
  (let ((source (list :type 'filter
                      :name (if (and save-name (not (string-empty-p save-name)))
                                save-name
                              "Ad-hoc filter")
                      :filter filter-plist)))
    (pearl--progress "Running ad-hoc filter...")
    (pearl--query-issues-async
     (pearl--build-issue-filter filter-plist)
     (lambda (result) (pearl--render-query-result result source)))))

;;;###autoload
(defun pearl-create-local-view ()
  "Build a filter interactively, name it, and save it as a local view.
Completes each dimension from the chosen team's fetched values, then prompts a
name (Replace / Rename / Cancel on a collision), persists via
`pearl--save-local-view' (stamping the active account under `pearl-accounts'),
and runs the new view.  The deliberate create path;
`pearl-list-issues-filtered' is the ad-hoc run that merely offers to save."
  (interactive)
  (let ((filter-plist (pearl--read-filter-interactively)))
    (pearl--validate-issue-filter filter-plist)
    (let ((name (pearl--resolve-local-view-name
                 (read-string "Name for this local view: "))))
      (unless name (user-error "Cancelled; no local view created"))
      (pearl--save-local-view name filter-plist)
      (let ((source (list :type 'filter :name name :filter filter-plist)))
        (pearl--progress "Running local view %s..." name)
        (pearl--query-issues-async
         (pearl--build-issue-filter filter-plist)
         (lambda (result) (pearl--render-query-result result source)))))))

(defun pearl--read-sort-or-keep (current)
  "Read a sort key, defaulting to CURRENT.  Returns a symbol, or nil for none."
  (let ((choice (completing-read
                 "Sort: "
                 (pearl--completion-table-keep-order
                  '("keep" "updated" "created" "priority" "title" "none"))
                 nil t nil nil "keep")))
    (pcase choice ("keep" current) ("none" nil) (_ (intern choice)))))

(defun pearl--read-order-or-keep (current)
  "Read an order, defaulting to CURRENT.  Returns `asc', `desc', or nil."
  (let ((choice (completing-read
                 "Order: "
                 (pearl--completion-table-keep-order '("keep" "desc" "asc"))
                 nil t nil nil "keep")))
    (pcase choice ("keep" current) (_ (intern choice)))))

;;;###autoload
(defun pearl-edit-local-view (name)
  "Edit the local view NAME, preserving its non-edited metadata.
Refuses a cross-account entry.  Offers to rebuild the filter (otherwise keeps
the stored one), then prompts a new name (Replace / Rename / Cancel on a
collision; keeping the same name is fine), and a sort and order.  Saves through
`pearl--save-local-view', so a published view keeps its `:linear-view-*' link
and a copied-down view keeps its `:copied-from-view-id'."
  (interactive
   (list (if (null pearl-local-views)
             (user-error "No local views to edit")
           (completing-read "Edit local view: "
                            (mapcar #'car pearl-local-views) nil t))))
  (let ((entry (assoc name pearl-local-views)))
    (unless entry (user-error "No local view named %s" name))
    (let ((spec (cdr entry)))
      (pearl--require-local-view-account name spec)
      (let* ((filter (if (pearl--read-yes-no "Rebuild the filter? " "no")
                         (pearl--read-filter-interactively)
                       (plist-get spec :filter)))
             (sort (pearl--read-sort-or-keep (plist-get spec :sort)))
             (order (pearl--read-order-or-keep (plist-get spec :order)))
             (new-name (pearl--resolve-local-view-name
                        (read-string "Name: " name) name)))
        (pearl--validate-issue-filter filter)
        (unless new-name (user-error "Cancelled; no edit saved"))
        ;; On rename, carry the existing spec to the new name first so the
        ;; metadata survives, then let `pearl--save-local-view' update it.
        (unless (string-equal new-name name)
          (setq pearl-local-views
                (cons (cons new-name (copy-sequence spec))
                      (assoc-delete-all name (copy-sequence pearl-local-views)))))
        (pearl--save-local-view new-name filter sort order)
        (message "Saved local view %s" new-name)))))

(defun pearl--cap-issue-list-comments (issue)
  "Cap a bulk-list ISSUE's fetched comments and record a `:comment-count' marker.
The list/view fetch pulls the newest `pearl-list-comments-count-cap'+1 comments
newest-first; keep the newest `pearl-list-comments-shown' for display (the
renderer re-sorts those oldest-first) and set `:comment-count' to (:shown N
:total M :overflow BOOL), where the total is exact up to the cap and overflows
past it.  An issue with no fetched comments is returned unchanged, so it renders
no Comments subtree."
  (let ((comments (plist-get issue :comments)))
    (if (null comments)
        issue
      (let* ((n (length comments))
             (cap pearl-list-comments-count-cap)
             (overflow (> n cap))
             (total (if overflow cap n))
             (shown (seq-take comments pearl-list-comments-shown)))
        (plist-put
         (plist-put (copy-sequence issue) :comments shown)
         :comment-count (list :shown (length shown) :total total :overflow overflow))))))

(defun pearl--render-query-result (result source)
  "Render a query RESULT into the active file, tagged with SOURCE.
Normalizes the raw nodes, writes them via `pearl--update-org-from-issues'
with SOURCE and the truncation flag, and reports the outcome.  The one render
boundary shared by list-issues, the ad-hoc filter, local views, views, and
refresh."
  (pcase (pearl--query-result-status result)
    ('ok
     (let ((issues (pearl--sort-issues
                    (mapcar (lambda (n)
                              (pearl--cap-issue-list-comments
                               (pearl--normalize-issue n)))
                            (pearl--query-result-issues result))
                    (plist-get source :sort)
                    (plist-get source :order)))
           (truncated (pearl--query-result-truncated-p result)))
       (condition-case err
           (progn
             (pearl--update-org-from-issues issues source truncated)
             (message "Linear: wrote %d issue%s%s"
                      (length issues)
                      (if (= 1 (length issues)) "" "s")
                      (if truncated
                          (format " (stopped at the %d-page limit; raise `pearl-max-issue-pages')"
                                  pearl-max-issue-pages)
                        "")))
         (error
          (pearl--log "Error updating org file: %s" (error-message-string err))
          (message "Error updating the Linear org file: %s"
                   (error-message-string err))))))
    ('empty
     (message "Linear: no issues match %s (file left unchanged)"
              (pearl--source-name source)))
    (_
     (message "Linear: %s"
              (or (pearl--query-result-message result)
                  "could not fetch issues")))))

(defun pearl--subtree-dirty-p ()
  "Return non-nil when the issue subtree at point has unpushed body edits.
Compares the current Org body against `LINEAR-DESC-ORG-SHA256', the hash of the
body as it was rendered at the last fetch.  This is an Org-to-Org comparison: it
does not round-trip through markdown, so a description whose markdown does not
survive md->org->md (headings, single-asterisk emphasis) is not mistaken for a
local edit.  This is what lets a refresh protect a locally edited description
from being clobbered while still re-rendering the untouched ones.

For subtrees rendered before this hash existed (no `LINEAR-DESC-ORG-SHA256'),
fall back to the older markdown-round-trip comparison; those migrate to the
Org-baseline hash the next time the subtree is re-rendered."
  (let ((org-hash (org-entry-get nil "LINEAR-DESC-ORG-SHA256")))
    (if org-hash
        (not (string= (secure-hash 'sha256 (pearl--entry-body-at-point)) org-hash))
      (let ((stored (org-entry-get nil "LINEAR-DESC-SHA256"))
            (local-md (pearl--org-to-md (pearl--entry-body-at-point))))
        (not (string= (secure-hash 'sha256 local-md) (or stored "")))))))

(defun pearl--issue-subtree-markers ()
  "Return an alist of (LINEAR-ID . marker) for every issue heading in the buffer.
Each marker sits at the start of an issue heading -- one carrying its own
`LINEAR-ID' property.  Comment headings carry `LINEAR-COMMENT-ID' instead and
have no `LINEAR-ID', so they are skipped.  Markers (not raw positions) so they
track correctly across the in-place inserts and deletes the merge performs."
  (let (markers)
    (save-excursion
      (goto-char (point-min))
      (while (re-search-forward "^\\*+ " nil t)
        (save-excursion
          (beginning-of-line)
          (let ((id (org-entry-get nil "LINEAR-ID")))
            (when (and id (not (string-empty-p id)))
              ;; Insertion type t matters here: replacing an earlier subtree
              ;; deletes then reinserts at its start, collapsing a later
              ;; marker onto that point.  A type-nil marker would stay before
              ;; the reinserted text and get stranded on the wrong heading; a
              ;; type-t marker advances past it to its own heading.
              (push (cons id (copy-marker (point) t)) markers))))))
    (nreverse markers)))

;;; Dirty detection (the save model's local scanners)

(defun pearl--comment-dirty-p ()
  "Return non-nil when the comment body at point differs from its last fetch.
An Org-to-Org comparison against `LINEAR-COMMENT-ORG-SHA256' (the rendered body
as fetched), so a comment whose markdown does not survive md->org->md (a heading
or single-asterisk emphasis) is not mistaken for a local edit -- the same fix
`pearl--subtree-dirty-p' applies to descriptions.  Comments rendered before that
baseline existed fall back to the older markdown-round-trip comparison against
`LINEAR-COMMENT-SHA256'; they migrate on the next re-render."
  (let ((org-hash (org-entry-get nil "LINEAR-COMMENT-ORG-SHA256")))
    (if org-hash
        (not (string= (secure-hash 'sha256 (pearl--entry-body-at-point)) org-hash))
      (let ((stored (or (org-entry-get nil "LINEAR-COMMENT-SHA256") "")))
        (not (string= (secure-hash 'sha256 (pearl--org-to-md (pearl--entry-body-at-point)))
                      stored))))))

(defun pearl--changed-comment-candidates ()
  "Return comments under the issue at point whose body changed since fetch.
Each is a plist (:comment-id :author-id :marker).  Local only, via
`pearl--comment-dirty-p'.  A candidate only means the body differs; ownership is
decided later."
  (let (candidates)
    (save-excursion
      (pearl--goto-heading-or-error)
      (let ((issue-end (save-excursion (org-end-of-subtree t t) (point))))
        (while (and (outline-next-heading) (< (point) issue-end))
          (let ((cid (org-entry-get nil "LINEAR-COMMENT-ID")))
            (when (and cid (not (string-empty-p cid)) (pearl--comment-dirty-p))
              (push (list :comment-id cid
                          :author-id (org-entry-get nil "LINEAR-COMMENT-AUTHOR-ID")
                          :marker (point-marker))
                    candidates))))))
    (nreverse candidates)))

(defun pearl--priority-number-at-point ()
  "Return the Linear priority (0-4) implied by the heading cookie at point.
A/B/C/D map to Urgent/High/Medium/Low (1-4); no cookie is None (0).  A cookie
present but outside A-D (e.g. \\='[#E]\\=') is not a Linear priority: it signals
a `user-error' rather than silently mapping to None, which would clear the
issue's priority on save.  Linear has exactly five priorities, so A-D plus
no-cookie is the whole range."
  (save-excursion
    (org-back-to-heading t)
    (let ((case-fold-search nil))
      (if (re-search-forward "\\[#\\([A-Z]\\)\\]" (line-end-position) t)
          (let ((letter (match-string 1)))
            (or (cdr (assoc letter '(("A" . 1) ("B" . 2) ("C" . 3) ("D" . 4))))
                (user-error
                 (concat "Priority cookie [#%s] is not a Linear priority; "
                         "use A-D (A=Urgent, B=High, C=Medium, D=Low) "
                         "or no cookie for None")
                 letter)))
        0))))

(defun pearl--priority-dirty-p ()
  "Non-nil if the heading's priority cookie differs from `LINEAR-PRIORITY'.
A missing baseline (a legacy file rendered before this field) is not dirty -- a
refresh writes the baseline; the saver's missing-property guard covers the edge."
  (let ((base (org-entry-get nil "LINEAR-PRIORITY")))
    (and base
         (/= (pearl--priority-number-at-point) (string-to-number base)))))

(defun pearl--id-baseline-dirty-p (live-prop base-prop)
  "Non-nil if LIVE-PROP differs from its present baseline BASE-PROP at point.
A missing baseline is not dirty (see `pearl--priority-dirty-p')."
  (let ((base (org-entry-get nil base-prop)))
    (and base
         (not (string= (or (org-entry-get nil live-prop) "") base)))))

(defun pearl--label-ids-dirty-p ()
  "Non-nil if `LINEAR-LABEL-IDS' differs from `LINEAR-LABEL-IDS-SYNCED' as a set.
Order-insensitive (Linear label order is not meaningful).  A missing baseline is
not dirty."
  (let ((base (org-entry-get nil "LINEAR-LABEL-IDS-SYNCED")))
    (and base
         (not (equal (sort (split-string (or (org-entry-get nil "LINEAR-LABEL-IDS") "") " " t)
                           #'string<)
                     (sort (split-string base " " t) #'string<))))))

(defun pearl--state-keyword-cycled-p ()
  "Non-nil when the heading's TODO keyword no longer matches the synced state.
Network-free: compares `org-get-todo-state' against the slug of
`LINEAR-STATE-NAME' (`pearl--state-name-to-keyword').  A heading with no
keyword or no recorded state name can't be judged cycled, so it returns nil.
The concrete state id the keyword resolves to is determined in the saver
(`pearl--resolve-keyword-to-state'), not here -- this scan stays local."
  (let ((kw (org-get-todo-state))
        (name (org-entry-get nil "LINEAR-STATE-NAME")))
    (and kw name (not (string-empty-p name))
         (not (string= kw (pearl--state-name-to-keyword name))))))

(defun pearl--resolve-keyword-to-state (keyword team-id)
  "Resolve KEYWORD to a TEAM-ID workflow state by slug match.
Returns a plist (:id :name :type) for the first state -- by `position' -- whose
name slugifies to KEYWORD, or nil when none match (a stale or hand-typed
keyword).  Uses the cached team states; a failed or empty fetch yields nil."
  (let (best best-pos)
    (dolist (node (ignore-errors (pearl--team-states team-id)))
      (when (string= keyword (pearl--state-name-to-keyword (cdr (assoc 'name node))))
        (let ((pos (or (cdr (assoc 'position node)) most-positive-fixnum)))
          (when (or (null best) (< pos best-pos))
            (setq best (list :id (cdr (assoc 'id node))
                             :name (cdr (assoc 'name node))
                             :type (cdr (assoc 'type node)))
                  best-pos pos)))))
    best))

(defun pearl--issue-dirty-fields ()
  "Return the locally-changed fields of the issue subtree at point, no network.
A plist: `:title', `:description', `:priority', `:state', `:assignee', and
`:labels' are booleans; `:comment-candidates' is the list from
`pearl--changed-comment-candidates'.  The structured-field checks compare each
live value against its synced baseline (id/scalar only, no name resolution or
remote read).  `:state' has two arms: the picker arm (explicit
`LINEAR-STATE-ID' vs `LINEAR-STATE-ID-SYNCED') and the keyword-cycle arm
(`pearl--state-keyword-cycled-p' -- the keyword slug diverged from
`LINEAR-STATE-NAME'); either marks state dirty.  This is Phase A of the
two-phase save
scan -- comment ownership is classified separately once the viewer id is known
(see `pearl--classify-comment-candidates')."
  (save-excursion
    (pearl--goto-heading-or-error)
    (list :title (not (string= (secure-hash 'sha256 (pearl--issue-title-at-point))
                               (or (org-entry-get nil "LINEAR-TITLE-SHA256") "")))
          :description (pearl--subtree-dirty-p)
          :priority (pearl--priority-dirty-p)
          :state (or (pearl--id-baseline-dirty-p "LINEAR-STATE-ID" "LINEAR-STATE-ID-SYNCED")
                     (pearl--state-keyword-cycled-p))
          :assignee (pearl--id-baseline-dirty-p "LINEAR-ASSIGNEE-ID" "LINEAR-ASSIGNEE-ID-SYNCED")
          :labels (pearl--label-ids-dirty-p)
          :comment-candidates (pearl--changed-comment-candidates))))

(defun pearl--classify-comment-candidates (candidates viewer-id)
  "Split CANDIDATES into own dirty comments and read-only ones, by VIEWER-ID.
Returns a plist (:own (...) :read-only (...)).  A candidate is `:own' when its
`:author-id' equals VIEWER-ID (see `pearl--comment-editable-p'); a non-own /
bot / external comment is `:read-only' -- edited locally but not pushable."
  (let (own read-only)
    (dolist (c candidates)
      (if (pearl--comment-editable-p (plist-get c :author-id) viewer-id)
          (push c own)
        (push c read-only)))
    (list :own (nreverse own) :read-only (nreverse read-only))))

;;; Save engine (the save model's per-field savers)
;;
;; Each dirty field runs through `pearl--run-field-save', which performs the
;; fetch + the three-way `pearl--sync-decision' + the push (or conflict
;; resolution) and invokes its callback exactly once with a structured outcome
;; instead of messaging.  The per-field savers below build the spec for a
;; title, description, or own comment.  The interactive sync commands are thin
;; wrappers that run one saver and message its outcome; `pearl-save-issue' /
;; `pearl-save-all' (later) drive several savers through a queue and aggregate
;; the outcomes -- never message-scraping.

(defun pearl--save-outcome-detail (label status reason)
  "Return a human-readable detail string for LABEL at STATUS/REASON."
  (pcase status
    ('pushed (format "%s pushed" label))
    ('unchanged (format "%s unchanged" label))
    ('resolved-remote (format "%s took Linear's version" label))
    ('conflict (format "%s left in conflict (%s)" label (or reason "unresolved")))
    ('skipped (format "%s skipped (%s)" label (or reason "not pushable")))
    ('failed (format "%s failed (%s)" label (or reason "error")))
    (_ (format "%s: %s" label status))))

(defun pearl--save-outcome (spec status reason)
  "Build a save-outcome plist for SPEC with STATUS and REASON.
SPEC is a field-save spec (see `pearl--run-field-save').  STATUS is one of
`pushed' `unchanged' `conflict' `resolved-remote' `skipped' `failed'.  REASON
is nil or a symbol detailing a non-success outcome (`fetch-failed',
`push-failed', `cancelled', `aborted', `read-only', `viewer-unavailable',
`missing-property')."
  (list :issue-id (plist-get spec :issue-id)
        :identifier (plist-get spec :identifier)
        :field (plist-get spec :field)
        :comment-id (plist-get spec :comment-id)
        :status status
        :reason reason
        :label (plist-get spec :label)
        :message (pearl--save-outcome-detail (plist-get spec :label) status reason)))

(defun pearl--marker-live-p (marker)
  "Non-nil if MARKER is nil, or points into a still-live buffer.
A nil MARKER (synthetic callers with no buffer) passes; a marker into a killed
buffer fails.  Guards async commit callbacks that touch the buffer after a push
the buffer may not have survived."
  (or (null marker)
      (let ((buffer (marker-buffer marker)))
        (and buffer (buffer-live-p buffer)))))

(defun pearl--save-field-push (spec text callback)
  "Push TEXT for SPEC, advancing the provenance hash on success.
CALLBACK gets a `pushed' outcome after any :after-push bookkeeping runs, or a
`failed' / `push-failed' outcome when the update reports no success."
  (let ((marker (plist-get spec :marker)))
    (funcall (plist-get spec :push) text
             (lambda (result)
               (if (plist-get result :success)
                   (progn
                     ;; The push can land after the buffer was killed; only run
                     ;; the buffer-touching bookkeeping when it's still live, but
                     ;; still report the remote success.
                     (when (pearl--marker-live-p marker)
                       (org-entry-put marker (plist-get spec :prop)
                                      (secure-hash 'sha256 text))
                       (when (plist-get spec :after-push)
                         (funcall (plist-get spec :after-push) result marker)))
                     (funcall callback (pearl--save-outcome spec 'pushed nil)))
                 (funcall callback (pearl--save-outcome spec 'failed 'push-failed)))))))

(defun pearl--run-field-save (spec callback)
  "Save one field per SPEC, invoking CALLBACK once with a save-outcome plist.
SPEC keys: :issue-id :identifier :field :comment-id :marker :prop :label
:local (current text) :stored (stored hash) :fetch (FN CB, calls CB with the
remote text or nil) :push (FN TEXT CB, calls CB with a (:success BOOL ...)
result) :apply (FN TEXT, writes reconciled text into the buffer) :after-push
\(optional FN RESULT MARKER).

No-op fast path: when the local hash already equals :stored the field is
`unchanged' and no fetch fires.  Otherwise the remote is fetched (nil ->
`failed' / `fetch-failed'), `pearl--sync-decision' runs, and the field is
pushed, taken from the remote, or sent through `pearl--resolve-conflict'.
CALLBACK fires exactly once, only after the final outcome is known -- including
the deferred smerge path."
  (let* ((local (or (plist-get spec :local) ""))
         (stored (or (plist-get spec :stored) "")))
    (if (string= (secure-hash 'sha256 local) stored)
        (funcall callback (pearl--save-outcome spec 'unchanged nil))
      (funcall (plist-get spec :fetch)
               (lambda (remote)
                 (if (null remote)
                     (funcall callback (pearl--save-outcome spec 'failed 'fetch-failed))
                   (pcase (pearl--sync-decision local stored remote)
                     (:noop (funcall callback (pearl--save-outcome spec 'unchanged nil)))
                     (:push (pearl--save-field-push spec local callback))
                     (:conflict
                      (pearl--resolve-conflict
                       (plist-get spec :label) local remote
                       (plist-get spec :marker) (plist-get spec :prop)
                       (plist-get spec :apply)
                       (lambda (text cb)
                         (funcall (plist-get spec :push) text
                                  (lambda (r) (funcall cb (plist-get r :success)))))
                       (lambda (status reason)
                         (funcall callback (pearl--save-outcome spec status reason))))))))))))

(defun pearl--save-description-field (marker callback)
  "Save the description of the issue subtree at MARKER, calling CALLBACK.
A push advances both `LINEAR-DESC-SHA256' (the markdown baseline used by the
remote conflict gate) and `LINEAR-DESC-ORG-SHA256' (the rendered-Org baseline
used by the local dirty scan), so the next scan sees the issue as clean."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (local (pearl--org-to-md (pearl--entry-body-at-point)))
           (spec (list
                  :issue-id issue-id :identifier identifier :field 'description
                  :comment-id nil :marker marker :prop "LINEAR-DESC-SHA256"
                  :local local :stored (org-entry-get nil "LINEAR-DESC-SHA256")
                  :label (format "%s description" (or identifier issue-id))
                  :fetch (lambda (cb)
                           (pearl--fetch-issue-description-async
                            issue-id
                            (lambda (remote) (funcall cb (and remote (plist-get remote :description))))))
                  :push (lambda (text cb)
                          (pearl--update-issue-description-async issue-id text cb))
                  :apply (lambda (md)
                           (org-with-point-at marker
                             (pearl--set-entry-body-at-point (pearl--md-to-org md))))
                  :after-push (lambda (result m)
                                (when (plist-get result :updated-at)
                                  (org-entry-put m "LINEAR-DESC-UPDATED-AT"
                                                 (plist-get result :updated-at)))))))
      (pearl--run-field-save
       spec
       (lambda (outcome)
         ;; A push or use-remote leaves the buffer body current; resync the Org
         ;; hash from it so the lossless local scan agrees with the markdown one.
         ;; Skip when the buffer was killed before this async callback fired.
         (when (and (memq (plist-get outcome :status) '(pushed resolved-remote))
                    (pearl--marker-live-p marker))
           (org-with-point-at marker
             (org-entry-put marker "LINEAR-DESC-ORG-SHA256"
                            (secure-hash 'sha256 (pearl--entry-body-at-point)))))
         (funcall callback outcome))))))

(defun pearl--save-title-field (marker callback)
  "Save the issue title at MARKER, calling CALLBACK with the save outcome."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (spec (list
                  :issue-id issue-id :identifier identifier :field 'title
                  :comment-id nil :marker marker :prop "LINEAR-TITLE-SHA256"
                  :local (pearl--issue-title-at-point)
                  :stored (org-entry-get nil "LINEAR-TITLE-SHA256")
                  :label (format "%s title" (or identifier issue-id))
                  :fetch (lambda (cb)
                           (pearl--fetch-issue-title-async
                            issue-id
                            (lambda (remote) (funcall cb (and remote (plist-get remote :title))))))
                  :push (lambda (text cb)
                          (pearl--update-issue-title-async issue-id text cb))
                  :apply (lambda (title)
                           (org-with-point-at marker
                             (org-back-to-heading t)
                             (org-edit-headline title))))))
      (pearl--run-field-save spec callback))))

(defun pearl--save-comment-field (marker viewer-id callback)
  "Save the comment at MARKER, calling CALLBACK with the outcome.
VIEWER-ID is the resolved viewer id (already known by the caller).  A comment
authored by anyone else is reported `skipped' / `read-only' with no network;
only the viewer's own comments are saved through the gate."
  (org-with-point-at marker
    (let* ((comment-id (org-entry-get nil "LINEAR-COMMENT-ID"))
           (author-id (org-entry-get nil "LINEAR-COMMENT-AUTHOR-ID"))
           (spec (list
                  ;; Comment headings carry LINEAR-COMMENT-ID, not LINEAR-ID, so
                  ;; climb to the enclosing issue for the outcome's :issue-id.
                  :issue-id (pearl--issue-id-at-point)
                  :identifier comment-id :field 'comment :comment-id comment-id
                  :marker marker :prop "LINEAR-COMMENT-SHA256"
                  :local (pearl--org-to-md (pearl--entry-body-at-point))
                  :stored (org-entry-get nil "LINEAR-COMMENT-SHA256")
                  :label (format "comment %s" comment-id)
                  :fetch (lambda (cb) (pearl--fetch-comment-body-async comment-id cb))
                  :push (lambda (text cb) (pearl--update-comment-async comment-id text cb))
                  :apply (lambda (md)
                           (org-with-point-at marker
                             (pearl--set-entry-body-at-point (pearl--md-to-org md)))))))
      (cond
       ((null viewer-id)
        (funcall callback (pearl--save-outcome spec 'skipped 'viewer-unavailable)))
       ((not (pearl--comment-editable-p author-id viewer-id))
        (funcall callback (pearl--save-outcome spec 'skipped 'read-only)))
       (t (pearl--run-field-save spec callback))))))

(defun pearl--report-save-outcome (outcome buffer)
  "Message a single field-save OUTCOME and surface BUFFER on a push.
The reporter for the thin interactive wrappers (`pearl-sync-current-issue' and
friends), which save one field; `pearl-save-issue' / `pearl-save-all'
aggregate their own summaries instead."
  (message "%s" (plist-get outcome :message))
  (when (memq (plist-get outcome :status) '(pushed resolved-remote))
    (pearl--surface-buffer buffer)))

(defun pearl--run-save-queue (thunks callback)
  "Run THUNKS sequentially; CALLBACK gets their outcomes, in order, at the end.
Each thunk is a function of one argument DONE, which it calls with a single
save-outcome when finished.  The next thunk starts only after the current
thunk's DONE fires, so at most one conflict-resolution UI is ever live -- the
deferred smerge path pauses the queue until it commits or aborts.  An empty
THUNKS list calls CALLBACK with nil immediately."
  (let (outcomes run-next)
    (setq run-next
          (lambda (remaining)
            (if (null remaining)
                (funcall callback (nreverse outcomes))
              (funcall (car remaining)
                       (lambda (outcome)
                         (push outcome outcomes)
                         (funcall run-next (cdr remaining)))))))
    (funcall run-next thunks)))

(defun pearl--save-summary-message (outcomes)
  "Return a one-line summary string for OUTCOMES, grouped by status.
A status that carries a reason (skipped / conflict / failed) shows the first
such reason next to its count."
  (let ((counts (make-hash-table :test 'eq))
        (reasons (make-hash-table :test 'eq))
        parts)
    (dolist (o outcomes)
      (let ((s (plist-get o :status)))
        (puthash s (1+ (gethash s counts 0)) counts)
        (when (and (plist-get o :reason) (not (gethash s reasons)))
          (puthash s (plist-get o :reason) reasons))))
    (dolist (s '(pushed resolved-remote unchanged conflict skipped failed))
      (let ((n (gethash s counts 0)))
        (when (> n 0)
          (push (if (gethash s reasons)
                    (format "%d %s (%s)" n s (gethash s reasons))
                  (format "%d %s" n s))
                parts))))
    (if parts (string-join (nreverse parts) ", ") "nothing")))

(defun pearl--report-save-summary (outcomes buffer label)
  "Message a one-line summary of OUTCOMES under LABEL.
Surface BUFFER when any field pushed.  The shared close-out for
`pearl-save-issue' and `pearl-save-all'."
  (let (pushed)
    (dolist (o outcomes)
      (when (memq (plist-get o :status) '(pushed resolved-remote))
        (setq pushed t)))
    (message "%s: %s" label (pearl--save-summary-message outcomes))
    (when pushed (pearl--surface-buffer buffer))))

(defun pearl--run-atomic-field-save (spec callback)
  "Save one atomic (enum/relation) field per SPEC, calling CALLBACK once.
SPEC keys: :issue-id :identifier :field :marker :label; :live and :baseline
\(comparison values -- a nil :baseline is a legacy file with no synced
baseline); :equal (a comparator, default `equal'); :fetch-remote (FN CB; CB
gets the remote comparison value or `:error'); :push (FN CB; pushes :live, CB
gets a (:success BOOL) result); :commit-local (FN; advances the baseline to
:live, already in the buffer); :commit-remote (FN VALUE; writes VALUE into the
buffer and advances the baseline to it); :live-display (a prompt string) and
:remote-display (FN VALUE -> string).

The atomic three-way, the sibling of `pearl--run-field-save' for non-text
fields: a missing baseline is `skipped'/`missing-property'; live equal to
baseline is `unchanged'; otherwise the remote is fetched (`:error' ->
`failed'/`fetch-failed') -- remote equal to live converges (advance baseline,
`unchanged'), remote equal to baseline is a clean push, anything else runs
`pearl--resolve-atomic-conflict'.  No SHA hash and no smerge."
  (let* ((live (plist-get spec :live))
         (baseline (plist-get spec :baseline))
         (equal-fn (or (plist-get spec :equal) #'equal))
         (marker (plist-get spec :marker))
         (push-then-commit
          (lambda (cb)
            (funcall (plist-get spec :push)
                     (lambda (r)
                       ;; The push can land after the buffer was killed; only run
                       ;; the buffer-touching commit when it's still live, but
                       ;; still report the remote success either way.
                       (when (and (plist-get r :success) (pearl--marker-live-p marker))
                         (funcall (plist-get spec :commit-local)))
                       (funcall cb (plist-get r :success)))))))
    (cond
     ((null baseline)
      (funcall callback (pearl--save-outcome spec 'skipped 'missing-property)))
     ((funcall equal-fn live baseline)
      (funcall callback (pearl--save-outcome spec 'unchanged nil)))
     (t
      (funcall
       (plist-get spec :fetch-remote)
       (lambda (remote)
         (cond
          ((eq remote :error)
           (funcall callback (pearl--save-outcome spec 'failed 'fetch-failed)))
          ((funcall equal-fn remote live)
           (when (pearl--marker-live-p marker)
             (funcall (plist-get spec :commit-local)))
           (funcall callback (pearl--save-outcome spec 'unchanged nil)))
          ((funcall equal-fn remote baseline)
           (funcall push-then-commit
                    (lambda (ok)
                      (funcall callback
                               (pearl--save-outcome spec (if ok 'pushed 'failed)
                                                    (and (not ok) 'push-failed))))))
          (t
           (pearl--resolve-atomic-conflict
            (plist-get spec :label)
            (plist-get spec :live-display)
            (funcall (plist-get spec :remote-display) remote)
            push-then-commit
            (lambda () (when (pearl--marker-live-p marker)
                         (funcall (plist-get spec :commit-remote) remote)))
            (lambda (status reason)
              (funcall callback (pearl--save-outcome spec status reason))))))))))))

(defun pearl--node-assignee-id (node)
  "The assignee id of raw issue NODE, or \"\" when unassigned."
  (or (cdr (assoc 'id (cdr (assoc 'assignee node)))) ""))

(defun pearl--node-assignee-name (node)
  "The assignee display name of raw issue NODE, or \"(unassigned)\"."
  (or (cdr (assoc 'name (cdr (assoc 'assignee node)))) "(unassigned)"))

(defun pearl--save-assignee-field (marker callback)
  "Save the assignee of the issue subtree at MARKER, calling CALLBACK.
Picker-authoritative: the live id is `LINEAR-ASSIGNEE-ID', diffed against
`LINEAR-ASSIGNEE-ID-SYNCED'.  A push sends `assigneeId' (`:null' unassigns)."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (live (or (org-entry-get nil "LINEAR-ASSIGNEE-ID") ""))
           (remote-node nil)
           (spec
            (list
             :issue-id issue-id :identifier identifier :field 'assignee
             :marker marker
             :label (format "%s assignee" (or identifier issue-id))
             :live live
             :baseline (org-entry-get nil "LINEAR-ASSIGNEE-ID-SYNCED")
             :equal #'string=
             :live-display (or (org-entry-get nil "LINEAR-ASSIGNEE-NAME") "(unassigned)")
             :remote-display (lambda (_id) (pearl--node-assignee-name remote-node))
             :fetch-remote
             (lambda (cb)
               (pearl--fetch-issue-async
                issue-id
                (lambda (node)
                  (if (memq node '(:error :missing))
                      (funcall cb :error)
                    (setq remote-node node)
                    (funcall cb (pearl--node-assignee-id node))))))
             :push
             (lambda (cb)
               (pearl--update-issue-async
                issue-id
                (list (cons "assigneeId" (if (string-empty-p live) :null live)))
                cb))
             :commit-local
             (lambda () (org-entry-put marker "LINEAR-ASSIGNEE-ID-SYNCED" live))
             :commit-remote
             (lambda (remote-id)
               (org-entry-put marker "LINEAR-ASSIGNEE-ID" remote-id)
               (org-entry-put marker "LINEAR-ASSIGNEE-NAME"
                              (pearl--node-assignee-name remote-node))
               (org-entry-put marker "LINEAR-ASSIGNEE-ID-SYNCED" remote-id)))))
      (pearl--run-atomic-field-save spec callback))))

(defun pearl--node-priority (node)
  "The priority number (0-4) of raw issue NODE."
  (or (cdr (assoc 'priority node)) 0))

(defun pearl--node-state-id (node)
  "The state id of raw issue NODE, or \"\"."
  (or (cdr (assoc 'id (cdr (assoc 'state node)))) ""))

(defun pearl--node-state-name (node)
  "The state name of raw issue NODE, or \"\"."
  (or (cdr (assoc 'name (cdr (assoc 'state node)))) ""))

(defun pearl--node-label-ids (node)
  "The sorted label ids of raw issue NODE."
  (sort (mapcar (lambda (l) (or (cdr (assoc 'id l)) ""))
                (pearl--node-list (cdr (assoc 'labels node))))
        #'string<))

(defun pearl--node-label-names (node)
  "The label display names of raw issue NODE, comma-separated."
  (mapconcat (lambda (l) (or (cdr (assoc 'name l)) ""))
             (pearl--node-list (cdr (assoc 'labels node))) ", "))

(defun pearl--save-priority-field (marker callback)
  "Save the priority of the issue subtree at MARKER, calling CALLBACK.
The live value is the heading cookie's number, diffed against `LINEAR-PRIORITY'."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (live (pearl--priority-number-at-point))
           (base-str (org-entry-get nil "LINEAR-PRIORITY"))
           (spec
            (list
             :issue-id issue-id :identifier identifier :field 'priority
             :marker marker :label (format "%s priority" (or identifier issue-id))
             :live live
             :baseline (and base-str (string-to-number base-str))
             :equal #'eql
             :live-display (pearl--get-linear-priority-name live)
             :remote-display (lambda (n) (pearl--get-linear-priority-name n))
             :fetch-remote
             (lambda (cb)
               (pearl--fetch-issue-async
                issue-id
                (lambda (node)
                  (if (memq node '(:error :missing))
                      (funcall cb :error)
                    (funcall cb (pearl--node-priority node))))))
             :push
             (lambda (cb)
               (pearl--update-issue-async issue-id (list (cons "priority" live)) cb))
             :commit-local
             (lambda () (org-entry-put marker "LINEAR-PRIORITY" (number-to-string live)))
             :commit-remote
             (lambda (n)
               (org-with-point-at marker (pearl--set-priority-cookie n))
               (org-entry-put marker "LINEAR-PRIORITY" (number-to-string n))))))
      (pearl--run-atomic-field-save spec callback))))

(defun pearl--save-state-field (marker callback)
  "Save the workflow state of the issue subtree at MARKER, calling CALLBACK.
Two arms reach the live state id.  Picker arm: the explicit `LINEAR-STATE-ID'
moved off `LINEAR-STATE-ID-SYNCED', and that id is the live value.
Keyword-cycle arm: the id is unmoved but the TODO keyword diverged from
`LINEAR-STATE-NAME', so the keyword resolves to a team state id by slug match
\(`pearl--resolve-keyword-to-state').  A keyword no team state matches can't be
resolved, so the save is skipped.  A push sends `stateId'."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (label (format "%s state" (or identifier issue-id)))
           (explicit-id (or (org-entry-get nil "LINEAR-STATE-ID") ""))
           (synced (org-entry-get nil "LINEAR-STATE-ID-SYNCED"))
           (name (or (org-entry-get nil "LINEAR-STATE-NAME") ""))
           (picker-dirty (pearl--id-baseline-dirty-p
                          "LINEAR-STATE-ID" "LINEAR-STATE-ID-SYNCED"))
           (cycled (and (not picker-dirty) (pearl--state-keyword-cycled-p)))
           (resolved (and cycled
                          (pearl--resolve-keyword-to-state
                           (org-get-todo-state)
                           (org-entry-get nil "LINEAR-TEAM-ID"))))
           (live (if cycled (and resolved (plist-get resolved :id)) explicit-id))
           (live-name (if cycled (and resolved (plist-get resolved :name)) name))
           (remote-node nil))
      (if (and cycled (not resolved))
          ;; The keyword was cycled to one no team state slugifies to -- there's
          ;; no id to push.  Report it skipped rather than guessing.
          (funcall callback
                   (pearl--save-outcome
                    (list :issue-id issue-id :identifier identifier
                          :field 'state :label label)
                    'skipped 'unknown-keyword))
        (let ((spec
               (list
                :issue-id issue-id :identifier identifier :field 'state
                :marker marker :label label
                :live live
                :baseline synced
                :equal #'string=
                :live-display live-name
                :remote-display (lambda (_id) (pearl--node-state-name remote-node))
                :fetch-remote
                (lambda (cb)
                  (pearl--fetch-issue-async
                   issue-id
                   (lambda (node)
                     (if (memq node '(:error :missing))
                         (funcall cb :error)
                       (setq remote-node node)
                       (funcall cb (pearl--node-state-id node))))))
                :push
                (lambda (cb)
                  (pearl--update-issue-async issue-id (list (cons "stateId" live)) cb))
                :commit-local
                (lambda ()
                  (org-with-point-at marker
                    (pearl--set-heading-state live-name live))
                  (org-entry-put marker "LINEAR-STATE-ID-SYNCED" live))
                :commit-remote
                (lambda (remote-id)
                  (org-with-point-at marker
                    (pearl--set-heading-state (pearl--node-state-name remote-node) remote-id))
                  (org-entry-put marker "LINEAR-STATE-ID-SYNCED" remote-id)))))
          (pearl--run-atomic-field-save spec callback))))))

(defun pearl--save-labels-field (marker callback)
  "Save the labels of the issue subtree at MARKER, calling CALLBACK.
The live id set is `LINEAR-LABEL-IDS', diffed order-insensitively against
`LINEAR-LABEL-IDS-SYNCED' (canonicalized to a sorted space-joined string).  A
push sends `labelIds'."
  (org-with-point-at marker
    (let* ((issue-id (org-entry-get nil "LINEAR-ID"))
           (identifier (org-entry-get nil "LINEAR-IDENTIFIER"))
           (live-ids (sort (split-string
                            (or (org-entry-get nil "LINEAR-LABEL-IDS") "") " " t)
                           #'string<))
           (live (string-join live-ids " "))
           (base-str (org-entry-get nil "LINEAR-LABEL-IDS-SYNCED"))
           (remote-node nil)
           (spec
            (list
             :issue-id issue-id :identifier identifier :field 'labels
             :marker marker :label (format "%s labels" (or identifier issue-id))
             :live live
             :baseline (and base-str
                            (string-join (sort (split-string base-str " " t) #'string<) " "))
             :equal #'string=
             :live-display (or (org-entry-get nil "LINEAR-LABELS") "[]")
             :remote-display (lambda (_) (format "[%s]" (pearl--node-label-names remote-node)))
             :fetch-remote
             (lambda (cb)
               (pearl--fetch-issue-async
                issue-id
                (lambda (node)
                  (if (memq node '(:error :missing))
                      (funcall cb :error)
                    (setq remote-node node)
                    (funcall cb (string-join (pearl--node-label-ids node) " "))))))
             :push
             (lambda (cb)
               (pearl--update-issue-async
                issue-id (list (cons "labelIds" (vconcat live-ids))) cb))
             :commit-local
             (lambda () (org-entry-put marker "LINEAR-LABEL-IDS-SYNCED" live))
             :commit-remote
             (lambda (remote-str)
               (org-entry-put marker "LINEAR-LABEL-IDS" remote-str)
               (org-entry-put marker "LINEAR-LABELS"
                              (format "[%s]" (pearl--node-label-names remote-node)))
               (org-entry-put marker "LINEAR-LABEL-IDS-SYNCED" remote-str)))))
      (pearl--run-atomic-field-save spec callback))))

(defun pearl--issue-has-dirty-fields-p (dirty)
  "Non-nil if the DIRTY plist (from `pearl--issue-dirty-fields') has any change."
  (or (plist-get dirty :title)
      (plist-get dirty :description)
      (plist-get dirty :priority)
      (plist-get dirty :state)
      (plist-get dirty :assignee)
      (plist-get dirty :labels)
      (plist-get dirty :comment-candidates)))

(defun pearl--save-field-thunks (marker dirty viewer-id)
  "Build the ordered save thunks for the DIRTY fields of the issue at MARKER.
Title, then the structured fields (priority / state / assignee / labels), then
description, then each changed comment candidate (VIEWER-ID gates ownership
inside `pearl--save-comment-field')."
  (let (thunks)
    (when (plist-get dirty :title)
      (push (lambda (done) (pearl--save-title-field marker done)) thunks))
    (when (plist-get dirty :priority)
      (push (lambda (done) (pearl--save-priority-field marker done)) thunks))
    (when (plist-get dirty :state)
      (push (lambda (done) (pearl--save-state-field marker done)) thunks))
    (when (plist-get dirty :assignee)
      (push (lambda (done) (pearl--save-assignee-field marker done)) thunks))
    (when (plist-get dirty :labels)
      (push (lambda (done) (pearl--save-labels-field marker done)) thunks))
    (when (plist-get dirty :description)
      (push (lambda (done) (pearl--save-description-field marker done)) thunks))
    (dolist (c (plist-get dirty :comment-candidates))
      (let ((cm (plist-get c :marker)))
        (push (lambda (done) (pearl--save-comment-field cm viewer-id done)) thunks)))
    (nreverse thunks)))

(defun pearl--save-issue-at (marker buffer dirty viewer-id)
  "Queue and run the DIRTY field saves for the issue at MARKER, then summarize.
VIEWER-ID is the resolved viewer id (or nil).  BUFFER is surfaced if anything
was pushed.  The summary is labelled with the issue identifier."
  (let ((label (org-with-point-at marker
                 (or (org-entry-get nil "LINEAR-IDENTIFIER")
                     (org-entry-get nil "LINEAR-ID")))))
    (pearl--run-save-queue
     (pearl--save-field-thunks marker dirty viewer-id)
     (lambda (outcomes)
       (pearl--report-save-summary outcomes buffer (format "Saved %s" label))))))

;;;###autoload
(defun pearl-save-issue ()
  "Save every changed field of the Linear issue at point in one pass.
Runs from anywhere inside an issue subtree.  A local dirty scan (no network)
picks which of the title, structured fields (priority / state / assignee /
labels), description, and your own comments changed; the viewer is resolved
once, and only if comments are dirty; then each dirty field is saved
sequentially through its conflict gate and a single summary is reported.  A
clean issue does no network at all."
  (interactive)
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-issue-heading-or-error)
    (let* ((marker (point-marker))
           (buffer (current-buffer))
           (dirty (pearl--issue-dirty-fields)))
      (if (not (pearl--issue-has-dirty-fields-p dirty))
          (message "Nothing to save for %s"
                   (or (org-entry-get nil "LINEAR-IDENTIFIER")
                       (org-entry-get nil "LINEAR-ID")))
        (if (plist-get dirty :comment-candidates)
            (pearl--viewer-async
             (lambda (viewer)
               (pearl--save-issue-at marker buffer dirty
                                     (and viewer (plist-get viewer :id)))))
          (pearl--save-issue-at marker buffer dirty nil))))))

(defun pearl--scan-all-dirty ()
  "Scan every issue subtree in the buffer; return ((MARKER . DIRTY) ...).
One entry per issue with any locally-changed field, in buffer order.  No
network.  This snapshots the work list at scan time -- edits made afterward
wait for the next save (each field's content is still re-read at push)."
  (let (result)
    (dolist (cell (pearl--issue-subtree-markers))
      (let* ((marker (cdr cell))
             (dirty (org-with-point-at marker (pearl--issue-dirty-fields))))
        (when (pearl--issue-has-dirty-fields-p dirty)
          (push (cons marker dirty) result))))
    (nreverse result)))

(defun pearl--save-all-counts (scan viewer-id &optional viewer-failed)
  "Tally the dirty fields in SCAN, classifying comments with VIEWER-ID.
When VIEWER-FAILED is non-nil (the viewer lookup ran and failed), every comment
candidate counts as `:viewer-unavailable' rather than being classified as own /
read-only -- a nil VIEWER-ID then means \"couldn't tell\", not \"none are
yours\".  Returns a plist (:issues :titles :descriptions :priorities :states
:assignees :labels :own-comments :read-only-comments :viewer-unavailable)."
  (let ((issues 0) (titles 0) (descriptions 0) (priorities 0) (states 0)
        (assignees 0) (labels 0) (own 0) (read-only 0) (viewer-unavailable 0))
    (dolist (cell scan)
      (let ((dirty (cdr cell)))
        (setq issues (1+ issues))
        (when (plist-get dirty :title) (setq titles (1+ titles)))
        (when (plist-get dirty :description) (setq descriptions (1+ descriptions)))
        (when (plist-get dirty :priority) (setq priorities (1+ priorities)))
        (when (plist-get dirty :state) (setq states (1+ states)))
        (when (plist-get dirty :assignee) (setq assignees (1+ assignees)))
        (when (plist-get dirty :labels) (setq labels (1+ labels)))
        (let ((cands (plist-get dirty :comment-candidates)))
          (if viewer-failed
              (setq viewer-unavailable (+ viewer-unavailable (length cands)))
            (let ((split (pearl--classify-comment-candidates cands viewer-id)))
              (setq own (+ own (length (plist-get split :own))))
              (setq read-only (+ read-only (length (plist-get split :read-only)))))))))
    (list :issues issues :titles titles :descriptions descriptions
          :priorities priorities :states states :assignees assignees :labels labels
          :own-comments own :read-only-comments read-only
          :viewer-unavailable viewer-unavailable)))

(defun pearl--save-all-prompt (counts)
  "Return the one-time confirmation prompt string for the dirty COUNTS plist."
  (let* ((titles (plist-get counts :titles))
         (descriptions (plist-get counts :descriptions))
         (priorities (or (plist-get counts :priorities) 0))
         (states (or (plist-get counts :states) 0))
         (assignees (or (plist-get counts :assignees) 0))
         (labels (or (plist-get counts :labels) 0))
         (own (plist-get counts :own-comments))
         (read-only (plist-get counts :read-only-comments))
         (viewer-unavailable (or (plist-get counts :viewer-unavailable) 0))
         (fields (+ titles descriptions priorities states assignees labels own))
         (issues (plist-get counts :issues))
         parts skips)
    (when (> titles 0)
      (push (format "%d title%s" titles (if (= titles 1) "" "s")) parts))
    (when (> descriptions 0)
      (push (format "%d description%s" descriptions (if (= descriptions 1) "" "s")) parts))
    (when (> priorities 0)
      (push (format "%d priorit%s" priorities (if (= priorities 1) "y" "ies")) parts))
    (when (> states 0)
      (push (format "%d state%s" states (if (= states 1) "" "s")) parts))
    (when (> assignees 0)
      (push (format "%d assignee%s" assignees (if (= assignees 1) "" "s")) parts))
    (when (> labels 0)
      (push (format "%d label%s" labels (if (= labels 1) "" "s")) parts))
    (when (> own 0)
      (push (format "%d comment%s" own (if (= own 1) "" "s")) parts))
    (when (> read-only 0)
      (push (format "%d read-only comment%s" read-only (if (= read-only 1) "" "s")) skips))
    (when (> viewer-unavailable 0)
      (push (format "%d comment%s (viewer unavailable)"
                    viewer-unavailable (if (= viewer-unavailable 1) "" "s"))
            skips))
    (format "Save %d field%s across %d issue%s? (%s%s) "
            fields (if (= fields 1) "" "s")
            issues (if (= issues 1) "" "s")
            (if parts (string-join (nreverse parts) ", ") "0 fields")
            (if skips
                (concat "; " (string-join (nreverse skips) ", ") " skipped")
              ""))))

(defun pearl--save-all-run (scan buffer viewer-id &optional viewer-failed)
  "Confirm SCAN once, then save all its dirty fields and report.
VIEWER-ID gates comment ownership; VIEWER-FAILED marks a failed viewer lookup so
the prompt counts comments as viewer-unavailable rather than read-only.  BUFFER
is surfaced if anything pushed.  Declining the prompt mutates nothing.  The
queue continues past a per-field conflict, so one conflicted issue does not
stop the rest."
  (if (not (pearl--read-yes-no (pearl--save-all-prompt
                      (pearl--save-all-counts scan viewer-id viewer-failed))))
      (message "save-all cancelled; nothing saved")
    (let (thunks)
      (dolist (cell scan)
        (setq thunks (append thunks
                             (pearl--save-field-thunks (car cell) (cdr cell) viewer-id))))
      (pearl--run-save-queue
       thunks
       (lambda (outcomes)
         (pearl--report-save-summary outcomes buffer "Saved all"))))))

;;;###autoload
(defun pearl-save-all ()
  "Save every changed field across all Linear issues in the file, after one prompt.
A local dirty scan (no network for title/description; comment changed-candidates
found locally) builds the work list.  When comment candidates exist and the
viewer cache is cold, one read-only viewer lookup runs so read-only comments are
counted -- no mutation before the prompt.  A single confirmation names the field
counts; declining mutates nothing.  On confirm the dirty fields save
sequentially, continuing past any per-field conflict, and one summary is
reported.  A clean file does nothing."
  (interactive)
  (pearl--require-account-context t)
  (let* ((buffer (current-buffer))
         (scan (pearl--scan-all-dirty)))
    (if (null scan)
        (message "Nothing to save")
      (let ((has-comments nil))
        (dolist (cell scan)
          (when (plist-get (cdr cell) :comment-candidates) (setq has-comments t)))
        (if (and has-comments (not pearl--cache-viewer))
            (pearl--viewer-async
             (lambda (viewer)
               ;; A nil viewer here means the lookup failed (we only do it when
               ;; comments exist), so flag it -- those comments are
               ;; viewer-unavailable, not read-only.
               (pearl--save-all-run scan buffer (and viewer (plist-get viewer :id))
                                    (null viewer))))
          (pearl--save-all-run scan buffer
                               (and pearl--cache-viewer
                                    (plist-get pearl--cache-viewer :id))))))))

(defun pearl--subtree-has-local-edits-p ()
  "Non-nil if the issue subtree at point has any unpushed local edit.
Broader than `pearl--subtree-dirty-p', which inspects only the description:
this also covers a changed title, state, priority, assignee, labels, or comment.
A merge refresh uses it so it keeps an issue you have touched in any field, not
just ones whose description changed."
  (pearl--issue-has-dirty-fields-p (pearl--issue-dirty-fields)))

(defun pearl--merge-issues-into-buffer (issues)
  "Merge normalized ISSUES into the current buffer by `LINEAR-ID'.
Same-source refresh semantics: an existing issue still in ISSUES is re-rendered
in place; an issue new to ISSUES is appended after the last one; an issue no
longer in ISSUES is dropped.  A subtree with any unpushed local edit (see
`pearl--subtree-has-local-edits-p' -- title, state, priority, assignee, labels,
description, or a comment) is never overwritten and never dropped; it is kept
and counted, so a refresh can't lose un-synced work.

Returns a plist of counts plus markers:
\(:updated N :added N :dropped N :skipped N :touched-markers (M1 M2 ...))
where `:touched-markers' carries one marker per subtree the merge re-rendered
(updated) or appended (added).  Callers use the marker list to fold just
those subtrees rather than re-folding the whole buffer, so an
edit-then-merge flow keeps the user's expanded subtrees expanded."
  (let ((existing (pearl--issue-subtree-markers))
        (fetched-ids (mapcar (lambda (i) (plist-get i :id)) issues))
        (updated 0) (added 0) (dropped 0) (skipped 0)
        (touched-markers '()))
    ;; Existing issues still in the result: re-render in place, unless dirty.
    (dolist (issue issues)
      (let ((marker (cdr (assoc (plist-get issue :id) existing))))
        (when marker
          (save-excursion
            (goto-char marker)
            (if (pearl--subtree-has-local-edits-p)
                (setq skipped (1+ skipped))
              ;; Capture a type-nil marker at the heading start BEFORE the
              ;; replace.  The alist marker is type-t (it needs to advance
              ;; past replaces of EARLIER subtrees so it stays on its own
              ;; heading); a type-t marker on the CURRENT replace advances
              ;; past its own delete-then-insert and lands on the next
              ;; subtree.  A type-nil copy stays anchored at the deletion
              ;; start and ends up on the new heading after the re-insert.
              (let ((touch (copy-marker marker nil)))
                (pearl--replace-issue-subtree-at-point issue)
                (push touch touched-markers))
              (setq updated (1+ updated)))))))
    ;; Existing issues absent from the result: drop them, but keep dirty ones.
    (dolist (cell existing)
      (unless (member (car cell) fetched-ids)
        (save-excursion
          (goto-char (cdr cell))
          (if (pearl--subtree-has-local-edits-p)
              (setq skipped (1+ skipped))
            (org-back-to-heading t)
            (delete-region (point) (progn (org-end-of-subtree t t) (point)))
            (setq dropped (1+ dropped))))))
    ;; Issues new to the result: append after the last one, in fetched order.
    (dolist (issue issues)
      (unless (assoc (plist-get issue :id) existing)
        (save-excursion
          (goto-char (point-max))
          (unless (bolp) (insert "\n"))
          (let ((insertion-start (point-marker)))
            (insert (pearl--format-issue-as-org-entry issue))
            (push insertion-start touched-markers)))
        (setq added (1+ added))))
    (list :updated updated :added added :dropped dropped :skipped skipped
          :touched-markers (nreverse touched-markers))))

(defun pearl--update-source-header (issue-count truncated)
  "Refresh the active file's run-at, count, and truncation header lines.
ISSUE-COUNT is the new issue total; TRUNCATED marks a page-cap hit.  The
`#+LINEAR-SOURCE:' descriptor is left untouched -- only the human-readable
provenance advances on a refresh.  Under accounts mode an unmarked file also
acquires its `#+LINEAR-ACCOUNT' stamp here (see
`pearl--ensure-buffer-account-header')."
  (pearl--ensure-buffer-account-header)
  (save-excursion
    (goto-char (point-min))
    (when (re-search-forward "^#\\+LINEAR-RUN-AT: .*$" nil t)
      (replace-match (format "#+LINEAR-RUN-AT: %s"
                             (format-time-string "%Y-%m-%d %H:%M"))
                     t t))
    (goto-char (point-min))
    (when (re-search-forward "^#\\+LINEAR-COUNT: .*$" nil t)
      (replace-match (format "#+LINEAR-COUNT: %d" issue-count) t t))
    (goto-char (point-min))
    (when (re-search-forward "^#\\+LINEAR-TRUNCATED: .*$" nil t)
      (replace-match (format "#+LINEAR-TRUNCATED: %s" (if truncated "yes" "no")) t t))))

(defun pearl--update-derived-todo-header (states)
  "Rewrite the buffer's `#+TODO:' line from the final headings plus STATES.
Scans every Linear issue heading (carrying `LINEAR-ID') for its TODO keyword
and `:LINEAR-STATE-TYPE:' drawer, unions those with STATES (the fetched teams'
states, see `pearl--gather-header-states'), and rewrites the line via
`pearl--derive-todo-line'.  Scanning the final buffer -- not just the fetched
issue list -- keeps retained / skipped dirty subtrees declared.  A heading with
no state-type drawer (a legacy render) is classified by `org-done-keywords'.
Creates the line after `#+STARTUP:' if it is absent."
  (save-excursion
    (let (scanned)
      (goto-char (point-min))
      (while (re-search-forward "^\\*+ " nil t)
        (when (org-entry-get nil "LINEAR-ID")
          (let ((kw (org-get-todo-state))
                (type (org-entry-get nil "LINEAR-STATE-TYPE")))
            (when kw
              (push (list :name kw
                          :type (cond ((and type (not (string-empty-p type))) type)
                                      ((member kw org-done-keywords) "completed")
                                      (t nil)))
                    scanned)))))
      (let ((line (pearl--derive-todo-line (append states (nreverse scanned)))))
        (goto-char (point-min))
        (if (re-search-forward "^#\\+TODO: .*$" nil t)
            (replace-match (format "#+TODO: %s" line) t t)
          (when (re-search-forward "^#\\+STARTUP: .*$" nil t)
            (end-of-line)
            (insert (format "\n#+TODO: %s" line))))))))

(defun pearl--merge-query-result (result source)
  "Merge a query RESULT into the current buffer by `LINEAR-ID', tagged with SOURCE.
The same-source refresh counterpart to `pearl--render-query-result': rather than
replacing the file, it updates issue subtrees in place, appends new matches, and
drops issues no longer present (protecting unpushed edits per subtree), then
refreshes the provenance header.  An empty result leaves the buffer untouched
rather than dropping every issue, mirroring the non-destructive empty handling
of the replace path."
  (pcase (pearl--query-result-status result)
    ('ok
     (let* ((issues (pearl--sort-issues
                     (mapcar (lambda (n)
                               (pearl--cap-issue-list-comments
                                (pearl--normalize-issue n)))
                             (pearl--query-result-issues result))
                     (plist-get source :sort)
                     (plist-get source :order)))
            (truncated (pearl--query-result-truncated-p result))
            (counts (pearl--merge-issues-into-buffer issues)))
       (pearl--update-source-header (length issues) truncated)
       (pearl--update-derived-todo-header (pearl--gather-header-states issues))
       (pearl-highlight-comments)
       ;; Same as the dirty-merge path: fold only the touched subtrees, leave
       ;; the rest of the page and point alone.
       (pearl--fold-touched-subtrees (plist-get counts :touched-markers))
       (pearl--surface-buffer (current-buffer))
       (message "Refreshed %s: %d updated, %d added, %d dropped%s"
                (pearl--source-name source)
                (plist-get counts :updated)
                (plist-get counts :added)
                (plist-get counts :dropped)
                (let ((s (plist-get counts :skipped)))
                  (if (> s 0) (format ", %d kept (unpushed edits)" s) "")))))
    ('empty
     (message "Linear: %s now matches no issues (file left unchanged)"
              (pearl--source-name source)))
    (_
     (message "Linear: %s"
              (or (pearl--query-result-message result)
                  "could not refresh issues")))))

;;;###autoload
(defun pearl-refresh-current-view ()
  "Re-run the active source recorded in the current file's header and merge it in.
Reads the `#+LINEAR-SOURCE:' descriptor, re-fetches it, and merges the result
into this buffer by `LINEAR-ID' (see `pearl--merge-query-result'): existing
issues update in place, new matches are appended, and issues no longer present
are dropped, while any subtree with unpushed edits is kept.  This is the
same-source counterpart to the replace-on-switch behavior of the query and view
commands.  Errors if no source is recorded."
  (interactive)
  (pearl--require-account-context)
  (let ((source (pearl--read-active-source))
        (buffer (current-buffer)))
    (unless source
      (user-error "No Linear source recorded in this file; run a query or view first"))
    (let ((merge (lambda (result)
                   (when (buffer-live-p buffer)
                     (with-current-buffer buffer
                       (pearl--merge-query-result result source))))))
      (pcase (plist-get source :type)
        ('filter
         (pearl--progress "Refreshing %s..." (pearl--source-name source))
         (pearl--query-issues-async
          (pearl--build-issue-filter (plist-get source :filter))
          merge))
        ('view
         (pearl--progress "Refreshing %s..." (pearl--source-name source))
         (pearl--query-view-async (plist-get source :id) merge
                                  (plist-get source :sort)))
        (_ (user-error "Unknown Linear source type: %s" (plist-get source :type)))))))

;;;###autoload
(defun pearl-run-linear-view (view-name)
  "Run a Linear Custom View by VIEW-NAME and render it into the active file.
Interactively, completes over the workspace's Custom Views.  The view's own
filter runs server-side; the result replaces the active file (behind the
dirty-buffer guard) and records the view as the active source."
  (interactive
   (list (completing-read "Custom view: "
                          (mapcar (lambda (v) (cdr (assoc 'name v)))
                                  (pearl--custom-views))
                          nil t)))
  (let* ((view (seq-find (lambda (v) (string= (cdr (assoc 'name v)) view-name))
                         (pearl--custom-views)))
         (view-id (and view (cdr (assoc 'id view)))))
    (unless view-id
      (user-error "No Custom View named %s" view-name))
    (let* ((prefs (cdr (assoc 'viewPreferencesValues view)))
           (sort (pearl--view-sort-arg (cdr (assoc 'viewOrdering prefs))
                                       (cdr (assoc 'viewOrderingDirection prefs))))
           (source (list :type 'view :name view-name :id view-id
                         :url (pearl--view-url view-id)
                         :sort sort)))
      (pearl--progress "Running view %s..." view-name)
      (pearl--query-view-async
       view-id
       (lambda (result) (pearl--render-query-result result source))
       sort))))

;;;###autoload
(defun pearl-open-current-view-in-linear ()
  "Open the active view's source URL in the browser.
Reads the recorded source from the file header; errors when the source is not
a view or has no URL."
  (interactive)
  (let* ((source (pearl--read-active-source))
         (url (plist-get source :url)))
    (unless (and url (not (string-empty-p url)))
      (user-error "The active source has no view URL to open"))
    (browse-url url)))

;;;###autoload
(defun pearl--list-issues-source (project-id project-name)
  "Return (AUTHORING . SOURCE) for `pearl-list-issues' given PROJECT-ID/-NAME.
Without PROJECT-ID this is \"my open issues\" (assignee=me). With PROJECT-ID
this is the *whole* project (no assignee lock), named \"Project issues: NAME\"
when PROJECT-NAME is known and \"Project issues\" otherwise."
  (let* ((authoring (if project-id
                        (list :project project-id :open t)
                      '(:assignee :me :open t)))
         (name (cond ((and project-id project-name)
                      (format "Project issues: %s" project-name))
                     (project-id "Project issues")
                     (t "My open issues"))))
    (cons authoring (list :type 'filter :name name :filter authoring))))

(defun pearl-list-issues (&optional project-id project-name)
  "Fetch open Linear issues into `pearl-org-file-path' and show them.
Without PROJECT-ID, fetches *your* open issues (assignee=me).  With PROJECT-ID,
fetches every open issue in that project (no assignee scoping) -- the command
named for a non-assignee dimension does not silently inject assignee=me.
PROJECT-NAME, when known, is used in the source's display name.  \"Open\" means
any workflow state that is not completed, canceled, or duplicate.

Inclusion is server-side via the issue filter; the state mapping only drives
how each issue's state renders as a TODO keyword."
  (interactive)
  (pearl--log "Executing pearl-list-issues")
  (pearl--progress "Fetching issues from Linear...")
  (let* ((src (pearl--list-issues-source project-id project-name))
         (authoring (car src))
         (source (cdr src))
         (_ (pearl--validate-issue-filter authoring))
         (filter (pearl--build-issue-filter authoring)))
    (pearl--query-issues-async
     filter
     (lambda (result) (pearl--render-query-result result source)))))

(defun pearl--resolve-default-view ()
  "Return the active scope's default view: a local-view name string, or nil.
In accounts mode the active account's `:default-view'; in legacy
single-account mode the global `pearl-default-view'.  nil means \"my open
issues\".  Resolving the account context follows the same active/default
fallback every account-aware command uses."
  (let ((ctx (pearl--current-account-context)))
    (if ctx
        (plist-get ctx :default-view)
      pearl-default-view)))

;;;###autoload
(defun pearl-open-default-view ()
  "Open the configured default view, or my open issues when none is set.
Resolves the active scope's default (`pearl--resolve-default-view'): nil runs
`pearl-list-issues' (my open issues); a local-view name in `pearl-local-views'
runs `pearl-run-local-view'; a name no longer present falls back to
`pearl-list-issues' with a message rather than erroring -- a stale default
never blocks the hot key."
  (interactive)
  (let ((default (pearl--resolve-default-view)))
    (cond
     ((null default)
      (pearl-list-issues))
     ((assoc default pearl-local-views)
      (pearl-run-local-view default))
     (t
      (message "Default view '%s' no longer exists; showing my open issues"
               default)
      (pearl-list-issues)))))

(defconst pearl--default-view-clear "[ My open issues ]"
  "Sentinel shown atop the `pearl-set-default-view' prompt.
Choosing it clears the default back to nil -- the built-in my-open-issues
fetch -- rather than naming a local view.")

(defun pearl--persist-default-view (value)
  "Persist VALUE (a local-view name string, or nil) as the default view.
In accounts mode, write VALUE to the active account's `:default-view' in
`pearl-accounts', preserving the account's other plist keys; in legacy
single-account mode, write the global `pearl-default-view'.  Both persist
durably through `customize-save-variable' so the choice survives a restart."
  (let ((ctx (pearl--current-account-context)))
    (if ctx
        (let ((name (plist-get ctx :name)))
          (setq pearl-accounts
                (mapcar (lambda (entry)
                          (if (string-equal (car entry) name)
                              (cons (car entry)
                                    (plist-put (copy-sequence (cdr entry))
                                               :default-view value))
                            entry))
                        pearl-accounts))
          (customize-save-variable 'pearl-accounts pearl-accounts))
      (setq pearl-default-view value)
      (customize-save-variable 'pearl-default-view value))))

;;;###autoload
(defun pearl-set-default-view ()
  "Set and persist the default view `pearl-open-default-view' opens.
When the current buffer shows a local view, offers that view as the default.
Otherwise prompts over `pearl-local-views' names with a clear-to-my-open-issues
sentinel at the top; choosing it clears the default, and quitting leaves it
unchanged.  Persists per scope (the active account's `:default-view' in
accounts mode, `pearl-default-view' in legacy) via `customize-save-variable'.
Bound to \\='C-; L v D\\='."
  (interactive)
  (let* ((source (pearl--read-active-source))
         (buf-view (and source
                        (eq (plist-get source :type) 'filter)
                        (let ((n (plist-get source :name)))
                          (and (stringp n) (assoc n pearl-local-views) n))))
         (value
          (if (and buf-view
                   (pearl--read-yes-no
                    (format "Set '%s' as the default view? " buf-view)))
              buf-view
            (let ((choice (completing-read
                           "Default view: "
                           (pearl--completion-table-keep-order
                            (pearl--with-sentinel pearl--default-view-clear
                              (mapcar #'car pearl-local-views)))
                           nil t)))
              (cond
               ((or (null choice) (string-empty-p choice)) :unchanged)
               ((string= choice pearl--default-view-clear) nil)
               (t choice))))))
    (if (eq value :unchanged)
        (message "Default view unchanged")
      (pearl--persist-default-view value)
      (message "Default view set to %s"
               (if value (format "'%s'" value) "my open issues")))))

;;;###autoload
(defun pearl-list-issues-by-project ()
  "List every open Linear issue in a chosen project (all assignees).
Picks a team first (or uses `pearl-default-team-id'), then a project, then
fetches via `pearl-list-issues' with no assignee scoping -- \"by project\"
means the project, not your slice of it."
  (interactive)
  (let* ((team (if pearl-default-team-id
                   (list (cons 'id pearl-default-team-id))
                 (pearl-select-team)))
         (team-id (cdr (assoc 'id team))))
    (if team-id
        (let* ((project (pearl-select-project team-id))
               (project-id (and project (cdr (assoc 'id project))))
               (project-name (and project (cdr (assoc 'name project)))))
          (if project-id
              (progn
                (message "Fetching issues for project: %s" project-name)
                (pearl-list-issues project-id project-name))
            (message "No project selected")))
      (message "No team selected"))))

;;;###autoload
(defun pearl--read-issue-label (team-id)
  "Prompt for an issue-type label in TEAM-ID, returning its label id (or nil).
Labels are grouped by their \" - \" category prefix; the user picks a category
\(or All), then a label, with a fuzzy match used directly when the typed text
resolves to a single label."
  (let* ((issue-types (pearl-get-issue-types team-id))
         (label-names (mapcar #'car issue-types))
         ;; Group labels by category (e.g., "Docs", "Feature", etc.)
         (label-categories (let ((categories (make-hash-table :test 'equal)))
                             (dolist (label label-names)
                               (when-let* ((parts (split-string label " - " t))
                                           (category (car parts)))
                                 (puthash category
                                          (cons label (gethash category categories nil))
                                          categories)))
                             categories))
         (category-names (hash-table-keys label-categories))
         ;; First select a category, then a specific label
         (selected-category (completing-read
                             "Label category: "
                             (append '("All") category-names)
                             nil nil nil nil "All"))
         (filtered-labels (if (string= selected-category "All")
                              label-names
                            (gethash selected-category label-categories nil)))
         (label-prompt (completing-read
                        (if (string= selected-category "All")
                            "Label (type for fuzzy search): "
                          (format "Label in %s category: " selected-category))
                        filtered-labels
                        nil nil nil nil ""))
         (matching-labels (when (not (string-empty-p label-prompt))
                            (cl-remove-if-not
                             (lambda (label-name)
                               (string-match-p (regexp-quote label-prompt) label-name))
                             filtered-labels)))
         (selected-label-name (if (= (length matching-labels) 1)
                                  (car matching-labels)
                                (when matching-labels
                                  (completing-read "Select specific label: " matching-labels nil t)))))
    (when (and selected-label-name (not (string-empty-p selected-label-name)))
      (cdr (assoc selected-label-name issue-types)))))

(defun pearl-create-issue ()
  "Create a new Linear issue with additional attributes."
  (interactive)
  ;; Select team first (needed for states, members, etc.)
  (let* ((team (if pearl-default-team-id
                   (list (cons 'id pearl-default-team-id))
                 (pearl-select-team)))
         (team-id (cdr (assoc 'id team))))

    (if team-id
        (let* ((title (read-string "Issue title: "))
               (description (read-string "Description: "))

               ;; Get workflow states
               (states (pearl-get-states team-id))
               (state-options (when states
                                (mapcar (lambda (state)
                                          (cons (cdr (assoc 'name state))
                                                (cdr (assoc 'id state))))
                                        states)))
               (selected-state (when state-options
                                 (cdr (assoc (completing-read "State: " state-options nil t)
                                             state-options))))

               ;; Get priorities
               (priority-options (pearl-get-priorities))
               (selected-priority (cdr (assoc (completing-read "Priority: " priority-options nil t)
                                              priority-options)))

               ;; Get team members for assignee
               (members (pearl-get-team-members team-id))
               (assignee-prompt (completing-read
                                 "Assignee: "
                                 (mapcar #'car members)
                                 nil nil nil nil ""))
               (selected-assignee (unless (string-empty-p assignee-prompt)
                                    (cdr (assoc assignee-prompt members))))

               ;; Estimate (points)
               (estimate (read-string "Estimate (points, leave empty for none): "))
               (estimate-num (when (and estimate (not (string-empty-p estimate)))
                               (string-to-number estimate)))

               ;; Issue type (label)
               (selected-type (pearl--read-issue-label team-id))

               ;; Get project
               (selected-project (pearl-select-project team-id))
               (selected-project-id (and selected-project (cdr (assoc 'id selected-project))))

               ;; Prepare mutation
               (query "mutation CreateIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
  success
  issue {
  id
  identifier
  title
  }
  }
  }")

               ;; Build input variables
               (input `(("title" . ,title)
                        ("description" . ,description)
                        ("teamId" . ,team-id)
                        ,@(when selected-state
                            `(("stateId" . ,selected-state)))
                        ,@(when selected-priority
                            `(("priority" . ,selected-priority)))
                        ,@(when selected-assignee
                            `(("assigneeId" . ,selected-assignee)))
                        ,@(when estimate-num
                            `(("estimate" . ,estimate-num)))
                        ,@(when selected-type
                            `(("labelIds" . [,selected-type])))
                        ,@(when selected-project-id
                            `(("projectId" . ,selected-project-id)))))

               (response (pearl--graphql-request query `(("input" . ,input)))))

          (let ((issue (pearl--created-issue response)))
            (if issue
                (progn
                  (message "Created issue %s: %s"
                           (cdr (assoc 'identifier issue))
                           (cdr (assoc 'title issue)))
                  issue)
              (message "Failed to create issue"))))

      (message "No team selected"))))

;;;###autoload
(defun pearl-test-connection ()
  "Test the connection to Linear API."
  (interactive)
  (pearl--log "Testing connection to Linear API")
  (pearl--progress "Testing Linear API connection...")

  (let* ((query "query { viewer { id name } }"))
    (pearl--graphql-request-async
     query
     nil
     (lambda (response)
       (if response
           (let ((viewer (assoc 'viewer (assoc 'data response))))
             (message "Connected to Linear as: %s" (cdr (assoc 'name viewer))))
         (message "Failed to connect to Linear API")))
     (lambda (_error _response _data)
       (message "Failed to connect to Linear API")))))

;;;###autoload
(defun pearl-toggle-debug ()
  "Toggle debug logging for Linear API requests."
  (interactive)
  (setq pearl-debug (not pearl-debug))
  (message "Linear debug mode %s" (if pearl-debug "enabled" "disabled")))

;;;###autoload
(defun pearl-check-setup ()
  "Check if Pearl is properly set up, then test the connection.
Under accounts mode reports on the active account (resolving the default on
first need) rather than the legacy `pearl-api-key' global, which is normally
unset once `pearl-accounts' is configured."
  (interactive)
  (if pearl-accounts
      (condition-case err
          (let ((ctx (pearl--current-account-context)))
            (message "Account %s is set up (key resolved). Testing connection..."
                     (plist-get ctx :name))
            (pearl-test-connection))
        (error (message "Pearl accounts are configured but not usable: %s"
                        (error-message-string err))))
    (if pearl-api-key
        (progn
          (message "API key is set (length: %d). Testing connection..." (length pearl-api-key))
          (pearl-test-connection))
      (message "Linear API key is not set. Use M-x customize-variable RET pearl-api-key"))))

;;;###autoload
(defun pearl-load-api-key-from-env ()
  "Try to load Linear API key from environment variable.
Legacy single-account path only: once `pearl-accounts' is configured this
refuses, so it can't bypass the per-account resolver and overwrite the active
account's key in memory.  Use `:api-key-source (:env \"...\")' in
`pearl-accounts' instead."
  (interactive)
  (when pearl-accounts
    (user-error
     "Accounts are configured; put :api-key-source (:env \"...\") in `pearl-accounts'"))
  (let ((env-key (getenv "LINEAR_API_KEY")))
    (if env-key
        (progn
          (setq pearl-api-key env-key)
          (message "Loaded Linear API key from LINEAR_API_KEY environment variable"))
      (message "LINEAR_API_KEY environment variable not found or empty"))))

;;; Comment Editing

(defface pearl-editable-comment
  '((t :inherit success))
  "Face for comment headings the current user can edit."
  :group 'pearl)

(defface pearl-readonly-comment
  '((((background dark)) :foreground "gray40")
    (((background light)) :foreground "gray60")
    (t :inherit shadow))
  "Face for comments the current user cannot edit, dimmed to read as disabled.
Darker than the stock `shadow' grey so a read-only comment clearly recedes."
  :group 'pearl)

(defun pearl--comment-editable-p (author-id viewer-id)
  "Return non-nil when a comment by AUTHOR-ID is editable by VIEWER-ID.
Editable only when both ids are present and equal; a nil or empty AUTHOR-ID
\(bot or external comment) is never editable."
  (and author-id viewer-id
       (not (string-empty-p author-id))
       (string= author-id viewer-id)))

(defun pearl--viewer-async (callback)
  "Resolve the current Linear viewer and call CALLBACK with a plist (:id :name).
Caches the result in `pearl--cache-viewer'; calls CALLBACK with nil on a
transport or GraphQL failure."
  (if pearl--cache-viewer
      (funcall callback pearl--cache-viewer)
    (pearl--graphql-request-async
     "query { viewer { id name } }" nil
     (lambda (data)
       (let ((v (cdr (assoc 'viewer (assoc 'data data)))))
         (funcall callback
                  (when v
                    (setq pearl--cache-viewer
                          (list :id (cdr (assoc 'id v))
                                :name (cdr (assoc 'name v))))))))
     (lambda (_error _response _data) (funcall callback nil)))))

(defun pearl--fetch-comment-body-async (comment-id callback)
  "Fetch COMMENT-ID's current body from Linear.
CALLBACK is called with the markdown body string on success, or nil on error."
  (let ((query "query CommentBody($id: String!) {
  comment(id: $id) { body }
  }")
        (variables `(("id" . ,comment-id))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let ((comment (cdr (assoc 'comment (assoc 'data data)))))
         (funcall callback (when comment (or (cdr (assoc 'body comment)) "")))))
     (lambda (_error _response _data) (funcall callback nil)))))

(defun pearl--update-comment-async (comment-id body callback)
  "Push BODY as COMMENT-ID's text via commentUpdate.
CALLBACK is called with a plist (:success BOOL)."
  (let ((query "mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: {body: $body}) {
  success
  comment { id body }
  }
  }")
        (variables `(("id" . ,comment-id) ("body" . ,body))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let* ((payload (cdr (assoc 'commentUpdate (assoc 'data data))))
              (success (eq t (cdr (assoc 'success payload)))))
         (funcall callback (list :success success))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

(defun pearl--delete-comment-async (comment-id callback)
  "Delete COMMENT-ID on Linear via commentDelete.
CALLBACK receives a plist (:success BOOL).  Verified live (2026-05-25):
`commentDelete' removes the comment immediately with no API restore path, so
unlike `issueDelete' this is not a recoverable soft delete."
  (let ((query "mutation CommentDelete($id: String!) {
  commentDelete(id: $id) { success }
  }")
        (variables `(("id" . ,comment-id))))
    (pearl--graphql-request-async
     query variables
     (lambda (data)
       (let ((payload (cdr (assoc 'commentDelete (assoc 'data data)))))
         (funcall callback
                  (list :success (eq t (cdr (assoc 'success payload)))))))
     (lambda (_error _response _data) (funcall callback '(:success nil))))))

(defun pearl--apply-comment-highlights (viewer-id)
  "Color every comment heading in the buffer by editability for VIEWER-ID.
The viewer's own comments get `pearl-editable-comment' on the heading line; all
others get `pearl-readonly-comment' over the whole comment subtree (heading and
body) so a comment you cannot edit reads as disabled.  Idempotent: clears prior
highlights first."
  (save-excursion
    (remove-overlays (point-min) (point-max) 'pearl-comment t)
    (goto-char (point-min))
    (while (re-search-forward "^\\*+ " nil t)
      ;; Point is now just past the leading stars + space.  Start the overlay
      ;; here, not at the line beginning, so the stars (and the bullet a package
      ;; like org-superstar composes from them) keep org's own fontification
      ;; instead of being recolored by our face.
      (let ((text-start (point))
            (comment-id (org-entry-get nil "LINEAR-COMMENT-ID")))
        (when comment-id
          (let* ((editable (pearl--comment-editable-p
                            (org-entry-get nil "LINEAR-COMMENT-AUTHOR-ID")
                            viewer-id))
                 (face (if editable 'pearl-editable-comment 'pearl-readonly-comment))
                 ;; Editable: heading text only, so your own comment reads
                 ;; normally.  Read-only: through the whole subtree, dimming the
                 ;; body too.
                 (end (if editable
                          (line-end-position)
                        (save-excursion (org-end-of-subtree t t) (point))))
                 (ov (make-overlay text-start end)))
            (overlay-put ov 'pearl-comment t)
            (overlay-put ov 'face face)))))))

;;;###autoload
(defun pearl-highlight-comments ()
  "Color comment headings in the current buffer by who can edit them.
The viewer's own comments render green (editable); others render greyed.  Runs
after a fetch/refresh, and is safe to invoke by hand."
  (interactive)
  (let ((buffer (current-buffer)))
    ;; Best-effort: highlighting is a display nicety and must never abort the
    ;; operation that triggered it (e.g. a missing API key errors in the
    ;; request layer), so a failure to resolve the viewer just skips coloring.
    (ignore-errors
      (pearl--viewer-async
       (lambda (viewer)
         (when (and viewer (buffer-live-p buffer))
           (with-current-buffer buffer
             (pearl--apply-comment-highlights (plist-get viewer :id)))))))))

;;;###autoload
(defun pearl-edit-current-comment ()
  "Push an edit to the comment at point on Linear.
Works from anywhere inside a comment's subtree.  Only the current user's own
comments are editable: a comment authored by anyone else (or by a bot or
integration) is refused without a network call.  The push is gated like the
description sync -- unchanged since fetch sends nothing, a local edit against
an unchanged remote pushes, and a both-sides-changed case is refused and
reported (refresh to reconcile)."
  (interactive)
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-heading-or-error "Not on a Linear comment")
    (let ((comment-id (org-entry-get nil "LINEAR-COMMENT-ID"))
          (marker (point-marker))
          (buf (current-buffer)))
      (unless comment-id
        (user-error "Not on a Linear comment"))
      ;; No-op fast path before resolving the viewer: an unchanged comment costs
      ;; no viewer lookup.  The dirty check is Org-to-Org (see
      ;; `pearl--comment-dirty-p'), so a comment whose markdown does not survive
      ;; the round-trip is not falsely seen as edited.
      (if (not (pearl--comment-dirty-p))
          (message "No comment changes to sync")
        (pearl--viewer-async
         (lambda (viewer)
           (pearl--save-comment-field
            marker (and viewer (plist-get viewer :id))
            (lambda (outcome) (pearl--report-save-outcome outcome buf)))))))))

;;;###autoload
(defun pearl-delete-current-comment ()
  "Delete the comment at point on Linear after confirmation, removing its subtree.
Works from anywhere inside a comment's subtree.  Only your own comments are
deletable: a comment authored by anyone else (or a bot/integration) is refused
without a `commentDelete' call.  The delete is permanent -- Linear's
`commentDelete' has no API restore path -- so a locally edited comment, or one
with no stored hash, gets a stronger discard-local-edits confirmation.  On
success the comment's Org subtree is removed; sibling comments and the issue
body stay."
  (interactive)
  (pearl--require-account-context t)
  (save-excursion
    (pearl--goto-heading-or-error "Not on a Linear comment")
    (let ((comment-id (org-entry-get nil "LINEAR-COMMENT-ID"))
          (author-id (org-entry-get nil "LINEAR-COMMENT-AUTHOR-ID"))
          (stored (org-entry-get nil "LINEAR-COMMENT-SHA256"))
          (marker (point-marker))
          (buf (current-buffer)))
      (unless comment-id
        (user-error "Not on a Linear comment"))
      (pearl--viewer-async
       (lambda (viewer)
         (cond
          ((null viewer)
           (message "Could not determine your Linear identity; not deleting"))
          ((not (pearl--comment-editable-p author-id (plist-get viewer :id)))
           (message "You can only delete your own comments"))
          (t
           ;; A clean comment (stored hash present and matching the rendered
           ;; body) gets the plain prompt; a locally edited body or a missing
           ;; hash (unknown provenance) gets the discard wording.  The delete
           ;; proceeds either way (decision 2).
           (let* ((clean (and stored
                              (string= (secure-hash 'sha256
                                                    (pearl--org-to-md
                                                     (org-with-point-at marker
                                                       (pearl--entry-body-at-point))))
                                       stored)))
                  (prompt (if clean
                              "Delete this comment from Linear and remove it here? "
                            "Delete this comment from Linear and discard your local edits here? ")))
             (when (yes-or-no-p prompt)
               (pearl--delete-comment-async
                comment-id
                (lambda (result)
                  (if (plist-get result :success)
                      (when (buffer-live-p buf)
                        (org-with-point-at marker
                          (org-back-to-heading t)
                          (delete-region (point)
                                         (progn (org-end-of-subtree t t) (point))))
                        (message "Deleted comment from Linear")
                        (pearl--surface-buffer buf))
                    (message "Failed to delete comment")))))))))))))

;;; Transient Menu

;;;###autoload (autoload 'pearl-menu "pearl" nil t)
(transient-define-prefix pearl-menu ()
  "Dispatch menu for pearl commands."
  ;; Grouped to mirror the `pearl-prefix-map' categories: Fetch is issue
  ;; sources only, Views is its own group, Workspace holds account switching
  ;; plus setup.  The hot keys `s' / `S' / `d' (save / save-all /
  ;; edit-description) match the keymap's direct keys.  The transient is a
  ;; flat keyspace -- every command needs a unique key on the screen -- so the
  ;; remaining letters are read off the menu rather than matching the keymap's
  ;; two-key chains.  Set-default-view has no command yet, so it gets no slot
  ;; here (the keymap reserves `v D' for it).  The org-sync commands (enable /
  ;; disable / push-file) are deliberately not surfaced -- they are plumbing.
  ["Issue"
   ["Save"
    ("s" "save issue" pearl-save-issue)
    ("S" "save all" pearl-save-all)]
   ["Edit"
    ("d" "edit description" pearl-edit-description)
    ("t" "edit state" pearl-edit-state)
    ("a" "edit assignee" pearl-edit-assignee)
    ("L" "edit labels" pearl-edit-labels)
    ("M" "edit comment" pearl-edit-current-comment)]
   ["Create"
    ("n" "create issue" pearl-create-issue)
    ("c" "create comment" pearl-create-comment)]
   ["Delete"
    ("k" "delete issue" pearl-delete-current-issue)
    ("K" "delete comment" pearl-delete-current-comment)]]
  ["Workspace"
   ["Fetch"
    ("P" "pick source" pearl-pick-source)
    ("l" "open default view" pearl-open-default-view)
    ("m" "my open issues" pearl-list-issues)
    ("p" "by project" pearl-list-issues-by-project)
    ("f" "build a filter" pearl-list-issues-filtered)]
   ["Views"
    ("V" "create local view" pearl-create-local-view)
    ("e" "edit local view" pearl-edit-local-view)
    ("Q" "run local view" pearl-run-local-view)
    ("v" "run Linear view" pearl-run-linear-view)
    ("u" "publish local view" pearl-publish-local-view)
    ("D" "save Linear view locally" pearl-save-linear-view-locally)
    ("U" "publish current view" pearl-publish-current-view)
    ("X" "delete local view" pearl-delete-local-view)
    ("." "set default view" pearl-set-default-view)]
   ["Buffer"
    ("g" "refresh view" pearl-refresh-current-view)
    ("r" "refresh issue" pearl-refresh-current-issue)
    ("b" "open view in Linear" pearl-open-current-view-in-linear)
    ("o" "open issue in browser" pearl-open-current-issue)
    ("y" "copy issue URL" pearl-copy-issue-url)]
   ["Workspace / setup"
    ("A" "switch account" pearl-switch-account)
    ("T" "test connection" pearl-test-connection)
    ("C" "check setup" pearl-check-setup)
    ("!" "toggle debug" pearl-toggle-debug)
    ("x" "clear cache" pearl-clear-cache)]])

;;; Prefix Keymap and minor mode
;;
;; A prefix keymap that makes the whole command surface reachable from the
;; keyboard.  The hot-path commands sit directly under the prefix (one key);
;; the rest are grouped into category sub-maps (two keys): fetch (issue
;; sources), views, edit, create, delete, open, copy, and workspace (account
;; + setup).  The most common commands appear in both places -- e.g.
;; edit-description is the direct `d' and also `e d' under the edit group.
;;
;; Each binding is a (LABEL . COMMAND) menu item, so `which-key' shows the
;; verb-matched label without pearl depending on which-key.  Lookups still
;; resolve straight to the command.
;;
;; `pearl-mode' (below) binds this map under `pearl-keymap-prefix' inside
;; Pearl-rendered buffers and turns on automatically, so the keys are live
;; without any global setup.  To bind the map globally as well:
;;
;;   (global-set-key (kbd "C-; L") pearl-prefix-map)
;;
;; Priority has no edit command -- it is edited org-natively via the heading
;; cookie (C-c , / S-up).  State also cycles org-natively (C-c C-t); the
;; picker `pearl-edit-state' (e s) reaches any team state.

(defvar pearl-fetch-map
  (let ((map (make-sparse-keymap)))
    (define-key map "s" (cons "pick source" #'pearl-pick-source))
    (define-key map "o" (cons "my open issues" #'pearl-list-issues))
    (define-key map "p" (cons "by project" #'pearl-list-issues-by-project))
    (define-key map "f" (cons "build a filter" #'pearl-list-issues-filtered))
    map)
  "Pearl issue-fetch commands; a sub-keymap of `pearl-prefix-map'.
Issue sources only -- pick a source, your open issues, a project, or an
ad-hoc filter.  View-movement commands (run / publish / save-locally) live
in `pearl-views-map' so this group stays one concern.")

(defvar pearl-views-map
  (let ((map (make-sparse-keymap)))
    (define-key map "l" (cons "run local view" #'pearl-run-local-view))
    (define-key map "L" (cons "run Linear view" #'pearl-run-linear-view))
    (define-key map "c" (cons "create local view" #'pearl-create-local-view))
    (define-key map "e" (cons "edit local view" #'pearl-edit-local-view))
    (define-key map "k" (cons "delete local view" #'pearl-delete-local-view))
    (define-key map "u" (cons "publish local view" #'pearl-publish-local-view))
    (define-key map "U" (cons "publish current view" #'pearl-publish-current-view))
    (define-key map "d" (cons "save Linear view locally" #'pearl-save-linear-view-locally))
    (define-key map "D" (cons "set default view" #'pearl-set-default-view))
    map)
  "Pearl view commands; a sub-keymap of `pearl-prefix-map'.
Lowercase `l' / capital `L' run a local / Linear view; `c' / `e' / `k'
create / edit / delete a local view.  `u' / `U' publish a named / the
current local view up to Linear; `d' saves a Linear view down into a new
local view.  Capital `D' sets the default view `pearl-open-default-view'
opens.")

(defvar pearl-edit-map
  (let ((map (make-sparse-keymap)))
    (define-key map "d" (cons "edit description" #'pearl-edit-description))
    (define-key map "s" (cons "edit state" #'pearl-edit-state))
    (define-key map "a" (cons "edit assignee" #'pearl-edit-assignee))
    (define-key map "l" (cons "edit labels" #'pearl-edit-labels))
    (define-key map "c" (cons "edit comment" #'pearl-edit-current-comment))
    map)
  "Pearl issue-field edit commands; a sub-keymap of `pearl-prefix-map'.
Editing a local view lives in `pearl-views-map' (`v e').")

(defvar pearl-create-map
  (let ((map (make-sparse-keymap)))
    (define-key map "t" (cons "create issue" #'pearl-create-issue))
    (define-key map "c" (cons "create comment" #'pearl-create-comment))
    map)
  "Pearl create commands; a sub-keymap of `pearl-prefix-map'.
Creating a local view lives in `pearl-views-map' (`v c').")

(defvar pearl-delete-map
  (let ((map (make-sparse-keymap)))
    (define-key map "t" (cons "delete issue" #'pearl-delete-current-issue))
    (define-key map "c" (cons "delete comment" #'pearl-delete-current-comment))
    map)
  "Pearl delete commands; a sub-keymap of `pearl-prefix-map'.
Deleting a local view lives in `pearl-views-map' (`v k').")

(defvar pearl-workspace-map
  (let ((map (make-sparse-keymap)))
    (define-key map "a" (cons "switch account" #'pearl-switch-account))
    (define-key map "t" (cons "test connection" #'pearl-test-connection))
    (define-key map "c" (cons "check setup" #'pearl-check-setup))
    (define-key map "!" (cons "toggle debug" #'pearl-toggle-debug))
    (define-key map "x" (cons "clear cache" #'pearl-clear-cache))
    map)
  "Pearl workspace and setup commands; a sub-keymap of `pearl-prefix-map'.
`a' switches the active Linear account; the rest are connection / setup
diagnostics.")

(defvar pearl-open-map
  (let ((map (make-sparse-keymap)))
    (define-key map "i" (cons "open issue in browser" #'pearl-open-current-issue))
    (define-key map "v" (cons "open view in Linear" #'pearl-open-current-view-in-linear))
    map)
  "Pearl open commands; a sub-keymap of `pearl-prefix-map'.")

(defvar pearl-copy-map
  (let ((map (make-sparse-keymap)))
    (define-key map "u" (cons "copy issue URL" #'pearl-copy-issue-url))
    map)
  "Pearl copy commands; a sub-keymap of `pearl-prefix-map'.")

(defvar pearl-prefix-map
  (let ((map (make-sparse-keymap)))
    ;; Hot path -- one key under the prefix.
    (define-key map "l" (cons "open default view" #'pearl-open-default-view))
    (define-key map "g" (cons "refresh view" #'pearl-refresh-current-view))
    (define-key map "r" (cons "refresh issue" #'pearl-refresh-current-issue))
    (define-key map "s" (cons "save issue" #'pearl-save-issue))
    (define-key map "S" (cons "save all" #'pearl-save-all))
    (define-key map "d" (cons "edit description" #'pearl-edit-description))
    (define-key map "m" (cons "menu" #'pearl-menu))
    ;; Category sub-maps -- two keys; each prefix names an action verb or noun.
    (define-key map "f" (cons "fetch..." pearl-fetch-map))
    (define-key map "v" (cons "views..." pearl-views-map))
    (define-key map "e" (cons "edit..." pearl-edit-map))
    (define-key map "c" (cons "create..." pearl-create-map))
    (define-key map "k" (cons "delete..." pearl-delete-map))
    (define-key map "o" (cons "open..." pearl-open-map))
    (define-key map "y" (cons "copy..." pearl-copy-map))
    (define-key map "w" (cons "workspace..." pearl-workspace-map))
    map)
  "Pearl command prefix keymap.
Hot-path commands are bound directly; the rest live under sub-maps
\(fetch / views / edit / create / delete / open / copy / workspace).  Fetch is
issue sources only; views have their own group; workspace holds account
switching and setup.  `pearl-mode' binds this under `pearl-keymap-prefix'
inside Pearl buffers; you can also bind it globally (see the Commentary
above).")

(defcustom pearl-keymap-prefix "C-; L"
  "Prefix key that `pearl-mode' binds to `pearl-prefix-map'.
Inside a Pearl-rendered buffer this makes the whole command surface reachable
without any global binding.  Set to nil to bind nothing (then bind
`pearl-prefix-map' yourself).  Changing this through Customize updates
`pearl-mode-map' immediately; setting it by hand needs `pearl-mode' re-enabled
in already-open buffers."
  :type '(choice (key-sequence :tag "Prefix") (const :tag "None" nil))
  :group 'pearl
  :set (lambda (sym val)
         (set-default sym val)
         (when (boundp 'pearl-mode-map)
           ;; Rebuild the mode map so a customized prefix takes effect.
           (setcdr pearl-mode-map nil)
           (when val
             (define-key pearl-mode-map (kbd val) pearl-prefix-map)))))

(defvar pearl-mode-map
  (let ((map (make-sparse-keymap)))
    (when pearl-keymap-prefix
      (define-key map (kbd pearl-keymap-prefix) pearl-prefix-map))
    map)
  "Keymap for `pearl-mode'.")

;;;###autoload
(define-minor-mode pearl-mode
  "Minor mode for Pearl's Linear org buffers.
Binds `pearl-prefix-map' under `pearl-keymap-prefix' so every Pearl command is
reachable from the keyboard.  Turns on automatically in any buffer Pearl
rendered (one carrying a `#+LINEAR-SOURCE' header); see
`pearl--maybe-enable-mode' on `org-mode-hook'.
On enable it also collapses the `#+' keyword preamble (see
`pearl--hide-preamble'), so opening a Linear file hides it the same way a fresh
fetch does."
  :lighter (:eval (pearl--mode-line-lighter))
  :keymap pearl-mode-map
  (when pearl-mode
    (pearl--hide-preamble)))

(defun pearl--buffer-is-pearl-p ()
  "Non-nil when the current buffer is a Pearl-rendered Linear file.
Detected by the `#+LINEAR-SOURCE' header Pearl writes into every view; the
search is bounded to the file preamble so it stays cheap on large buffers."
  (save-excursion
    (goto-char (point-min))
    (let ((case-fold-search t))
      (re-search-forward "^#\\+LINEAR-SOURCE:" 4000 t))))

(defun pearl--maybe-enable-mode ()
  "Enable `pearl-mode' when the current org buffer is a Pearl Linear file.
Hung on `org-mode-hook'; a no-op in any other org buffer."
  (when (and (derived-mode-p 'org-mode) (pearl--buffer-is-pearl-p))
    (pearl-mode 1)))

;; Registered at load, not via an autoload cookie: an autoloaded hook would
;; fire before pearl is loaded (calling a void function) and would pull all of
;; pearl into every org buffer the user opens.  Once any autoloaded pearl
;; command has loaded the package, this hook auto-enables the mode in Pearl
;; files; freshly fetched buffers are also enabled directly in the writer.
(add-hook 'org-mode-hook #'pearl--maybe-enable-mode)

(provide 'pearl)
;;; pearl.el ends here