AI Update

A twice-weekly AI news newsletter, generated by Claude, delivered by Gmail,
archived on GitHub Pages. Runs automatically every Sunday and Wednesday
at 13:00 UTC via GitHub Actions.

The editorial brief: synthesize trends and themes (not article lists),
always link out for going deeper, and never miss big new techniques, tools,
workflows, or mental models.

How it works

fetch (RSS / Reddit / GitHub Trending / RSSHub)
  → dedupe against data/seen.json
  → synthesize one edition with Claude Opus 4.8
  → publish docs/editions/<date>.html + update docs/index.html + docs/feed.xml
  → email via Gmail SMTP
  → commit docs/ + data/ back to main

• Sources live in sources.yaml (what gets fetched) and
  SOURCES.md (the editorial manifest with rationale).
• Cost guard: the run counts tokens before calling the API and aborts if
  the worst-case estimate exceeds $7 (MAX_RUN_COST_USD in
  config.py). A typical run costs ~$1–2.
• Flaky sources (RSSHub/Twitter especially) are best-effort — failures are
  logged and skipped, never fatal.
• RSS feed: docs/feed.xml carries the last 20 editions
  (full content) and is linked from the site header. It’s regenerated on
  every run and requires SITE_BASE_URL to be set (already the case in CI);
  it’s skipped in local runs without that env var.

One-time setup

1. Repo secrets

In GitHub → Settings → Secrets and variables → Actions, add:

Secret	Value
ANTHROPIC_API_KEY	Your Anthropic API key
GMAIL_ADDRESS	The Gmail account that sends the email
GMAIL_APP_PASSWORD	A Gmail app password (see below)
RECIPIENT_EMAIL	Where to deliver (can be the same Gmail address)

Gmail app password: requires 2-Step Verification on the Google account.
Go to https://myaccount.google.com/apppasswords, create one named
“ai-update”, and paste the 16-character password into the secret. Regular
account passwords do not work with SMTP.

2. GitHub Pages

GitHub → Settings → Pages → Source: Deploy from a branch, branch
main, folder /docs. The site will be at
https://<user>.github.io/ai-update/.

3. First run

Trigger manually: Actions → Newsletter → Run workflow (optionally with
“publish only, skip the email” checked for a test run).

Running locally

pip install -r requirements.txt
export ANTHROPIC_API_KEY=...
export GMAIL_ADDRESS=... GMAIL_APP_PASSWORD=... RECIPIENT_EMAIL=...

python -m newsletter.main --dry-run    # fetch + dedupe only, no API call
python -m newsletter.main --no-email   # full run, publish but don't email
python -m newsletter.main              # the real thing

Tuning

• Schedule: edit the cron in
  .github/workflows/newsletter.yml
  (0 13 * * 0,3 = Sun/Wed 13:00 UTC).
• Cost/size: MAX_TOTAL_ITEMS, MAX_SUMMARY_CHARS, MAX_RUN_COST_USD
  in config.py.
• Voice & structure: the system prompt in
  synthesize.py.
• Look: docs/style.css.