ConferenceHype

ConferenceHype is a source-attributed medical-conference broadcast system. It collects selected conference, journal, clinical-news, and social material, builds an operator-controlled presentation, renders the program, publishes it to YouTube, and exposes the same broadcast on conferencehype.com.

Built with Codex and GPT-5.6

ConferenceHype was substantially extended during OpenAI Build Week 2026 with Codex and GPT-5.6 acting as an engineering collaborator. Codex inspected the existing application, traced failures across the codebase, GitHub Actions, Supabase, Vercel, YouTube, Kokoro, and FFmpeg, implemented focused repairs, added regression checks, and helped run shadow and production workflows.

The product and editorial decisions remained human-directed, including PubMed-first sourcing, human approval before broadcast, low-cost operation, complete-video delivery, and the rule that incomplete medical cards must never air. Local installation and the judge testing path are documented under Verification below.

Production Flow

1. The operator selects conferences, journals, news sources, priorities, exclusions, custom coverage, and approved presentation slots.

2. Scheduled ingestion and generation create source-attributed review cards.

3. The operator edits, orders, approves, rejects, or atomically replaces cards.

4. In Daily coverage decisions, Create one-hour batch cards drafts and schedules cards into the presentation sequence for the selected hour only — it does not provision a broadcast. As soon as scheduling succeeds, the admin view jumps to Presentation sequence so the operator can see the approved scheduled cards immediately. This reuses unused weekly ready cards first, before generating anything new — reuse priority is: this week's real, source-backed cards first, then this week's "no new articles" announcement card, then any leftover card from a past week last (a stale past-week announcement must never outrank this week's real content just because it was created earlier).

   This endpoint is not idempotent per hour: calling it again for an hour that already has scheduled cards re-picks all 20 slots from scratch and will collide with what's already there (multiple cards landing on the same slot time). To move a batch to a different hour, first revert its existing segments back to pending_review (clear approved_at) before creating the new hour's batch — see POST /api/admin/coverage-slots/create-broadcast below for the matching slot-side cleanup.

5. Once the presentation sequence looks right, Create broadcast (POST /api/admin/coverage-slots/create-broadcast) provisions the approved conference_coverage_slots row for that hour. This is a deliberately separate, explicit step from card creation, so an operator can review the queued cards before committing to actually building and airing the hour.

6. The production cron (.github/workflows/youtube-stream.yml, every 15 minutes, with a 30-minutes-back/90-minutes-forward lookback window) discovers any approved slot with youtube_status: not_scheduled and runs the full render/upload pipeline automatically — nothing further needs to be clicked. Alternatively, Start selected hour dispatches the same YouTube workflow immediately instead of waiting for the cron to discover it; the plan/preview buttons never start or confirm a broadcast on their own.

7. Migrated 2026-07-16 from a live RTMP broadcast to render-then-upload; changed 2026-07-17 to publish immediately instead of a scheduled release. There is no live broadcast object, no RTMP connection, and no "wait for the scheduled hour" step — scripts/render-hour-broadcast.ts renders the file, then uploads it directly to YouTube (lib/youtube/uploadBroadcastVideo.ts) with privacyStatus: "public" from the start. An earlier version of this migration uploaded as private with publishAt set to the slot's scheduled airtime, letting YouTube's own scheduler flip it public later — that added real complexity (a wall-clock "is this the currently airing one" derivation, a stream_state singleton picking the wrong queued video when multiple slots were queued ahead of their airtime, confirmed live 2026-07-17 with two journal slots queued in advance for the same night) for a benefit that didn't hold up in practice: render+upload already finishes close to the intended air time in the common cron-triggered case, so "public immediately" and "public at the scheduled time" rarely differed. Title/description/tags are resolved from the real, final rendered cards (via buildBroadcastMetadata) and set once, at upload time — there's no longer an earlier placeholder to correct afterward.

8. Supabase stream_state and the slot's row receive the resulting YouTube video ID/URL and youtube_status: "queued" once the upload succeeds — this is the terminal success status now (nothing writes "live" or "completed" to the database going forward).

9. The public site still derives whether a queued video should currently be featured as "live" or already "completed" from wall-clock time against the card schedule baked into the writeout at render time (deriveDisplayYoutubeStatus in lib/data.ts) — this now decides which already-public video to spotlight as current, not whether it's technically live, but the viewer-facing effect is the same: "Live now on YouTube" shows during the scheduled air window. Since stream_state is a singleton that only remembers whichever slot's status was written last, getPublicBroadcastContext() also checks both conference_coverage_slots and journal_broadcast_slots directly for a queued slot whose own window actually contains "now", and prefers that over the singleton pointer — otherwise a slot queued (and already public) well ahead of its scheduled window could get silently skipped once a later-queued slot overwrites stream_state first.

10. scripts/verify-public-broadcast-alignment.ts and scripts/verify-youtube-delivery-loop.ts confirm the rendered video, the uploaded YouTube video's status (including privacyStatus: "public"), Supabase's public stream state, and conferencehype.com all agree on the same video ID after upload.

11. Once the upload succeeds, every real (database-backed) segment used in that hour transitions status: "approved" -> "rendered" (markSegmentsRenderedInDb, called from render-hour-broadcast.ts right after a successful upload — deliberately not called if the upload fails, so a failed attempt's segments stay "approved" and are eligible for a retry instead of being silently consumed). getNextBroadcastSegmentsFromDb only ever selects status = "approved", so this is what keeps an already-aired segment from being picked again for a future hour. Because of this, the approved pool only shrinks as hours air — it does not refill itself. Card creation/approval must keep pace with how much airs, or later hours will have thinner presentation sequences and less material available for bonus-card gap filling (see "Broadcast Presentation" below). Watch the approved-segment count if broadcasts feel sparse.

YouTube OAuth is required for delivery now — there is no RTMP-key fallback (uploading a file has no raw-stream-key equivalent). "Continuous mode" (the always-be-streaming fallback loop) was built entirely around the retired live RTMP layer and is not currently functional under render-then-upload; treat the "Allow continuous mode" admin toggle as dormant until that's redesigned or removed.

GitHub main is the source of truth for final code. Any completed fix must be committed and pushed to GitHub before it is treated as final, runnable, or ready for production scheduling. Local-only workspace changes are not final code.

Weekday journal station scheduling

The production weekday station releases exactly one new journal video each Monday through Friday, at 7:15 AM America/New_York. Each program must contain at least 12 substantive, source-backed cards, and cards already reserved earlier in the same week cannot be reused.

Journal selection remains quality-first. The scheduler tries the preferred journal cadence and fallback list before other enabled journals. If those pools cannot supply one complete program, it may use an enabled journal that was previously sidelined from the preferred cadence. Disabled journals remain excluded. Publication freshness expands only as needed, in this order: 14, 21, 28, then 35 days. The 12-card floor is never lowered to fill a slot.

For the week of August 10, 2026, the station reserved 10 programs containing 120 unique cards with zero reuse. Friday, August 14 uses Advances in Radiation Oncology at 7:15 AM and Annals of Surgery at 5:10 PM, with 12 cards in each program. The fallback implementation was verified with npm run typecheck, npm run test:guards, and git diff --check, and landed in commit 1d137bf.

Every journal-video title begins with the journal name, followed by a specific clinical topic and a readable specialty research hook. Viewer-facing metadata must never use Multiple Cancers, and registry-only identifiers such as NCT, ISRCTN, or ACTRN numbers are excluded from titles, descriptions, hashtags, and tags. Descriptions begin with <Specialty> Journal Club, followed by explicit Journal: and Relevant specialties: lines. Source-verified named studies may appear in the description, but they do not displace the journal from the title.

Every journal description also includes an Audience: line. It names the specific specialists first—for example Gastroenterologists, Oncologists, Hematologists, Cardiologists, or Psychiatrists—then adds the general discovery terms Physicians and Advanced Practice Providers (APPs). These audiences also appear in YouTube tags, while titles remain focused on the journal and clinical topic rather than being crowded with generic keywords. Audience resolution uses both the journal's catalog specialty and the clinical topic: for example, a JAMA lung-cancer broadcast targets both Internists and Oncologists, and a Blood leukemia broadcast targets both Hematologists and Oncologists.

Public Site

• Status-aware YouTube player with direct YouTube, audio, and HLS fallbacks
• Live topic text only while the delivery state is actually live
• The public player, current topic, and visible rundown cards must always align. When a YouTube handoff has a saved broadcast_writeouts record, the public site uses that exact writeout as the source of truth for all visible cards. Do not show next approved/admin queue cards beside a different rendered video.
• The ConferenceHype first-viewport wordmark must never be hidden by, overlapped by, or visually crowded under the video/player box. Keep the homepage hero stacked until the text and player have enough horizontal room, and reserve a protected text column in two-column layouts.
• Broadcast audio reads only the material that is actually in the approved cards. Internal workflow procedure, source-checking instructions, missing-source explanations, and operator notes must never be narrated. If copy is not intended for the viewer-facing card, it is not broadcast material.
• Preparing, completed rehearsal, failed, and idle states without stale claims
• Current YouTube handoff read from Supabase on each request
• #ConferenceHype and @conferencehype audience routing
• Emergency override display
• Vercel Web Analytics and Speed Insights

The player prefers the Supabase video ID, then NEXT_PUBLIC_YOUTUBE_VIDEO_ID, then the channel live page. The iframe is shown only when YOUTUBE_EMBED_ENABLED=true.

The YouTube iframe identifies the site with:

• origin=https://conferencehype.com
• widget_referrer=https://conferencehype.com
• referrerPolicy="strict-origin-when-cross-origin"

These values prevent YouTube from treating the iframe as an unidentified embedder.

Broadcast Presentation

Create a Story editorial rule

Create a Story broadcasts (prepared_story) must never show or narrate the words "Physician Education." This rule applies to opening artwork, thumbnails, all subsequent slides, transition panels, narration, and closing copy. Story programs use ConferenceHype branding and the story-specific topic instead.

For the Story opening/title-card format that previously displayed CLINICAL EVIDENCE BRIEF above the story topic, display BREAKING instead. Do not use CLINICAL EVIDENCE BRIEF in that position for this format.

Story update numbering rule

Standing operator rule (2026-10-13): once a conference has already had a video, every later Story on it is titled <Meeting> <Year> Update <N>: <headline>, where N is the number of videos already delivered for that conference. The first video on a conference has no Update label, so the second video is Update 1, the third is Update 2, and so on.

• Where it runs. lib/story/meetingUpdateNumbering.ts, called by POST /api/admin/story/preview and POST /api/admin/story/publish, so the Story desk and the CLI behave the same. The preview returns the final title, the unlabelled baseTitle, and updateNumber; publish stores the labelled title, which is also the YouTube title and the opening title card.
• What is counted. Rows in meeting_watch_broadcasts with status verified or uploaded whose meeting_label or title names the same conference in the same year. Failed, planned, and still-rendering rows are not counted. Only Story broadcasts are renamed; Meeting Watch five-news and 5 Things to Know build their own titles and are not yet covered.
• Which conferences. A registry of known meetings (ESMO, EASD, ASTRO, WCLC, IMS, ESC, ERS, ASCO Quality Care Symposium, ASCO, ACCC, AAP, ACEP, HFSA, DCLung, CHEST, IDWeek, Kidney Week, ACG, AHA, AAO, ACS, ADA, ASH, SABCS, SITC, AASLD, ObesityWeek, CTAD, ACC, ATS, UEG Week, AACR, EHA, EULAR, ACR Convergence, AAN, ECCO, DDW, ENDO) in that file. Add a new meeting on main before its first Story is published. A meeting that is not in the registry gets no label; add it there. Acronym patterns are case-sensitive on purpose.
• Headline length. The label counts toward YouTube's 100-character limit. If the labelled title is too long the request is rejected with the number of characters to cut; nothing is truncated silently. A leading ESMO 2026: in the headline is dropped so the meeting name is not repeated.
• Duplicates. source_hash is computed from the unlabelled title, so re-publishing the same Story is still caught after other videos go out.
• Drafting. Write the headline without the label and quote the labelled title from the preview when asking for headline approval.

Story series connections rule

Operator rule (2026-10-14): when a conference already has earlier videos, the new video must connect back to them to raise retention across the series.

• In the narration (required). When the update number is 1 or higher, the narrative carries a short series bridge near the top, after the thesis and before the first deep item: one to three spoken sentences that name the most recent earlier update by its subject, say what this update adds, and point to the description for the full list. Example: "This is our tenth update from ESMO 2026. Our last one covered the Moderna and Merck melanoma vaccine and Pfizer's lung ADC; this one turns to the pipelines behind them. Links to the earlier updates are in the description." Name specific earlier videos only from the previousUpdates list returned by the production preview, never from memory.
• In the YouTube description (automatic). The production preview returns previousUpdates (newest first, up to five, delivered videos with a public URL). The publish route stores them as a "Previous updates:" block at the end of the broadcast description, and the render reads that block back into "Previous updates in this series:" with one title and link per line.
• Series playlist (automatic, best effort). Each Story is added to one public playlist per meeting and year, titled " Updates | ConferenceHype" (lib/youtube/meetingPlaylist.ts). The render finds or creates the playlist before the upload so its link is in the description ("Series playlist, all updates in order"), then adds the new video after the upload and also adds any earlier delivered videos that are missing, oldest first. A playlist failure only logs a warning; it never fails or delays the delivery writes. It uses the same OAuth token as the upload (scope youtube). The playlist is created by the first Story rendered for that meeting after this feature shipped, and the meeting's earlier delivered videos are added to it at that time.
• Not covered. YouTube end screens and cards cannot be set through the API, and pinned comments need a different OAuth scope.
• Style. A bridge is a callback, not a recap: do not repeat numbers from the earlier video, and do not use it in place of the subscribe line.
• Wording. The bridge must use a phrase like "our last video" or "the previous update" within the first ~260 words.

Story package pre-flight checklist

Everything below is a standing operator rule. Check a Story against the whole list before it is shown for headline approval or published; each item has a history in the project memory notes.

• Production is the authority. Run the draft through the live read-only POST /api/admin/story/preview first. A local dry run uses the local branch's code, which differs from main (the local branch adds a location field and a "has started" opener that production does not have). Production strips unknown fields and prepends nothing.
• Opener. The standing rule is a clean opening line of the form "The [meeting] at [location] has started / will start, [dates]." Production does not add it, so write it as the first sentence of the narrative, using "will start" for a meeting that has not begun. If the automatic opener is ever deployed to production, drop this manual step so it is not spoken twice.
• Length and shape. At least 500 spoken words; 12 cards; continuous flowing prose with no labeled subheadings, bullets, or markdown (labels are reserved for 5 Things to Know).
• Like-and-subscribe line. One sentence about 45 seconds in (inside the first 100 to 150 words): "If you want more of this kind of coverage, take a second right now to like this video and subscribe to the channel." Then continue. The older subscribe-only sentence is retired (operator rule 2026-10-22); replace it wherever it appears in a Grok package.
• Series bridge. For any update after a meeting's first video, see the series connections rule above.
• Closing disclaimer. The last sentence is the fixed AI-generation line. Never use the word "verify" in it or anywhere in a narrative: the broadcast-ready filter silently drops cards containing verify, unverified buzz, air/aired/airing/airtime, snack, coffee, hallway energy, rising energy, audience tip, pending review, or "we verify".
• Title and headline. YouTube title at most 100 characters, including the automatic <Meeting> <Year> Update <N>: label for a conference that already has videos (see the update numbering rule above); thumbnail headline 8 to 58 characters; SEO-oriented; always name the company and the drug explicitly, never a pronoun; the operator approves only the headline.
• Facts. Every claim checked against an official source (company release, registry, program page, peer-reviewed publication); no predictions about adoption, policy, or future trials; say plainly when a number comes from trade coverage rather than the sponsor.
• Source URL. One primary source, written in full with https://, as plain text.
• Spoken form. Write times as "9:45 in the morning" (never a.m., which the card splitter breaks into "a. m."). Do not use ALL-CAPS words, since the voice spells them out. Keep company names in their normal spelling; the pronunciation layer handles them. No "Dr." before names and no initials (the citation filter drops cards that name a "Dr. X" not in the citation); use the full name, or the bare surname after first mention.

Story narrative craft rule

Operator feedback (2026-10-13): the ACG, CHEST, and ESMO updates read as a schedule, not a story, and were weaker than earlier Stories. Measured against 64 earlier Stories, they carried clock times and session slots in 12 to 32 percent of sentences (earlier median 0), roughly twice the number density, five to ten times the attribution hedges, and no "why it matters" sentences. The format below is the standing fix.

• Lead with a thesis. The first sentences state what the meeting's data actually show, not its dates. A preview leads with the one or two questions the data will answer.
• Go deep on three or four items, not eight. Each item runs: result (with the numbers), what it means, and the one caveat that matters. Everything else belongs in the YouTube description.
• Include results that are already reported. For every trial or drug in the story, add its published or topline results (effect sizes, endpoints, safety signals), even when the new presentation is a follow-up or a preview, and say which results are earlier readouts.
• Interpretation is required; prediction is banned. Explain what a result means, how strong the evidence is (randomized versus open-label, small versus large, published versus conference-only), and why a comparator or endpoint matters. Do not forecast adoption, approval, or future trial outcomes.
• Hedge once per item. Attribute and caveat each result once, in plain language, instead of qualifying every clause.
• Keep logistics out of the narration. At most the date of the one presentation that matters. No rooms, session slots, or time zones.
• Close with a synthesis. One short paragraph ranking the evidence (which results are firm, which are preliminary) before the disclaimer.
• Read it aloud. Expand abbreviations, keep sentences speakable, and re-read the draft once before asking for headline approval.

5 Things to Know editorial rule

5 Things to Know is a separate manual editorial lane for completed Claude or Grok write-ups. An operator selects one configured specialty and supplies exactly five numbered items in order, each with its own distinct primary-source URL. The server rejects missing, duplicated, undersized, or unsourced items before dispatching any render.

Packaging is search-focused only. The YouTube title begins <Specialty>: 5 Things to Know Today and may append the first searchable item topics while remaining inside YouTube's 100-character limit. There are no curiosity-title alternatives and no thumbnail experiments. One fixed thumbnail and its matching burned-in opening frame show the specialty in uppercase in the orange box, then 5 THINGS TO KNOW, then up to three supplied item topics.

The format reuses the prepared Meeting Watch persistence, narration, rendering, upload, and public-oEmbed verification pathway, but every segment is isolated by the prepared_five_things flag. It must not inherit prepared_story or journal30 visual and metadata rules. Viewer descriptions begin with the specialty, list five timestamped chapters, and include all five primary-source URLs plus the specialty-specific audience line.

Persistent evidence dashboard

Every newly rendered broadcast uses the shared evidence-dashboard slide renderer. The center of the video must never be an empty color field:

• content cards show the source-verified title, Key Finding, Study Snapshot, Why It Matters, source attribution, and program progress;
• explicit Background, Methods, Results, and Discussion text is reused when present; otherwise the dashboard falls back to concise text already stored in the approved card and never invents missing study details;
• music cards show a branded Coming Next panel using the next approved card; its body text is always a like/subscribe + "suggest a journal in the comments" call to action (lib/broadcast/evidenceDashboard.ts), never inert filler like "A brief music transition..." — fixed 2026-07-30, that filler used to show on every transition slide except the final closing one;
• slide titles (including the Coming Next panel's next-title) must never be silently cut off. Two distinct bugs were fixed 2026-07-30 after a live broadcast showed a Coming Next slide reading just "End of" with nothing after it: (1) stripSlideDescriptors()'s "strip a leading label prefix" regexes (TumorCrusher / Media Watch EMERALD-3 trial -> EMERALD-3 trial) were unanchored, so they deleted the same phrase anywhere it appeared — the outro card titled "End of journal coverage" (lib/rundown/slots.ts) lost "journal coverage" to the "Journal Coverage" label pattern; fixed by anchoring every pattern to the start of the string (^), both in evidenceDashboard.ts and the identical stripPreparedDescriptors() in lib/meetingWatch/preparedNarrative.ts, which had the same unanchored bug applied to spoken narration text. (2) wrap()'s line-wrapping loop could drop the final overflow word with no ellipsis when it landed exactly on a line-count boundary, and truncate()'s ellipsis character was mojibake (… instead of …) and could cut mid-word; rewritten so a truncated title always ends in a real …, cut at a word boundary when reasonably close to the limit.
• the persistent series header, footer, and narration-driven waveform remain overlays and do not alter card timing, narration, music placement, upload, scheduling, or activation;
• if structured sections are unavailable, a populated branded evidence-summary card is still rendered. A blank center screen is not an allowed fallback.

This contract is implemented once in scripts/render-hour-broadcast.ts, so it applies to presentation, weekday station, single-journal, weekend roundup, Meeting Watch/prepared narrative, and breaking-news broadcasts going forward.

• Created/ready cards are not automatically in the selected hour. A card only belongs to the broadcast presentation sequence after it is accepted and scheduled for that hour, dragged into a content slot, or used as a replacement. Admin card lists must show this distinction: ready cards are candidates, while scheduled slot cards are marked as approved in the presentation sequence.
• Daily card creation is selection-only. The admin selects the date and time, then checks the desired journals, meetings, abstracts, or media sources. No journal, meeting, RSS feed, or clinical-news source may be default selected. The batch algorithm must create cards only from those checked selections, using source IDs rather than loose title/source-name matching. Brand New Ready Cards remain candidates until the admin accepts, rejects, or replaces them into the presentation sequence.
• When a conference, meeting, journal RSS feed, clinical news source, or newspaper source is selected, both Presentation sequence and Brand New Ready Cards must show that selected source set only. Old ASCO cards, platform-smoke cards, and unrelated prior scheduled cards must stay hidden until the operator clears or changes the source selection.
• Daily guard verification must fail if an unselected journal/meeting/media item can generate a card or if a legacy untagged batch card can enter the presentation sequence.
• Viewer-facing transition cards are clean ConferenceHype cards. Internal labels such as "music card", "gap clip", or workflow instructions are not shown.
• Do not use internal generic source labels in prepared copy. Attribute the journal, meeting, media, or social source naturally instead.
• Cards placed into slots must visibly belong to one of six operator-facing types: Journal coverage, Abstracts, Conference Coverage, Media watch, Pharma watch, or Diagnostic Company watch.
• If any card contains missing-intake failure language instead of source detail, replace the entire card with the stored music transition. Do not voice or display that card as content. If a social-voices card or any other card is empty, play only music for that slot.
• Journal-review cards begin their substantive content with: "From the [Month] edition of [Journal Name]". They should condense the abstract, methods, results, and discussion into broadcast language rather than merely reading the article headline.
• Article, abstract, journal, and clinical-news cards must be PubMed-first when a PubMed record can be found. Use the complete PubMed abstract to write specific Background, Methods, Results, and Discussion content. Do not build article cards from RSS issue metadata alone.
• PubMed title matching must be exact (after stripping the RSS feed's leading category tag, e.g. [Articles], [Review], [Comment]). Never accept a "best guess"/top-relevance result as a fallback when no exact title match is found — that has previously misattributed an unrelated article's abstract to the wrong journal. No match means no PubMed enrichment for that item, not a guess. NCBI E-utils calls must stay throttled to roughly 3 requests/second with a retry on ; a rate-limited response is not the same as "no record found" and must not be treated as one.

Keep purchase and license evidence for third-party tracks outside the repository. See public/music/README.md.

Admin

Broadcast

• Configure daily sources, priorities, exclusions, and breaking-news behavior.
• Edit and order the one-hour presentation sequence.
• Drag review cards into exact content slots.
• Preview and place any of the 20 three-minute Funk/Latin music cards into a selected presentation slot.
• Approve, reject, discard, or atomically replace cards.
• The top navigation includes a dedicated Pending Review tab showing the complete quality-passing journal-card queue. Operators can review or edit individual cards, approve or reject them one at a time, or use the confirmed Approve all action. Large queues are submitted sequentially in 1,000-card request batches, below the API's 2,000-ID safety limit, and the UI aggregates the results. Every batch still runs server-side deduplication and the normal quality validator; duplicates and cards that fail source or structure checks are skipped rather than force-approved.
• Manage source URLs, X follows, social items, and emergency overrides.
• Approve conference coverage by slot, day, or week.
• Two explicit, always-visible buttons control continuous YouTube delivery (components/StartStreamButton.tsx, redesigned 2026-07-08 from a single state-toggling button): "Stop continuous / scheduled only" and "Allow continuous mode." Scheduled-only (continuous off) is the default/expected mode; continuous is a deliberate opt-in an operator chooses, not something a single ambiguous toggle should make easy to leave on by accident. Whichever action matches the current state is disabled so it can't be clicked redundantly. Both call the same /api/admin/start-stream route with action: "start" or "stop" — no backend change, just two explicit entry points instead of one.
• Inspect YouTube status, video links, workflow links, and delivery errors.
• The "Weekly ready-card pool" panel (components/DailyCoveragePlanner.tsx) is deduplicated by content signature and sorted/grouped alphabetically by journal name, with a visible journal-name badge per card. Fixed 2026-07-18: the weekly batch and the one-hour batch can each independently generate their own segment row for the same underlying article (same citation url, different ids) — one real article had 44 duplicate rows, which rendered as repeated identical tiles before this fix. The per-journal/conference deck view (lib/cardDeck.ts's buildDeck) gets the same content-signature dedup.
• Release all ready cards sends the visible segment IDs as a JSON request and handles an empty HTTP response with an operator-readable error. This prevents the former Unexpected end of JSON input failure while retaining the server-side approval quality gates.
• getAdminSnapshot () runs its ~20 independent Supabase calls via instead of one after another, and the "one-hour planning slots" picker only spans 24h back through 48h forward (not a full week) — fixed 2026-07-18 after navigation (which is and reruns this on every request) was reported very slow.

Journal Watch

• Manage official RSS or Atom feeds.
• Develop the latest issue into an editorial package.
• Generate at most one unseen issue package per run to control LLM cost.

Current seeded feeds:

• The Lancet Oncology
• The Lancet Haematology
• The New England Journal of Medicine
• JAMA
• Nature Medicine
• Nature Cancer
• British Journal of Cancer
• Leukemia
• Blood Cancer Journal
• Annals of Oncology
• The Lancet

Run npm run test:rss to make a live request to every seeded feed. Psychiatry coverage includes JAMA Psychiatry, American Journal of Psychiatry, The British Journal of Psychiatry, Molecular Psychiatry, World Psychiatry, Psychiatric Services, and Journal of Child Psychology and Psychiatry. Publisher feeds are used when they are dependable; American Journal of Psychiatry, The British Journal of Psychiatry, and Psychiatric Services use exact PubMed [Journal] queries because their publisher feed endpoints reject automated requests. JAMA Psychiatry must remain labeled Psychiatry, while Journal of Neurology, Neurosurgery & Psychiatry must remain labeled Neurology.

Psychiatry cards follow the same source and approval rules as every journal: start at PubMed, require substantive abstract-grounded Background, Methods, Results, and Discussion coverage, keep generated cards in pending review, and never auto-approve a title-only, missing-abstract, or otherwise source-limited card. Weekly availability is not proof of complete intake; feed-level sync, article, reconciliation, and card-state counts must be audited before claiming that no psychiatry journals or articles were missed.

Meeting Watch

Free Korean, Japanese, and Simplified Chinese IASLC editions

The manual IASLC localized editions workflow republishes the two verified IASLC/WCLC Meeting Watch broadcasts as six separate language editions: Korean, Japanese, and Simplified Chinese narration plus synchronized burned-in subtitles over the source episode's branded thumbnail. It also attaches a selectable YouTube caption track when the channel OAuth token includes caption-management scope. It uses the local open NLLB-200 multilingual translation model and native Korean, Japanese, and Mandarin voices through the no-key Edge speech endpoint. No paid translation or speech API is required. Target-script, output-length, repetition, medical-term, and numeric-fact guards reject malformed translations before upload.

Each run retrieves only the verified, approved source scripts from Supabase, preserves drug/trial names and numeric facts, uses the Meeting Watch 16-second speech-free transitions, uploads privately, verifies the localized narration and burned-in subtitles, and only then makes the edition public. When authorized, it also attaches the matching selectable caption track. A title-based preflight prevents duplicate uploads on retries. Delivery evidence is retained as a GitHub Actions artifact for 30 days.

The workflow defaults to generation-only (publish: false). Review the JSON/SRT evidence for coherent medical translation before rerunning the selected language with publish: true; this explicit review gate prevents a structurally valid but semantically malformed machine translation from reaching YouTube.

Run it from GitHub Actions with language=all for all six editions, or choose one language. The two source broadcast UUIDs are pinned in .github/workflows/iaslc-localized-editions.yml so “last two” cannot drift while a release is running.

• Meeting Watch is a conference-first format. New complete-narrative episodes contain 5-10 distinct, source-attributed meeting news items or abstracts; legacy five-news packages retain exactly five. The YouTube caption starts <Meeting name> <year> | <SPECIALIST ALERT>: <eye-catching topic>.

• Thumbnails and every recurring in-video frame repeat the meeting name and year plus the specialty-specific alert. Meeting Watch must never display or narrate CLINICAL EVIDENCE BRIEF, NEW EVIDENCE, THE STORY BEHIND THE RESULT, or WHY THIS RESULT MATTERS.

• New Claude or Grok packages use schema conferencehype_meeting_watch_full_narrative_v3. The model supplies the exact beginning-to-end spoken text: a focused 30-120-word hook that identifies the meeting and its year or dates, names at least two source-supported pharma companies, and previews the subjects; 5-10 ordered, distinct abstracts with 30-65 exact spoken words and a supporting primary-source URL; a 15-35-word disclaimer; and a 20-50-word closing. A single primary-source document may support multiple abstracts when each has a distinct abstract number or study name. ConferenceHype preserves that narration order verbatim, inserts 16 seconds of speech-free music between the hook, abstracts, and closing, and rejects packages whose calculated narration plus music exceeds 10 minutes. Claude/Grok must keep objective response rate unbroken and must not write novel-novel or consecutive repetitions of novel. The admin uses one Develop and publish YouTube video action; validation, title/thumbnail normalization, render, upload, and delivery tracking remain server-side. The legacy conferencehype_meeting_watch_five_news_v1 and conferencehype_meeting_watch_story_v2 schemas remain readable for existing packages.

• Pharma company names are included when an official meeting abstract, trial registry, publication, or company primary source explicitly supports the relationship. Never guess sponsorship, ownership, or drug-company attribution merely to improve search performance.

• The Meeting Watch admin extracts the editable YouTube headline directly from meeting.eye_catching_topic as soon as pasted JSON can be parsed, even if unrelated narration validation still needs correction. The operator-edited headline is passed through unchanged at publish time, subject to the 150-character and prohibited-generic-label guards.

• Manage the medical-conference catalog.

• Add exact dates only from official conference sources.

• Choose one-hour coverage slots.

• Approve an individual slot, a day, or the next seven days.

Weekly Source Cards

• At the start of each week, weekly-source-cards.yml pre-generates template-based ready cards (no LLM cost) for every enabled conference, journal, and clinical news/newspaper source. These appear under that entity's checkbox in Broadcast, Journal Watch, and Meeting Watch, with the full spoken script — not just a title — visible in the card deck so the operator can review the actual material before it ever airs.
• The admin page's "Run weekly batch now (free)" button runs all three entity types together, matching the scheduled cron. Three additional buttons — "Run journals batch now", "Run conferences batch now", "Run newspapers batch now" — trigger only one entity type via the workflow's scope input (all / journals / conferences / newspapers), so a much smaller journals-only run (or any single type) doesn't also regenerate cards for the other two. WEEKLY_SOURCE_SCOPE is read by both scripts/generate-weekly-source-cards.ts and scripts/verify-weekly-source-cards.ts, so a scoped run's own verify/repair steps don't fail on entity types it deliberately skipped.
• Click "View deck" under any conference, journal, or source to expand its card list and read each card's entire broadcast script, every time. There is no summary shown here and no truncation — the card list scrolls, not the individual card, so a full ~6-minute script always renders in totality.
• If the operator does not like what is there, click "Don't like these? Generate more cards" under that same entity. This calls POST /api/admin/source-cards/regenerate (entityType + entityId), which re-checks that one entity's official sources/abstracts/RSS for anything not already covered, falls back to an X post search (own account, or whoever is discussing it) if nothing new is found there, and appends any new cards to that entity's deck. It is purely additive — it never deletes or replaces existing ready cards, so re-clicking it is always safe.
• This is scoped to a single entity per click, not a full catalog re-sweep, so it is cheap enough to use repeatedly while reviewing.

Records

• Writeouts: ordered spoken cards, sources, YouTube and workflow links, delivery state, and errors for each render.
• Memory: developed packages waiting for an operator-assigned start time.
• Specialty X Voices: curated and operator-added voices, blacklist controls, and a real-ingestion leaderboard with no fabricated rankings.
• Talked About: every card that has actually aired (status: "rendered"), newest first, with its source attribution and a "Send back for re-presentation" button. Updated 2026-07-09: aired cards used to stay mixed into their journal/conference/source's regular deck (just tagged "Presented") — they're now excluded from that deck entirely (lib/cardDeck.ts's buildDeck) and only live here. "Send back" reuses the existing /api/admin/approve endpoint (action: "approve", no new backend logic) to move a card from rendered back to approved, making it schedulable again. Confirmed buildDeck() is display-only — this doesn't touch card creation, selection, or the render/broadcast pipeline.

Required Services

• Vercel: Next.js site, admin API, analytics, and performance monitoring
• Supabase: editorial data, schedules, writeouts, and delivery state
• GitHub Actions: generation, rendering, embed checks, and publishing
• YouTube Data API OAuth: fresh broadcast creation and embed management
• LLM provider: script generation
• Kokoro: render-time speech
• X API: optional social monitoring

Configuration

Use .env.example as the local template. Never commit secret values.

Vercel Production

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
ADMIN_SHARED_SECRET
GITHUB_DISPATCH_TOKEN
GITHUB_DISPATCH_REPO
YOUTUBE_EMBED_ENABLED=true

Optional public fallbacks:

NEXT_PUBLIC_YOUTUBE_VIDEO_ID
NEXT_PUBLIC_YOUTUBE_CHANNEL_ID
NEXT_PUBLIC_AUDIO_STREAM_URL
NEXT_PUBLIC_HLS_URL

GitHub Actions Secrets

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
LLM_API_KEY
LLM_BASE_URL
LLM_MODEL
YOUTUBE_OAUTH_CLIENT_ID
YOUTUBE_OAUTH_CLIENT_SECRET
YOUTUBE_OAUTH_REFRESH_TOKEN

Optional services and legacy fallback:

X_BEARER_TOKEN
YOUTUBE_RTMP_URL
YOUTUBE_STREAM_KEY
NEXT_PUBLIC_YOUTUBE_VIDEO_ID

Set the GitHub Actions variable YOUTUBE_PRIVACY_STATUS to public for production scheduled broadcasts so saved streams appear on the ConferenceHype YouTube channel. Use unlisted only for rehearsals or private tests.

The ConferenceHype Google OAuth app is published In production. Refresh tokens issued after production authorization are no longer subject to Google's seven-day Testing-mode expiration rule, although they can still be revoked by the account owner or Google security controls. The OAuth client must include https://developers.google.com/oauthplayground as an authorized redirect URI when OAuth Playground is used to obtain that token.

Rotate the OAuth client secret and refresh token immediately if either is exposed in chat, logs, screenshots, or source control.

Renewing the YouTube refresh token

Continuous journal station and manual break-ins

The station planner in the admin Broadcast tab creates a daily three-hour wheel of six 30-minute specialty/journal programs. The wheel repeats across the day. For a journal with new ready cards, the operator renders a new program. If the card count is zero, the planner reuses the latest verified program for that journal (or, secondarily, that specialty). Music already fills unused time inside every 30-minute render. Each new program reserves at most twelve quality-passed cards. This bounds the approval transaction and render input while leaving excess cards in their journal deck for a later program.

The regular Monday-Friday journal wheel releases exactly one new journal video per day at 7:15 AM America/New_York. The weekday-station-wheel.yml prepares the program in advance, uploads it privately, and asks YouTube to publish it at its assigned time. Each YouTube title includes the journal title. Assigned articles must predate the broadcast date and normally be no more than fourteen days old; a bounded twenty-one-day fallback is allowed only when one complete twelve-card deck cannot be assembled from the fourteen-day window. Selection stays within the approved flagship list and never lowers the twelve substantive, source-backed card floor. Activation fails closed until one verified YouTube ID exists. Unused cards remain available, and the separately scheduled weekend roundup also releases one new Journal Club per day.

Morning-journal recovery is deliberately fail-closed. GitHub Actions runner delays must not silently turn a scheduled run into a successful no-op: weekday-station-wheel.yml retains the intended UTC release date, and weekday-station-activate.yml proceeds whenever the delayed run starts at or after its minimum activation hour. Publication dates from PubMed/RSS are normalized to ISO before freshness comparisons, including values such as 2026 Jul 31. The planner skips an assigned flagship journal when fewer than the renderer's twelve substantive source-backed cards are eligible and tries only the approved flagship fallback list; it never lowers the render quality gate. After activation, refresh-station-video-metadata.yml can safely refresh the canonical video's title and high-contrast thumbnail in place, with exact operator overrides, without uploading a duplicate. This recovery policy was verified end to end on 2026-08-05 with one public 14:52 Blood broadcast reused across all six station positions.

This feature is additive and fail-closed:

• The station tables are private service-role tables created by migration 20260722170000_station_schedule_and_breakins.sql.
• A weekday schedule cannot become active until both new uploads verify as two distinct YouTube IDs; otherwise the existing public player remains unchanged.
• The public page selects only an active schedule and a verified current program. If either is absent, it retains the existing working YouTube broadcast without changing stream_state.
• station-program.yml and station-breakin.yml are isolated manual workflows; they do not alter the proven scheduled youtube-stream.yml path.
• A manual breaking-news card is source-labelled, approval-validated, and rendered as a 15-minute program for either the next :00 (top) or next :30 (bottom) boundary. It temporarily takes public-player precedence only during its verified 15-minute window. A failed render leaves the current player untouched.

Twitter / X Stream tab

The admin top navigation includes a dedicated Twitter Stream tab. It builds a zero-cost replay plan from prior station programs that already have verified YouTube video IDs. The operator selects one specialty, a start time, and a one-to-six-hour duration. The planner schedules two journal broadcasts per hour—one at :00 and one at :30—and cycles only through previous broadcasts from that same specialty. It does not render new media or call an AI service.

The tab copies an operator-readable run plan with the journal, title, and replay URL for every half-hour boundary. Actual X delivery remains fail-closed: do not label the stream live until X Media Studio Producer ingest access and a persistent local encoder have passed a private test. An app-only bearer token is not sufficient for posting or creating a live broadcast, and a Vercel request or temporary GitHub runner must not be treated as the persistent encoder.

If the OAuth consent screen is returned to Testing status, Google can expire a YouTube-scope refresh token after seven days. Keep the app In production. The following tools provide renewal detection and recovery without exposing token values:

1. npm run youtube:refresh-token opens your browser for one sign-in/ approval click, exchanges the code for a new refresh token, and pushes it straight to the YOUTUBE_OAUTH_REFRESH_TOKEN GitHub secret via gh secret set — the token value never touches the terminal output or any log. Requires YOUTUBE_OAUTH_CLIENT_ID and YOUTUBE_OAUTH_CLIENT_SECRET in .env.local (see .env.example) and a one-time addition of http://localhost:53682/oauth/callback to the OAuth client's authorized redirect URIs in Google Cloud Console.
2. .github/workflows/youtube-oauth-health-check.yml runs daily and tries a real refresh-token grant against Google. If it fails, it opens (or keeps open) a single "YouTube OAuth token needs renewal" issue instead of waiting for a scheduled broadcast to silently fail; it auto-closes that issue once a check passes again.

Database Migrations

Apply every file in supabase/migrations in filename order. Important current migrations include:

• 20260614005000_public_youtube_delivery.sql: public YouTube handoff and persistent continuous-feed state
• 20260615173849_remove_legacy_conference_content.sql: removes retired conference-specific content from active data
• 20260709120000_journal_specialty.sql: adds oncology_journals.specialty, which groups the "Journal RSS feeds" picker into specialty tabs (see lib/catalog/journalWatchSpecialties.ts). After applying, run npm run backfill:journal-specialty once to stamp the specialty value onto journal rows that already existed in the database (the catalog seed upsert uses ignoreDuplicates: true, so it won't update pre-existing rows).
• 20260713000000_journal_broadcast_slots.sql: adds the journal_broadcast_slots table backing 30-minute single-journal broadcasts (see below). Independent of conference_coverage_slots — no backfill needed.

https://conferencehype.com/api/stream/status is the fastest production check for the current youtubeVideoId, URL, and delivery status.

YouTube Title/Description/Tags/Category Automation

Each hourly broadcast's YouTube title, description, tags, and category are built automatically from that hour's actual, final rendered cards (lib/youtube/broadcastMetadata.ts, wired into scripts/render-hour-broadcast.ts and set once at upload time via lib/youtube/uploadBroadcastVideo.ts) so the broadcast surfaces in search/recommendations for physicians, NPs, and PAs following specific journals or specialties, instead of a generic always-identical title.

• Title: journal name first, followed by a specific clinical topic and a readable specialty research hook when one journal clearly leads the hour (≥2 cards); falls back to a specialty-only "Roundup" framing for a genuinely mixed hour; falls back to today's original generic conference-based title when zero cards have resolvable journal data — a zero-journal-data hour is never worse off than before this feature. Known issue, diagnosed but not yet fixed (2026-07-19): the "≥2 cards" dominant threshold in resolveTier() (lib/youtube/broadcastMetadata.ts) is a flat count, not a share of the hour, so at 90-journal scale a journal with a slim plurality (e.g. 7 of 32 cards) still gets crowned as the whole hour's title/intro even though the rest of the hour is unrelated specialties. Confirmed on a real video (MRDoPUwUVgk, titled "JAMA Psychiatry - Others" while ~78% of its 32 cards were Nature Medicine, PLOS Medicine, JAMA Surgery, JAMA Otolaryngology, JCO Oncology Practice, and JAMA Pediatrics). Per-card chapter attribution in the description is correct; only the title/intro summarization is wrong. Fix direction: require dominant to represent a real proportion of resolved cards (e.g. ≥40%), falling through to the existing roundup tier otherwise.
• Study-name search optimization (effective July 24, 2026): named studies and trials are extracted only when explicitly present in approved card text, citation labels, or the linked PubMed abstract. Registry-only identifiers such as NCT..., ISRCTN..., and ACTRN... are not viewer-facing search terms. Named studies may appear in the description and leading tags, but the journal remains first in the title. Generic phrases such as this study or controlled trial are rejected, and the system never invents a study name. Metadata refresh updates canonical videos in place without uploading duplicates.
• Description invariant: every journal video begins its description with <Specialty> Journal Club, then Journal: ..., Relevant specialties: ..., and an Audience: ... line beginning with Physicians and Medical Students, followed by the specific resolved specialties and Advanced Practice Providers (APPs). The generic phrase Medical Specialists is prohibited. For example, an oncology program begins Oncology Journal Club before Journal: Cancer Discovery. When named studies are detected, a Named studies covered: ... line follows. Journal and source publication month/year remain explicit.
• Station search-metadata gate: every newly rendered weekday journal program must pass one validation package before it can be marked verified. The journal begins the title; the description begins with the specific specialty plus , followed by the journal name; , , and registry-only identifiers are rejected from viewer-facing search metadata. Journal name, specific specialty, and publication month/year are mandatory; generic fallback and thumbnail-upload warnings are not accepted for station programs.

YouTube Custom Thumbnails

Beginning July 24, 2026, new and weekday-refreshed journal videos use a higher-contrast curiosity thumbnail. When a verified explicit study name exists, the headline combines that name with What Did It Find?; otherwise it uses the non-claiming What Did This Research Find?. Thumbnail text comes from the same metadata object as the title, description, and tags, so it cannot independently invent or select a different study.

app/api/youtube-thumbnail/route.tsx renders a 1280×720 thumbnail via next/og's ImageResponse (no new dependency — built into Next.js) with three tiers matching the title's own tiers exactly (dominant journal + specialty, specialty-only roundup, or the generic ConferenceHype wordmark). lib/youtube/uploadBroadcastVideo.ts's uploadYoutubeThumbnail fetches this route using the exact same resolved metadata already computed for the title (never a second independent resolution, so title and thumbnail can't disagree) and uploads it via thumbnails.set right after the video upload succeeds. Wrapped in try/catch — YouTube requires the channel to be phone-verified before custom thumbnails are accepted (see LAUNCH_CHECKLIST.md's YouTube section), which can't be confirmed from code, so an unverified channel just means the thumbnail step silently no-ops with a logged warning; the upload itself and title/description/tags/category are all unaffected either way.

Journal-recognition and CTR thumbnail rule

Beginning with commit 860090c, every 30-minute single-journal broadcast uses the dedicated Journal Club thumbnail hierarchy:

1. A large, high-contrast gold-on-red JOURNAL CLUB badge, paired with the source-resolved specialty and no CONFERENCEHYPE wordmark on this layout.
2. The full plain-text journal name and the source issue month/year.
3. The complete primary article title in smaller adaptive type.

The corresponding YouTube title begins JOURNAL CLUB | <target audience> | before the journal name. The audience is resolved from the journal specialty; for example, Radiology / Radiation Oncology becomes Radiation Oncologists and Radiologists. This ordering is exclusive to single-journal (journal30) videos and is enforced for new uploads and in-place metadata refreshes. Set STATION_METADATA_JOURNAL_CLUB_ONLY=1 with the all-released metadata refresh to update only canonical single-journal videos while leaving weekend and mixed-program metadata untouched.

The article title is passed separately from the short curiosity headline and must wrap to fit without truncation or an ellipsis. The journal name and issue date come from the same source-resolved metadata as the YouTube title and description. Do not use publisher logos or imply journal endorsement.

This dedicated layout applies only to single-journal (journal30) broadcasts. Mixed programs show no more than the two journals with the most covered cards and an accurate + N JOURNALS count for the remainder. Weekend roundups retain that two-name/count rule. Manual breaking-news videos retain BREAKING MEDICAL RESEARCH, and Create a Story / prepared_story retains ConferenceHype plus story-specific branding. When no journal can be source-resolved, the safe fallback is MEDICAL RESEARCH.

CTR is not optimized by misleading copy. When YouTube Studio Test & Compare is used, compare no more than three truthful variants: journal recognition, study-result curiosity, and specialty emphasis. Select based on YouTube watch- time share and first-30-second retention, not raw clicks alone. Automated YouTube APIs do not expose Test & Compare, so experiments remain an operator action in YouTube Studio.

In-video opening title rule

Every newly rendered ConferenceHype video displays its exciting 1280x720 metadata-driven YouTube thumbnail over the first eight seconds of playback. Narration begins normally underneath it: the opening visual does not add time, move a card, change audio synchronization, shorten the true-end outro, or alter the exact 15-, 30-, or 60-minute broadcast frame. The same resolved thumbnail bytes are then uploaded to YouTube, so the promise viewers click and the title they see when playback begins cannot drift apart.

This is enforced once in the shared final-render path and therefore applies to presentation broadcasts, weekday station programs, single-journal broadcasts, weekend roundups, and manual breaking-news broadcasts. Thumbnail rendering is retried before publication; a video is not published without its required opening title visual. Failure of YouTube's separate thumbnails.set operation continues to follow the existing station versus non-station delivery policy and does not change the already-burned in-video opening.

Opening slide disease label rule

Operator rule (2026-10-29): the disease label on the opening slide and thumbnail must describe the video, never a disease that is only mentioned in passing. The ASCO election Story opened as "BREAKING | Breast Cancer" because one candidate's paper was a breast cancer trial and the label picked whichever disease the pattern list in lib/youtube/clinicalEvidencePackaging.ts happened to list first.

resolveClinicalTopic now decides the label for every video type (Story, Meeting Watch, journal shows, weekend roundups, hourly broadcasts, Breaking Paper):

• One disease named anywhere in the text: that disease.
• Several diseases: the disease named in the video's own title, if the title names exactly one.
• Otherwise: the video's own topic (the Story topic or meeting name) or its specialty ("Oncology Research"), never an arbitrary first match.

The trial line under the headline follows the same idea for Story and Meeting Watch videos (resolvePrimaryEntity, entityMustMatchTitle): one named study -> that study; several -> the one the title names, if exactly one; otherwise no trial line. The re-rendered election slide had shown "DeLLphi-301 trial", the first of many papers mentioned. Journal shows still feature their first study.

Guard tests in scripts/verify-broadcast-guards.ts cover the election case, a titled multi-disease review, a multi-disease journal roundup and both trial line cases. When a Story covers several diseases, check the preview's opening label before publishing; a burned-in opening can only be fixed by re-rendering.

YouTube Embed Protection

The main workflow runs scripts/enable-youtube-embed.ts immediately after creating the broadcast. It verifies both:

• the live broadcast has contentDetails.enableEmbed=true
• the underlying video has status.embeddable=true

It then requests the iframe with the ConferenceHype origin and referrer. The workflow stops before saving the public video handoff when YouTube returns:

EMBEDDER_IDENTITY_MISSING_REFERRER
Playback on other websites has been disabled
disabled by the video owner

For a targeted repair, manually run the Enable YouTube embedding workflow and provide the affected YouTube video ID.

30-Minute Single-Journal Broadcasts

Regional Journal Club series

ConferenceHype has two additive regional series: JOURNAL CLUB - INDIA JOURNAL ARTICLES and JOURNAL CLUB - UNITED KINGDOM JOURNAL ARTICLES. They reuse the current Journal Club badge, typography, colors, evidence dashboard, narration, source attribution, thumbnail/opening-frame byte stream, and 30-minute frame. They do not modify or activate the weekday station or weekend wheel.

The India catalog contains 20 curated journals and is scheduled for Tuesday and Friday at 7:30 PM Asia/Kolkata. The United Kingdom catalog contains 22 curated journals and is scheduled for Wednesday and Sunday at 6:30 PM Europe/London. Each program requires 12 unique, substantive PubMed-grounded cards, excludes cards already reserved by the station or either regional series, and searches 14, 21, 28, then 35 days without lowering the card floor.

Regional journal membership is explicit in journal_series_memberships; country identity is never inferred from author affiliation or article subject. New region-only journal rows carry regional_only=true, and both weekday selection paths explicitly reject those rows. Existing UK journals may remain eligible for their established weekday cadence while also being explicit UK series members.

.github/workflows/regional-journal-club.yml defaults to shadow planning. A render/upload occurs only when the matching journal_series.enabled row is true and REGIONAL_JOURNAL_CLUB_PUBLISH_ENABLED (or the manual publish input) is true. The workflow never calls either station activation function and never writes stream_state; successful regional uploads remain independent YouTube series videos.

Weekend roundup wheel

Saturday and Sunday use a separate, additive station-planning lane. At 8:00 AM America/New_York, the recurring GitHub Actions workflow ranks only quality- passed card IDs stored on verified Monday-Friday station programs. Ranking is deterministic and cost-free: explicit trial or study names, registry IDs, randomized or phase-trial language, clinically meaningful outcomes, structured article quality, and numerical results receive additional weight. No LLM is called. Saturday receives the top 24 cards in one 30-minute program. Sunday uses 24 cards not selected Saturday when available; if weekly inventory is lower, it keeps every unused card first and fills only the remaining positions with the next-best cards already used Saturday.

The program begins at 9:00 AM Eastern. After its YouTube upload verifies, an isolated weekend-only database function repeats that canonical video across the six-position station wheel for that day. It never changes weekday selection, weekday card status, or the weekday workflow. A failed render cannot activate a partial weekend schedule, so the previously verified public player remains available. Monday's normal weekday activation supersedes the weekend wheel.

Every upcoming weekend program is packaged as a multi-journal Journal Club. Its YouTube title begins JOURNAL CLUB | <resolved specialties> |, followed by the source-grounded clinical topic and article hook. Its description begins with JOURNAL CLUB, then Relevant specialties: ..., before the roundup part, study, journal, chapter, and source details. The opening thumbnail, persistent top frame, and in-video evidence-dashboard header use the same JOURNAL CLUB | <resolved specialties> label. Specialties are derived only from the journals attached to the selected approved cards; they are never invented, and the weekend metadata gate fails closed when none can be resolved. This is prospective for all Saturday and Sunday weekend30 renders. It does not apply the dedicated single-journal thumbnail layout: weekend artwork still shows at most two actual journal names plus an accurate + N JOURNALS count.

The description and tags also list explicit trial/study names found in approved PubMed-grounded content, journals, article chapters, and source context; names are omitted rather than invented. Each program ends with one roundup conclusion and uses full-length Funk/Latin music blocks for any unused portion of the 30-minute frame. Weekend planning budgets 55 seconds per article card, based on measured production narration, so 24 articles fit without the pre-render planner discarding them; the measured post-narration reconciler still makes the finished video exactly 30 minutes.

On July 25, 2026, video 6qKRZ1JJG44 exposed the earlier 12-card capacity cap: its selected cards finished after roughly 12 to 15 minutes and the renderer correctly filled the remainder with music. The source week contained 72 eligible, actually-broadcast cards, so this was a selection-capacity defect, not missing intake. The 24-card-per-program invariant and verifier prevent that failure from recurring. A second broadcast format, additive to the existing 60-minute mixed-content hourly show: a journal_broadcast_slots row picks one journal for a 30-minute, single-persona show that narrates only that journal's approved cards, in groups of 4 with a music break after every group and the disclaimer after every 2nd group — fewer, denser silent gaps than the hourly format. It runs alongside conference-coverage hours, never replacing them.

Status as of 2026-07-18: Phases A-D (data model, scheduling, render integration, admin UI) are built, committed, and verified — including a real render exercised via HOUR_BROADCAST_DRY_RUN=1 and a live admin-UI slot creation. Phase E's manual workflow_dispatch path (create real broadcast, render, upload, verify) is wired and has been exercised via many real youtube-stream.yml dispatches, including multiple journal slots per day. The schedule: cron has deliberately not been switched over to run this format automatically — it still only fires the existing hourly/conference format; every journal broadcast so far has been started manually via the "Start journal broadcast"/"Run now" buttons in the admin's "Journal-only broadcasts for this hour" panel. Cutting the cron over to 15,45 * * * * and teaching the "Resolve block start time" step to pick up journal_broadcast_slots is the last remaining step, intentionally deferred until the format has run cleanly enough, for long enough, on manual dispatch alone.

Key files: lib/broadcast/journalShowSchedule.ts (group/music/disclaimer constants), lib/rundown/slots.ts's buildJournalShowSlots / personaForJournalShow, scripts/render-hour-broadcast.ts's journal30 mode branch, components/SingleJournalPicker.tsx + components/DailyCoveragePlanner.tsx's "Journal-only broadcasts for this hour" panels.

Three real bugs were found and fixed while running the first manual test broadcasts through this new path:

• Duplicate-article cards. buildJournalShowSlots could schedule the same underlying article twice in one show when it existed as two separate approved segment rows (e.g. a weekly-digest card and a same-week one-hour-batch card both citing the same URL). Fixed by deduping on contentSignature (extracted into a shared lib/segments/contentSignature.ts, reused from the hourly format's existing dedup logic) before grouping segments into cards.
• broadcast_writeouts alignment check has no row to check for a 30-minute show. broadcast_writeouts has a hard duration_minutes = 60 check and a FK to conference_coverage_slots, so a journal show correctly never writes one (render-hour-broadcast.ts already guarded saveBroadcastWriteout behind !isJournalMode). What was missed: two separate verification scripts — scripts/verify-public-broadcast-alignment.ts and lib/media/youtubeDeliveryVerifier.ts's assertPublicState (used both mid-stream and at stream completion) — unconditionally required a matching writeout row and threw/timed out without one. A real test dispatch got all the way through rendering and streaming before failing at this check. Fixed by threading a JOURNAL_SLOT_ID env var through both scripts and both youtube-stream.yml verification steps; when set, they confirm the right video is public via stream_state and skip the writeout lookup entirely, rather than requiring a table row that can't structurally exist for this format. Other broadcast_writeouts consumers (lib/data.ts's findMatchingWriteout, the admin writeout archive display) were checked and already degrade gracefully with no row present, so needed no changes.
• Silent post-render write failures with useless error logs. The first fully clean end-to-end journal30 test (video xh77Aljha6o) still shipped with two gaps: the post-render title/description rebuild never landed (video stayed on its placeholder title), and the segments used in the show never got flipped to rendered, leaving them eligible for reuse in a future broadcast. Both writes failed within the same ~2-second window in scripts/render-hour-broadcast.ts while every other network call in the same job succeeded — consistent with a transient runner network blip, not a deterministic bug. Root-causing this was slower than it should have been because both catch blocks logged ${error}/String(error) on plain Supabase/fetch error objects, which stringify to "[object Object]" instead of anything useful. Fixed by adding a helper that extracts the error's actual fields, and wrapping both writes (both idempotent — safe to repeat) in a short retry via a new helper.

Automation Cadence

• generate.yml: hourly, including fresh ingestion
• ingest.yml: daily safety pull
• upcoming-events.yml: every six hours
• youtube-stream.yml: hourly continuation check and manual dispatch. Every scheduled broadcast must run the verifier loop after streaming; if the loop cannot prove the rendered MP4, YouTube live/completed state, saved YouTube video, Supabase stream state, saved writeout, and conferencehype.com all match the same video ID, the broadcast process is still broken and must keep failing/retrying until fixed.
• weekly-source-cards.yml: low-cost weekly ready-card pre-generation for every enabled conference, journal RSS feed, and clinical news/newspaper source. It fetches the configured source catalog once, creates deterministic pending-review cards without LLM expansion by default, and tags them as the weekly ready-card pool. When an operator selects that conference, journal, or news source for an hour, unused weekly cards are shown and reused first; newly generated cards only fill remaining space. Cards already scheduled/broadcast are not reused ahead of unused weekly cards. If any enabled source has no weekly card, the generator must create a viewer-facing context card for that source, the verifier must fail, and the daily loop must run the weekly-card repair step until every enabled source has an unused weekly ready card.
• daily-verification-loop.yml: the single daily verification loop. It runs typecheck, broadcast guards, RSS feed verification, weekly source-card verification, the Complete RSS card scheduling report, randomized platform smoke, public stream handoff resolution, YouTube delivery verification, and automatic repair/retry passes before reporting failure. The automatic repair passes are: refresh ingestion and rerun RSS verification after source failure; verify weekly source cards and rerun weekly-card generation if any enabled source is missing an unused weekly ready card; report the Complete RSS card scheduling result daily; rerun the randomized platform smoke loop after smoke failure; run a short smoke repair pass and resolve the public handoff again when conferencehype.com does not expose a live/completed YouTube ID; set the YouTube video privacy to public and rerun delivery verification after delivery failure. Only unresolved failures after those repair passes open a GitHub issue and fail the workflow.
• platform-smoke-loop.yml: manual targeted randomized platform smoke repair. The daily schedule lives in daily-verification-loop.yml.
• youtube-delivery-daily-verify.yml: manual targeted YouTube delivery repair. It accepts the render-then-upload terminal queued state, then independently verifies the saved YouTube video, public privacy, database handoff, and site exposure before reporting success.

Where rendered media is written

Rendered videos are uploaded to YouTube from the GitHub Actions runner, so production renders never touch the operator's computer. A render run by hand writes a file, and the project folder lives inside the OneDrive-synced Desktop, so anything written under it (public/rendered, .tmp) is uploaded to the personal OneDrive account.

• Default for hand-run renders (2026-10-14). lib/media/localOutputDir.ts sends output to the OS temp directory (<temp>/conferencehype/rendered), which is outside OneDrive. This covers render-hour-broadcast.ts, ffmpeg-render.ts, dub-korean-broadcast.ts, and the hype-line frame scratch directory.
• CI is unchanged. When GITHUB_ACTIONS or CI is set the original public/rendered/... paths are used, because the workflows cache and upload from them on the runner.
• Override. Set CONFERENCEHYPE_MEDIA_DIR to an absolute path outside OneDrive to choose the location, or the per-script variables (HOUR_BROADCAST_OUTPUT, HOUR_BROADCAST_DIR, RENDER_DIR, KOREAN_DUB_OUTPUT, KOREAN_DUB_DIR) to set exact files.
• Still synced. Dependencies and build output (node_modules, .next) and anything under .tmp or .claude/worktrees live in the synced folder because the repository itself does. The durable fix is to keep the working copy outside OneDrive (for example C:\Dev), or turn off OneDrive's Desktop backup.

Verification

Local checks:

npm install
npm run typecheck
npm run test:guards
npm run test:rss
npm run build

Delivery check loop (post-migration: single-pass upload verification, no more live/completed phases):

$env:YOUTUBE_VIDEO_ID="<video id>"
npm run verify:youtube-delivery

Full randomized platform smoke loop:

npm run verify:platform-smoke

In GitHub Actions the smoke loop dispatches youtube-stream.yml, waits for the stream workflow to finish, and then verifies the uploaded/queued video. A successful run must include content cards and music cards in the saved broadcast_writeouts record.

A configured workflow or a YouTube watch page alone does not prove a successful upload. Before declaring it good, verify:

1. The render contains both video and audio streams (assertMediaGenerated in lib/media/youtubeDeliveryVerifier.ts).
2. The upload step logs Uploaded <url>, public immediately..
3. The uploaded video's status.uploadStatus is processed/uploaded (not deleted/failed/rejected), and status.privacyStatus is public.
4. stream_state.youtube_video_id/youtube_status and the matching broadcast_writeouts row agree on the same video ID (youtube_status should be queued).
5. The YouTube watch page finds the video by ID and it's already publicly playable (no private/scheduled-release wait — uploads go public immediately as of 2026-07-17).
6. Confirm conferencehype.com shows "Live now" / the correct "Current topic" once the slot's scheduled window arrives (derived from wall-clock time against the slot's own window, not a stored live status — see deriveDisplayYoutubeStatus/the currently-airing-slot check in lib/data.ts). If multiple slots are queued at once, confirm the site features whichever one's window actually contains "now", not just whichever was queued most recently.
7. After the show's scheduled end time, confirm the public site's "Current topic" section stops showing (source degrades gracefully back to approved segments), with the saved YouTube video still reachable.

Deployment

1. Apply pending Supabase migrations.
2. Run the local verification commands.
3. Commit and push the release to GitHub.
4. Deploy main to Vercel.
5. Confirm conferencehype.com, /admin/login, and /api/stream/status.
6. Approve the desired programming in admin.
7. Start an unlisted rehearsal.
8. Complete all live and completed verification checks above.

Failure Recovery

• The site shows the wrong video: compare /api/stream/status with the workflow video ID and confirm the Supabase service credentials are present.
• The iframe says playback is disabled: run the targeted embed repair, verify YOUTUBE_EMBED_ENABLED=true, and confirm the iframe origin and referrer guard test passes. If YouTube rejects an embed metadata toggle with invalidEmbedSetting, the iframe preflight remains the source of truth.
• The site shows an old replay after a failed start: /api/stream/status should report failed and no stale YouTube ID for the attempted broadcast. The workflow records failures for continuous/manual runs even when no coverage slot ID exists.
• The site shows a direct YouTube button instead of an iframe: embedding is disabled in Vercel or the deployment has not picked up the environment change.
• Start selected hour fails: verify GITHUB_DISPATCH_TOKEN can dispatch Actions, GITHUB_DISPATCH_REPO names the correct repository, and the selected hour is not more than one hour in the past.
• OAuth returns access denied: add the signing-in Google account as an OAuth test user or publish/verify the consent screen as appropriate.
• A scheduled hour does not publish: confirm the slot is enabled, approved, in the future, and still has youtube_status = not_scheduled.
• No generated cards: inspect ingestion logs, LLM credentials, source selections, and exclusions. For journal cards specifically, also check for NCBI PubMed 429 rate-limit responses — a journal can have a healthy RSS feed full of real items and still fall back to the generic "no new tracked articles" card if PubMed enrichment was throttled or found no exact title match.
• RSS verification fails: disable or replace the failed official feed.
• The same article produces more than one card in the same week: check the conference/journal/source catalog for a duplicate row by name first — seed reconciliation conflicts on URL, not name, so correcting a feed URL can silently orphan a stale duplicate row that keeps generating its own cards. Weekly card generation also re-checks for an existing match immediately before saving, as a backstop against an overlapping run.
• The same card plays more than once in one hour: check for duplicate approved rows sharing a citation URL or script text (see the content-signature dedup note under "Broadcast Presentation") before assuming it's a scheduling bug.
• Broadcasts feel sparse, or bonus-card gap filling stops finding content: check how many segments are currently (). Since segments now transition to after actually airing (see "Production Flow" step 14), the approved pool only drains — it never refills itself. If continuous mode has been running without matching card approval, this count can get very low (confirmed near-empty, 2 rows, during testing on 2026-07-09). Run , , or to replenish it, or check why the backlog isn't being approved.

Safety

ConferenceHype is interactive AI commentary only. It is not reporting, journalism, medical education, clinical guidance, scientific validation, legal advice, or financial advice. Source attribution and operator review remain required for broadcast programming.