From 00f218a13add7fce072879da0749ee2afe6d4a6f Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Thu, 28 May 2026 01:36:14 -0500
Subject: docs(README): explain that pearl follows browse-url-browser-function

A new "Which browser opens for Linear URLs" subsection under Configuration names the fact that pearl hands every URL to `browse-url' and never picks a browser of its own, so the answer to "why this browser?" is always the Emacs setting. Lists the common values for `browse-url-browser-function' (default-browser, xdg-open, firefox / chrome, generic) and points at `browse-url-handlers' for per-URL routing.
---
 README.org | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.org b/README.org
index 0c78722..f6323f5 100644
--- a/README.org
+++ b/README.org
@@ -337,6 +337,21 @@ Most users only need an API key and an output path. The rest are knobs for teams
 
 If a fetch stops at the pagination cap, Pearl writes =#+LINEAR-TRUNCATED: yes= in the file header. Raise =pearl-max-issue-pages= if your result set is larger than the default 1000 issues.
 
+*** Which browser opens for Linear URLs
+
+Pearl hands every URL it opens (issue links, view links, browser-only favorites) to Emacs's =browse-url=, which dispatches to whatever =browse-url-browser-function= names. Pearl never picks a browser of its own, so the answer to "why this browser?" is always your Emacs setting, not pearl. Your system default ($BROWSER, xdg-mime) only matters when =browse-url-browser-function= delegates to it.
+
+Common shapes:
+
+| Value                                       | Behavior                                                       |
+|---------------------------------------------+----------------------------------------------------------------|
+| ='browse-url-default-browser=               | Emacs autodetects (usually correct)                            |
+| ='browse-url-xdg-open=                      | Honor the desktop default (=xdg-mime= for http/https)          |
+| ='browse-url-firefox= / =-chrome= / =-chromium= | Always that browser                                            |
+| ='browse-url-generic= + =browse-url-generic-program= | Any command you name                                           |
+
+For per-URL routing (e.g. "Linear goes to the work-account browser, everything else to my personal one"), set =browse-url-handlers= with a list of =(REGEXP . FUNCTION)= pairs.
+
 ** Development & Testing
 :PROPERTIES:
 :CUSTOM_ID: development--testing
-- 
cgit v1.2.3