From 6b7edc5b56190842182dfb6ede9b642209eee524 Mon Sep 17 00:00:00 2001
From: Will Estes <westes575@gmail.com>
Date: Wed, 22 Jul 2026 19:36:12 -0400
Subject: [PATCH] Document the gift/lead-magnet partnership pattern

Maps the four repos involved (reground-site, reground-gift-guide,
downloads-uploader, eec-courses) into one SOP, since none of it is
derivable from reading any single repo on its own.
---
 docs/gift-partnerships.md | 103 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/gift-partnerships.md

diff --git a/docs/gift-partnerships.md b/docs/gift-partnerships.md
new file mode 100644
index 0000000..4ae260a
--- /dev/null
+++ b/docs/gift-partnerships.md
@@ -0,0 +1,103 @@
+# Adding a gift/lead-magnet partnership
+
+The `/gift` funnel (opt-in page → PDF → nurture emails) can be customized per
+reader-acquisition partner, each getting its own URL, PDF, and email content. A
+partnership touches four repos. This doc is the map between them; each repo's own
+README covers the details of its own step.
+
+## The URL
+
+`gift.reground.org/<slug>` already works for any `<slug>` with no infrastructure
+changes. `reground-infrastructure`'s Caddy config redirects generically:
+
+```
+gift.reground.org {
+    redir https://reground.org/gift{uri} permanent
+}
+```
+
+So `gift.reground.org/cheyenne` → `https://reground.org/gift/cheyenne` automatically —
+you only ever need to add the Hugo page below.
+
+## 1. reground-site (this repo) — the pages
+
+`content/gift/` is a branch bundle (`_index.md`), so it can hold real child pages. Add
+two leaf bundles per partner:
+
+```
+content/gift/<slug>/index.md          # the opt-in page
+content/gift/<slug>-thanks/index.md   # the delivery/thanks page
+```
+
+Both use `type: "courses"` (rendered by `layouts/courses/single.html`, sharing the
+`courses-body.html` partial with the generic `/gift` page). Front matter fields worth
+setting per partner, copied from `content/gift/_index.md`'s existing example:
+
+- `title`, `hero_subhead`, `cta_text`, `repeat_cta_heading` — the bridging copy
+- `hero_image` — path under `/images/...`; see "cover image" below
+- `eec_slug` — must match the slug used in `eec-courses` (step 4)
+- `success_message` — markdown, should link to this partner's own `<slug>-thanks` page
+
+The `<slug>-thanks` page just needs a title, a short thanks note, and a download link
+pointing at wherever the PDF got uploaded (step 3).
+
+### Cover image
+Not automated. Render page 1 of the partner's built PDF and crop it to the cover block:
+
+```sh
+cd /home/will/opt/src/reground-gift-guide
+pdftoppm -png -f 1 -l 1 -r 150 partners/<slug>.pdf cover
+convert cover-1.png -crop 1275x885+0+0 +repage -resize 640x /home/will/opt/src/reground-site/static/images/gift-<slug>.png
+rm cover-1.png
+```
+(The `885` crop height assumes the cover design hasn't changed — check the rendered PNG
+first if it looks off.)
+
+## 2. reground-gift-guide — the PDF
+
+See that repo's own README. Summary: `cp template.md partners/<slug>.md`, hand-edit the
+title and bridging paragraphs, `make partners/<slug>.pdf`.
+
+## 3. downloads-uploader — hosting the PDF
+
+See that repo's own README. Summary:
+
+```sh
+./upload.sh --site reground --slug <slug> partners/<slug>.pdf
+```
+
+Publishes to `https://downloads.reground.org/<slug>/<slug>.pdf` — that's the URL the
+`<slug>-thanks` page (step 1) should link to.
+
+## 4. eec-courses — delivery + nurture emails
+
+Not engine work — pure content, same shape as the existing generic offer. Copy both
+directories:
+
+```
+courses/three-steps-find-your-right-readers/          → courses/<eec_slug>/
+courses/welcome-three-steps-find-your-right-readers/  → courses/welcome-<eec_slug>/
+```
+
+Each is a `course.yml` (metadata: `slug`, `name`, `from_email`, `ceiling_hours`, `steps`)
+plus a `day-0.md` (YAML front matter: `subject`, `list_name`, `redirect_url`, `enroll:`
+chaining to the welcome sequence's slug — followed by the email body in markdown).
+Update:
+
+- `course.yml`'s `slug` and `name` in both directories (must match `eec_slug` used in
+  step 1, and the welcome sequence's slug referenced by `enroll:`)
+- `day-0.md`'s `subject`, body copy, and `redirect_url` (→ the `<slug>-thanks` page,
+  step 1) in the first course
+- The welcome sequence's `day-0.md` copy, to reference the partner instead of the
+  generic offer
+
+No changes needed in `will/eec` (the engine processes any slug with a valid
+`course.yml` generically).
+
+## Verification
+1. `hugo --minify -D` in reground-site, confirm no build errors.
+2. Local dev server: load `/gift/<slug>/`, confirm hero copy/image render and the form
+   points at the right `eec_slug`.
+3. Confirm the uploaded PDF URL returns `200`.
+4. Once eec-courses changes are deployed, do one real signup end-to-end and confirm the
+   delivery email, its PDF link, and its redirect all point at this partner's content.