building-psych-explainers

Building psych explainers

Each explainer is one page on a site that already exists.

Site: What that therapy word means Repo: ~/git/what-that-therapy-word-means (GitHub rianvdm/what-that-therapy-word-means) Live: https://therapy-words.com (custom domain on its own zone since 2026-09-04; the canonical host in every page's tags). https://befriending-your-nervous-system..workers.dev still serves the same files — the Worker kept its original name when the repo was renamed — and the previous home, therapywords.elezea.com, is a 301 redirect rule on the elezea.com zone

public/
  index.html            landing page; one <a class="shelf-slab"> per explainer
  assets/explainer.css  the entire design system, shared by every page
  <slug>/index.html     one explainer
wrangler.jsonc          assets-only Worker: no main, no assets.binding

Start by copying an existing page under public/ as the skeleton. A new page adds markup and inline SVG. It does not add styles — if you need a style that is not in explainer.css, add it there so every page gets it.

Order of work

1. Source it. Find where the originator explains the idea in their own words — a transcript, a talk, their own book or site — and fetch that page. Quote from it. The best source is often a PDF transcript, and a 27-page interview yields far more quotable wording than any summary of it. WebFetch cannot read a PDF — it saves the binary locally and tells you where. Extract it with the macOS PDFKit recipe in .opencode/command/extract-pdf.md, which needs no install and no network. Do not go looking for pdftotext, mutool, qpdf, gs, pypdf or Quartz-for-system- python — none of them are on this machine, and building a venv to get one is a detour around a tool that already works. For an HTML transcript, curl the page and strip the tags yourself. WebFetch runs a summariser that refuses to return long verbatim passages (on TIST it answered a request for the transcript with a note about a 125-character quote limit). The raw page was 8,000 words and read straight through in one go; that is where every spoken quote on the page came from. When the originator's own words exist only behind a paywall (EMDR: Shapiro's park story is in a journal PDF that serves an HTML block page), tell that part from their organisation's own page and quote them elsewhere. Do not quote via a blog that quotes them — the wording cannot be checked.
2. Check the evidence. Search for the state of the research and write down what you actually find. This goes in the footer whether it is flattering or not. Publisher pages (ScienceDirect, Taylor & Francis, Springer, PubMed) 403 or cookie-wall WebFetch. Get abstracts with numbers from Europe PMC instead: curl -s "https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=DOI:<doi>&format=json&resultType=core" returns abstractText; Crossref confirms the DOI, title and authors. Guideline PDFs read through the PDFKit recipe once downloaded.
3. Draft the arc from the beats below.
4. Build the page.
5. Run all five checks. Fix what they surface. Brevity first, because every later check can be satisfied by adding words; the voice pass last, because cutting is what breaks the voice, and it is the one Rian reads for.
6. Show Rian the prose before anything goes live — the page is public writing.
7. Add the index entry, deploy, byte-compare live against the repo file.