feat(render): render issue titles and the view name verbatim

The buffer should mirror Linear: a value on the page appears exactly as Linear stores it, so the heading title matches what you'd see opening the issue in Linear itself. I flipped pearl-title-case-headings to default nil so titles render verbatim. I also stopped running the view name in the #+title through the title-caser, which was coupled to the same flag. The smart-title-case path stays as opt-in tidying for anyone who wants it.

Two transformations remain, both forced by Org's syntax rather than chosen: state names become TODO keywords (Org keywords can't contain spaces, so the real name stays in the LINEAR-STATE-NAME drawer), and descriptions and comments convert between Markdown and Org. Documented under "Fidelity to Linear" in the README.

1 files changed, 13 insertions, 0 deletions

diff --git a/README.org b/README.org
index ad6c5a6..6dd3b92 100644
--- a/README.org
+++ b/README.org
@@ -266,6 +266,18 @@ A fetched Pearl file is intentionally readable. The header records the source, r
 
 The =LINEAR-*= properties store both ids and display names so common commands do not need a network lookup just to render. The hash properties are provenance for conflict-aware sync.
 
+*** Fidelity to Linear
+:PROPERTIES:
+:CUSTOM_ID: fidelity-to-linear
+:END:
+
+Anything on the page that is Linear's data renders verbatim — the buffer shows the same text you would see opening the issue in Linear itself. Titles, the view name, assignee and label names, comment bodies: Pearl does not re-case, reword, or tidy them. There are exactly two transformations, and both are forced by Org's own syntax rather than chosen:
+
+- *State names become TODO keywords.* Org keywords cannot contain spaces, so "Dev Review" renders as the keyword =DEV-REVIEW=. The real state name is preserved verbatim in the =:LINEAR-STATE-NAME:= drawer property.
+- *Descriptions and comments convert between Markdown and Org.* Linear stores them as Markdown; the buffer renders them as Org and converts back on save. This is a representation translation, not an edit of the content, and round-trips for the supported subset.
+
+If you prefer a tidier outline, =pearl-title-case-headings= opts issue titles into smart title case (off by default, so titles match Linear out of the box).
+
 ** Configuration
 :PROPERTIES:
 :CUSTOM_ID: configuration
@@ -282,6 +294,7 @@ Most users only need an API key and an output path. The rest are knobs for teams
 | =pearl-max-issue-pages=       | Pagination cap, 100 issues per page               |
 | =pearl-request-timeout=       | Synchronous request timeout in seconds            |
 | =pearl-fold-after-update=     | Re-fold the active page after fetch/refresh       |
+| =pearl-title-case-headings=   | Opt-in smart title case for issue titles (off)    |
 | =pearl-surface-buffer=        | Show the active buffer after a command updates it |
 | =pearl-surface-select-window= | Move focus to the surfaced buffer                 |
 | =pearl-debug=                 | Log request/response details to =*Messages*=        |