docs(fumadocs): document NOTRA_API_KEY turbo passthrough and empty-blog troubleshooting

[tembo]

Summary

Follow-up documentation for the Notra-powered blog build pipeline, triggered by the merge of #116. That PR fixed a production incident — the live blog rendered empty because turbo's strict env mode stripped NOTRA_API_KEY from the fumadocs build (the Vercel env var never reached scripts/fetch-notra-posts.ts). The fix lived only in turbo.json; the operational knowledge behind it was undocumented, so this captures it where developers already look.

All changes are to the existing apps/fumadocs/README.md "Blog content (Notra)" section — no new pages — and every statement is verified against source.

Docs added/updated

• apps/fumadocs/README.md
  • Expanded the Environment bullet: production now states that setting the Vercel env var is not sufficient on its own — the var must also be listed in passThroughEnv in apps/fumadocs/turbo.json, because turbo's strict env mode strips undeclared variables. Also noted that Bun auto-loads .env.local locally (which is why local builds masked the bug).
  • Added a Troubleshooting: the deployed blog is empty runbook: how to spot the [notra] NOTRA_API_KEY is not set log line, the two-point checklist (Vercel env var + passThroughEnv), and the success log to confirm a good build.
  • Corrected an existing inaccuracy: the refresh workflow was described as "weekly", but blog-schedule.yml's cron (30 13 * * *, its own comment: "Daily safety net") runs daily.

Codepaths covered

• apps/fumadocs/turbo.json — passThroughEnv: ["NOTRA_API_KEY"] (added in fix(docs): pass NOTRA_API_KEY through turbo so the blog builds with posts #116)
• apps/fumadocs/scripts/fetch-notra-posts.ts — the skip-and-keep-snapshot behavior and the exact warning/success log lines
• apps/fumadocs/package.json — build runs the fetch before vite build
• .github/workflows/blog-schedule.yml — the daily rebuild cron

Key knowledge gaps addressed

• Why a correctly-set Vercel env var still produced an empty blog — the turbo strict-env / passThroughEnv requirement, previously implicit and the root cause of the fix(docs): pass NOTRA_API_KEY through turbo so the blog builds with posts #116 incident.
• Why local builds worked but production didn't — Bun's .env.local loading bypasses turbo's env filtering, so the gap only surfaces in CI/Vercel.
• A concrete recovery runbook for the empty-blog symptom, keyed off the actual log lines emitted by the fetch script.

Documentation-only change; no SDK/CLI behavior touched, so no changeset.

---

Triggered by the merge of #116 (fix(docs): pass NOTRA_API_KEY through turbo to the docs build).

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

[tembo]

Requesting review from @leoisadev1 who has experience with the following files modified in this PR:

• apps/fumadocs/README.md

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	Jun 28, 2026 2:54am