docs(scripts): add a scripts README

scripts/README.org is the single home for documentation about the helpers under scripts/. A Purpose section says what the file is for, then one heading per script with its purpose, usage, and notes. It documents seed_pearl_workspace.py (including the Linear constraints that shaped its reconcile model) and coverage-summary.el, and asks that new scripts add a heading here too.

1 files changed, 100 insertions, 0 deletions

diff --git a/scripts/README.org b/scripts/README.org
new file mode 100644
index 0000000..5ee298e
--- /dev/null
+++ b/scripts/README.org
@@ -0,0 +1,100 @@
+#+TITLE: Pearl Scripts
+#+AUTHOR: Craig Jennings
+
+* Purpose
+
+This file is the single home for documentation about the helper scripts under
+=scripts/=. These scripts aren't part of pearl.el itself. They're development
+and setup tooling that sits alongside the package: workspace seeding, coverage
+reporting, and whatever else lands here later. Each script gets its own heading
+below with what it's for, how to run it, and any notes worth knowing before you
+use it. When you add a script, add a heading here too.
+
+* seed_pearl_workspace.py
+
+** Purpose
+
+Brings a Linear workspace up to Pearl's dogfooding conventions in one run:
+
+- a "Pearl" team whose columns are the six Agile states (Icebox, Triage Queue,
+  Backlog, In Progress, Done, Canceled),
+- a "Pearl" project inside that team,
+- three Custom Views: Pearl Open Issues, Pearl Icebox, Pearl Inbox.
+
+It's idempotent. It reconciles against whatever's already there by name, so a
+second run changes nothing. It's reusable for us and for anyone standing up the
+same setup.
+
+** Usage
+
+The script reads the Linear API key from the =LINEAR_API_KEY= environment
+variable.
+
+#+begin_src bash
+  # preview the plan without changing anything
+  LINEAR_API_KEY=lin_api_... python3 scripts/seed_pearl_workspace.py --dry-run
+
+  # run it
+  LINEAR_API_KEY=lin_api_... python3 scripts/seed_pearl_workspace.py
+#+end_src
+
+Run the tests with pytest:
+
+#+begin_src bash
+  pytest scripts/tests/test_seed_pearl_workspace.py
+#+end_src
+
+The personal key lives in a gitignored =apikey.txt= at the repo root, never in
+the repo. A convenient way to pass it:
+
+#+begin_src bash
+  LINEAR_API_KEY="$(tr -d '[:space:]' < apikey.txt)" python3 scripts/seed_pearl_workspace.py
+#+end_src
+
+** Notes
+
+- *Reconcile, not create-from-scratch.* Linear's =teamCreate= seeds its own
+  default columns, and Linear dedups state names case-insensitively, so a naive
+  "create all six" run collides with the defaults. The script instead renames
+  the defaults into the six Agile columns (keeping Backlog, In Progress, Done,
+  Canceled, and repurposing the unstarted Todo as Triage Queue) and creates
+  only the genuinely-new Icebox.
+
+- *It never archives.* A Linear team must keep at least one unstarted state, and
+  the Duplicate state is reserved, so neither can be removed by API. The script
+  leaves any column it doesn't claim (Duplicate, which Linear hides in the board
+  UI) and reports it rather than failing.
+
+- *Positions are set in a second pass with distinct nonzero values.* Linear
+  ignores a 0.0 position and appends a freshly-created state at a high one, so
+  the script updates positions after the states exist.
+
+- *Grouping isn't set at view-create time.* Linear's =CustomViewCreateInput= has
+  no grouping field, so Pearl Open Issues is created with its filter only. Group
+  it by category in pearl with =pearl-set-grouping=, or in the Linear UI.
+
+- *Triage Queue is the unstarted type* (it took over the default Todo). pearl's
+  grouped view orders sections by state type and then position, so Triage Queue
+  lists after the backlog columns in pearl even though the Linear board keeps
+  your column order.
+
+* coverage-summary.el
+
+** Purpose
+
+The batch helper behind =make coverage-summary=. It parses the SimpleCov JSON
+that =make coverage= writes and prints a terminal summary: per-file covered and
+total executable lines with a percent (worst-covered first), plus a
+line-weighted project figure. Without it, =make coverage= reports little more
+than the HTML report's file size.
+
+** Usage
+
+#+begin_src bash
+  make coverage           # run tests with coverage, then print the summary
+  make coverage-summary   # just re-print the summary from the last report
+#+end_src
+
+It's invoked from the Makefile (=coverage= and =coverage-summary= targets) with
+=emacs -batch -L scripts -l coverage-summary=, so there's no need to call it
+directly.