What we’ve shipped

Users receive a fresh scripture-based devotional every day at their chosen local hour, delivered via Telegram and/or surfaced in the companion chat. The system is week-aware: Monday opens a theme, Friday closes with reflection, mid-week entries develop it.

(migration 0011) — week records track theme, proposedNextTheme, and week-end reflection; entry records carry all rendered fields (dayRole, scriptureRef, scriptureText, opening, reflection, prayerPrompt, question) plus Telegram delivery metadata.

— ensureTodaysDevotional is the core coordinator: claim a pending slot, call the role-specific LLM tool (theme_open / reflection_close / middle), write the result. Idempotent — concurrent callers compete for a pending row; only the first writer wins. LLM output truncated via v100()/txt() helpers before every DB write. tool_choice: { type: "tool", name } forces the correct role-specific tool to fire.

— hourly Vercel cron that sweeps stale pending entries (> 10 min old), finds users at their delivery hour, generates entries, and sends to Telegram. Midnight hour normalized (% 24) for V8 Intl.DateTimeFormat quirk. Query capped at 500 users per run with a log warning when the limit is hit.

— nightly cron that extracts week-level reflection from completed entries and proposes next week's theme.

— returns today's devotional for the authenticated user (generating on first request).

— saves timezone, delivery hour, and devotional_enabled flag. IANA timezone validated via Intl.DateTimeFormat; isValidIanaZone exported for testability.

(src/components/companion/DevotionalMessage.tsx) — inline companion card rendering scripture reference, opening, reflection, prayer prompt, and reflection question with gold-tinted scripture styling per DESIGN.md.

(src/components/settings/DevotionalCard.tsx) — timezone picker (20 common zones), hourly delivery selector, enable toggle, "Send now" preview button.

— new step 4 in the onboarding flow introducing the devotional, with a scripted companion demo that walks through the companion philosophy using pre-scripted message pairs.

— devotional note type now renders a gold "Devotional" badge in the notes list.

— replaces a blind cast in the companion page; validates dayRole shape before rendering the devotional card inline.

— sendDevotional renders devotionals as clean Markdown messages; atomic update sets deliveredTelegramAt only when IS NULL to prevent double-sends.

(269 total) — chunkMessage, verifyWebhookSecret, isValidIanaZone with full branch coverage.

midnight normalization, scale cap log warning, reflection_close idempotency guard, handleConnect single body parse.

Previously, a Telegram user with no Selah account hit a dead end: the bot sent them to /settings/telegram (7 steps to actually get connected). Now the bot creates a one-time signup invite, sends a single "Sign up to Selah" button, the website binds the chat on signup, and the user lands back in Telegram with the bot already greeting them.

(migration 0010) — 32-byte url-safe random token, 24h TTL, single-use, tracks chatId + Telegram username/first name. Inverse direction of the existing telegram_link_codes flow (website → bot).

— createSignupInvite, findOpenInviteForChat, findSignupInvite, claimSignupInvite, pushTelegramWelcomeIfEligible, buildWelcomeMessage. The claim function handles happy path, invalid/expired/consumed tokens, and cross-user guard with idempotent self-reclaim.

— auth-required. Body { token }. Binds the chat to the authenticated user and returns botDeepLink from TELEGRAM_BOT_USERNAME. Maps claim errors to 400 (invalid/expired/consumed) and 409 (chat_linked_to_another_user).

(src/app/api/telegram/webhook/route.ts) — replaced the dead-end "go to settings" message with a personalized welcome + "Sign up to Selah" button. Reuses an existing open invite if the user re-messages instead of creating a fresh row each time.

(src/app/sign-up/page.tsx, src/app/sign-in/page.tsx) — read ?via=telegram&t=TOKEN on mount, stash the token in sessionStorage, show a "Signing up from Telegram" banner. After successful auth, call /api/telegram/claim immediately. Sign-up routes to /onboarding?via=telegram; sign-in (already-onboarded users) redirects straight to the bot via window.location. Wrapped in Suspense for useSearchParams() per Next.js 16.

(src/app/onboarding/onboarding-flow.tsx) — detects via=telegram from the URL, hides the "How did you find Selah?" question, forces signup_source = "telegram" in the PATCH (including on Skip), and swaps the step 3 CTA from "Enter Selah" to "Open Telegram." On completion, reads telegramBotDeepLink from the response and redirects via window.location.

now returns telegramBotDeepLink when signup_source === "telegram" and TELEGRAM_BOT_USERNAME is set. Also triggers pushTelegramWelcomeIfEligible on the first completion transition (gated behind !before.completed). Non-fatal if the push fails.

— 3-tier context-aware greeting: anchors on first capture content if saved, else on current focus, else falls back to a generic "share a thought" prompt. All under 2 sentences per DESIGN.md's Telegram response rules. No emoji in message text (DESIGN.md rule).

remains unchanged: signup_source = "telegram" is analytics, not memory, so it isn't written to memory_facts.

— the chat → user link is established before onboarding begins. If the user abandons mid-onboarding, they can return to Telegram and keep using the bot; onboarding resumes on their next web visit.

20 helper tests (telegram-signup.test.ts), 11 claim-route tests (telegram-claim-route.test.ts), plus updates to the onboarding-route suite covering the welcome-push gate and the bot deep link response shape.

— role (required-ish) plus four optional companion-context questions: Bible translation, what they're studying right now, theological tradition, and how they found Selah. All optional fields can be skipped with one button.

— 9-option pill row (ESV, NIV, NLT, KJV, NASB, CSB, NRSV, MSG, Other), defaulted to ESV. Stored on user_onboarding.translation.

— 11-option pill row (Reformed, Wesleyan, Pentecostal, Baptist, Anglican, Lutheran, Catholic, Orthodox, Non-denominational, Still exploring, Other). Framed sensitively: "so we don't push contradictory stuff." Stored on user_onboarding.tradition.

— single-line text input. "What are you studying right now?" → free text up to 500 chars. The single biggest unlock for first-session value.

— "How did you find Selah?" pill row (Friend, Social, Search, Blog/podcast, Other). Stored on user_onboarding.signup_source. Analytics-only, NOT memory.

— when a user finishes onboarding, role/translation/tradition/currentFocus are written into memory_facts (category: life_context / preference / theology, confidence 0.95, sourceType manual). The companion sees these from message #1 instead of cold-starting from zero. Gated so re-entry doesn't double-seed; non-fatal if seeding fails.

inside the onboarding flow with proper radiogroup/radio ARIA roles, 44px min touch targets, sage active state.

— additive ALTER TABLE for the four new columns. Idempotent.

— helper coverage for the new fields, EAV mapping in seedMemoryFactsFromOnboarding, route validation for every new field's enum + bounds, the seeding gate (fires once, no re-fire on re-entry), and the non-fatal error path.

— New optimized signup form replaces the inline toggle on /sign-in. Name is optional. Password has a show/hide toggle. Clear value prop, trust microcopy ("Free. No credit card. Takes 30 seconds."), and friendly error states.

— /sign-in is now sign-in only with a clear link to /sign-up for new users. Matches signup-flow-cro best practices: one page, one job.

— /onboarding is a 3-step guided experience new users hit immediately after signup:

1. Welcome + role — Pick how you use scripture (pastor, small group leader, student, personal). Skippable. Feeds companion personalization later.
2. First capture (aha moment) — Guided textarea with an example placeholder. Saves a real stream capture so the user sees their Home populated immediately. Supports Cmd/Ctrl+Enter to submit.
3. You're ready — Warm recap of what Selah can do (capture, companion, notes, prayer). Single CTA: "Enter Selah."

— New user_onboarding table tracks role, first capture, and completed_at. Home page redirects any user with completed_at IS NULL to /onboarding, so returning users who bailed mid-flow resume where they left off.

— GET reads status (creates row lazily), PATCH updates role, saves first capture, or marks complete. All fields optional so the client can update progressively.

— /sign-up is now excluded from Neon Auth proxy alongside /sign-in so unauthenticated visitors can reach it.

— Type /prep [topic] to start a Socratic interview for sermon, Bible study, or devotional prep. The AI interviews you (8+ exchanges before it lets you build), then formats your words into a structured teaching note with inline enrichment tags ([Historical], [Greek/Hebrew], [Cross-ref], [Cultural], [Illustration]). Your voice stays central. Saved as a note you can edit in the Tiptap editor.

— The companion tracks what mode you're in (prep, interview, pray) server-side. No more frontend guessing.

— The AI can't skip the interview. The save_prep tool is withheld until you've had enough exchanges. When you say "done," the AI is forced to call the tool instead of just saying "Building now."

— Prep output matches your vocabulary and tone. If you write simply, the note reads simply.

— When the AI builds your prep note, a loading overlay shows progressive status messages instead of a generic spinner.

— Deep-dive conversations with pull-quote transcript UI.

— Attach your stream captures and notes to companion messages as context.

— Leave and come back. Your conversation picks up where you left off.

— Quick-access slash commands for common actions.

).