1 files changed, 56 insertions, 0 deletions
diff --git a/scripts/README.org b/scripts/README.org
index e6bacd2..5d5ab6d 100644
--- a/scripts/README.org
+++ b/scripts/README.org
@@ -82,6 +82,62 @@ the repo. A convenient way to pass it:
   default new-issue state at Triage (the intake column) after the columns
   reconcile, so a fresh issue lands there.
 
+* import_org_backlog.py
+
+** Purpose
+
+Imports an org-mode backlog into the Pearl Linear workspace. It reads the
+level-2 =TODO=/=DOING= headings under the "Pearl Open Work" section and creates
+one Linear issue per task, carrying the priority, tags, and body across.
+
+The mapping:
+
+- priority cookie =[#A]= .. =[#D]= becomes Linear priority Urgent .. Low,
+- a =[#D]= "someday" task lands in Icebox, everything above it in Backlog,
+- tags become labels (missing ones are created); the =discuss=, =next=,
+  =cleanup=, and =pearl= workflow markers are dropped rather than turned into
+  labels,
+- the heading body becomes the issue description, minus the property drawer and
+  any sub-entries.
+
+It's idempotent: a task whose title already exists is skipped, so a re-run only
+fills in what's missing. The two umbrella headings (the dogfooding parent and
+the manual-testing checklist) and everything under the Resolved section are left
+out.
+
+** Usage
+
+The script reads the Linear API key from =LINEAR_API_KEY= and takes the org file
+as its argument.
+
+#+begin_src bash
+  # preview the tasks without creating anything
+  python3 scripts/import_org_backlog.py todo.org --dry-run
+
+  # run it
+  LINEAR_API_KEY="$(tr -d '[:space:]' < apikey.txt)" python3 scripts/import_org_backlog.py todo.org
+#+end_src
+
+Run the tests with pytest:
+
+#+begin_src bash
+  pytest scripts/tests/test_import_org_backlog.py
+#+end_src
+
+** Notes
+
+- *Dry-run first.* =--dry-run= parses the file and prints each task with its
+  target state and surviving labels, plus the full label set it would create. It
+  touches the network only on a real run, so it's the safe way to confirm scope
+  before importing.
+
+- *Idempotent by title.* The skip check matches on exact issue title. Editing a
+  task's title in the org file and re-running creates a second issue rather than
+  updating the first, so treat titles as stable once imported.
+
+- *Tags are matched case-insensitively.* An existing =Bug= label is reused for a
+  =:bug:= tag; only genuinely new labels are created.
+
 * coverage-summary.el
 
 ** Purpose