recap/docs/daily-digest-plan.md

Daily Digest — plan

Status: proposed (awaiting go-ahead). Captures the design agreed with Grant on 2026-06-15. Build only after sign-off.

Goal

An opt-in (off by default) daily "wake-up" email to recaps.cc users: the recaps added to their library in the last ~24 hours, each shown as a synthesized 1–2 paragraph overview generated from that recap's existing per-topic summaries. Turns passive subscriptions into a daily touchpoint without making the user open the app.

Decisions (locked 2026-06-15)

• Content — "overnight recaps": library additions since the user's last digest.
• Audience / opt-in — multi-mode (recaps.cc) first; off by default; per-user toggle.
• Per-episode depth — a 1–2 paragraph overview synthesized from the stored topic summaries (chunks). NOT raw full text (too long, Gmail clips >~102 KB), NOT a one-sentence blurb (too thin). This is Grant's call and it's what bounds email size.
• Volume — per-episode size is bounded by the 2-paragraph synthesis. Still cap at ~10 episodes per email with an "and N more in your library →" overflow link for extreme days.
• Cadence — once per user per ~24h at a fixed server-time hour (default 08:00). Timezone-aware send is a v2. Skip the email entirely when nothing is new.
• Dedup — a per-user last_digest_at watermark; each digest covers recaps created since that instant, so nothing repeats and nothing is missed.

Data (grounded in code)

• Saved recap record (server/history.js saveToHistory): id, title, type, url, createdAt (ISO), topicCount, chunks (topics, each with bullet summaries), entries (transcript), speakers/speakerNames. No top-level summary is stored → the 1–2 paragraph overview must be synthesized.
• Multi-mode users live in the users table (id, email, …); a user's library scope is their user id.

Architecture

Mirror server/subscription-reminders.js (the proven daily-scan-plus-email pattern: self-gating, deduped, never throws).

• server/daily-digest.js (new)
  • runDigestScan({ force }): gate on isSmtpReady() + public URL set. For each opted-in user, list sessions with createdAt > last_digest_at; if none, skip. For each new recap, get-or-generate its overview (see below), render the email, sendMail, then advance the watermark. Returns a {sent, skipped} summary; never throws.
  • startDigestScheduler(): boot delay + interval, fires near the target hour. Idempotent; safe to start unconditionally in multi mode.
• Synthesis — synthesizeEpisodeOverview(record): send the recap's topic titles + bullet summaries to the relay LLM with a "write a 1–2 paragraph overview" prompt. Cache the result back onto the session JSON (e.g. digestOverview) so it's generated once and could later power an in-app episode overview. Sanitize operator-internal strings at this boundary (Parakeet/CUDA/LAN IPs etc. must not reach cloud users — existing repo convention).
• Email — renderDigestEmail({ brandName, episodes, manageUrl, unsubscribeUrl }) in server/email-template.js, matching the existing reminder/magic-link templates.
• Opt-in storage — migration in server/db.js: add users.digest_enabled (default 0) and users.last_digest_at (ms, nullable). Toggle endpoint in server/account-routes.js (requires session). Settings-modal toggle in public/index.html.
• Unsubscribe — a one-click tokenized GET link in every email that flips digest_enabled = 0 without requiring login (signed token), plus the in-app toggle. Consent + deliverability hygiene on the young recaps.cc domain.
• Operator test trigger — POST /api/admin/digest/run { test_email }, mirroring the reminders test hook, so it can be smoke-tested without waiting a day.

Cost / credits

The synthesis is one small relay LLM call per new recap per opted-in user, run once and cached. Bounded by (opted-in users × new recaps/day). Recommend operator-absorbed (it's a retention feature, input is already-short topic summaries) rather than drawing the user's credits. Confirm.

Open questions (defaults chosen; confirm or adjust)

1. Synthesis cost owner — operator-absorbed (default) vs user credits?
2. Send hour — 08:00 server time (default)?
3. Single-mode operator digest — defer to a follow-on (default: multi-mode only v1)?
4. Relay contract — does an existing relay endpoint (/relay/analyze) fit the "summarize these topic summaries into 2 paragraphs" call, or is a small new relay capability/prompt-mode needed? If new, update ../recap-relay + both repos' AGENTS.md/ROADMAP.md per the cross-repo rule. Resolve before phase 2.

Build phases

1. Schema + opt-in toggle (migration, account endpoint, settings UI).
2. Synthesis + cache (relay call + write-back + operator-string scrub). Resolve the relay-contract question first.
3. Email template + scan loop + scheduler + watermark dedup + overflow cap.
4. Operator test trigger.
5. Tests — pure-function coverage (episode selection vs watermark, cap/overflow, empty → skip), in the subscription-reminders test style.