LETS GOOOOOOOOOOOOOOOOOOOOOOOOO

backend/alembic/versions/0003_billing_events.py

@@ -0,0 +1,29 @@
+"""billing events: Stripe webhook deliveries already handled
+
+Revision ID: 0003_billing_events
+Revises: 0002_build_out
+Create Date: 2026-09-27
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0003_billing_events"
+down_revision = "0002_build_out"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 0001 builds from the live models, so a fresh database may already have the table.
+    if "billing_events" in sa.inspect(op.get_bind()).get_table_names():
+        return
+    op.create_table(
+        "billing_events",
+        sa.Column("id", sa.String(100), primary_key=True),
+        sa.Column("type", sa.String(80), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("billing_events")

backend/app/models/__init__.py

@@ -21,11 +21,12 @@ from app.models.content import (
     VoiceProfile,
 )
 from app.models.email import EmailVerificationCode, UpdateEmail, UpdateEmailSend, VerificationPurpose
-from app.models.user import AuthProvider, Subscription, User, Workspace, WorkspaceMember
+from app.models.user import AuthProvider, BillingEvent, Subscription, User, Workspace, WorkspaceMember
 
 __all__ = [
     "Artifact",
     "AuthProvider",
+    "BillingEvent",
     "CalendarItem",
     "Chat",
     "Citation",

backend/app/models/user.py

@@ -70,3 +70,13 @@ class Subscription(IdMixin, TimestampMixin, Base):
     provider_customer_id: Mapped[str | None] = mapped_column(String(100))
     provider_subscription_id: Mapped[str | None] = mapped_column(String(100))
     current_period_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class BillingEvent(Base):
+    """Stripe webhook events already handled, so a retried delivery never sends a second email."""
+
+    __tablename__ = "billing_events"
+
+    id: Mapped[str] = mapped_column(String(100), primary_key=True)  # Stripe event id (evt_...)
+    type: Mapped[str] = mapped_column(String(80))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))

backend/app/routers/billing.py

@@ -3,8 +3,11 @@ from typing import Literal
 from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel
 
+from sqlalchemy.orm import Session
+
 from app.auth import Ctx, get_ctx
 from app.config import settings
+from app.db import get_db
 from app.services.billing import billing_status, create_checkout_url, create_portal_url
 from app.services.plans import PLAN_ORDER, PLANS, effective_plan, plan_dict
 
@@ -50,10 +53,28 @@ def portal(ctx: Ctx = Depends(get_ctx)):
     return {"url": create_portal_url(ctx.db, ctx.workspace)}
 
 
+class ConfirmIn(BaseModel):
+    session_id: str
+
+
+@router.post("/confirm")
+def confirm(body: ConfirmIn, ctx: Ctx = Depends(get_ctx)):
+    """Called when the app lands back from Checkout, so the new plan applies even if the webhook is late."""
+    if not settings.billing_enabled:
+        raise HTTPException(409, {"code": "billing_disabled", "message": "Billing is not available yet."})
+    from app.services import stripe_billing
+
+    stripe_billing.confirm_checkout(ctx.db, ctx.workspace, body.session_id)
+    return billing_status(ctx.db, ctx.workspace)
+
+
 @router.post("/webhook")
-async def webhook(request: Request):
-    """TODO(stripe): verify the Stripe-Signature header against STRIPE_WEBHOOK_SECRET, then map events to
-    services.billing.apply_subscription (workspace id from client_reference_id, plan from metadata)."""
+async def webhook(request: Request, db: Session = Depends(get_db)):
+    """Stripe events. The signature is checked against the raw body, so nothing in front of the API may
+    rewrite it. Point the Stripe endpoint at {API_URL}/api/billing/webhook."""
     if not settings.billing_enabled:
         return {"ignored": True}
-    raise HTTPException(501, "Webhook not wired yet")
+    from app.services import stripe_billing
+
+    event = stripe_billing.parse_event(await request.body(), request.headers.get("stripe-signature"))
+    return {"received": True, "result": stripe_billing.handle_event(db, event)}

backend/app/services/billing.py

@@ -165,18 +165,16 @@ def return_urls() -> tuple[str, str]:
 
 
 def create_checkout_url(db: Session, user: User, workspace: Workspace, plan: Plan, cycle: str) -> str:
-    """Return the hosted checkout URL for plan on the monthly or annual cycle.
+    """Hosted Stripe Checkout for plan on the monthly or annual cycle, or an in place plan change (which may
+    return Stripe's invoice page when the bank wants 3D Secure). See services/stripe_billing.py."""
+    from app.services import stripe_billing
 
-    TODO(stripe): create a Checkout Session in subscription mode with the price for (plan.id, cycle),
-    customer_email=user.email, client_reference_id=str(workspace.id), metadata={"plan": plan.id},
-    success_url/cancel_url from return_urls(), and return session.url.
-    """
-    raise HTTPException(501, {"code": "checkout_not_wired", "message": "Checkout is almost ready. Check back soon."})
+    success, cancel = return_urls()
+    return stripe_billing.start_checkout(db, user, workspace, plan, cycle, success, cancel)
 
 
 def create_portal_url(db: Session, workspace: Workspace) -> str:
-    """Return the customer portal URL for managing or cancelling a subscription.
+    """Stripe customer portal: change card, switch or cancel the plan, download invoices."""
+    from app.services import stripe_billing
 
-    TODO(stripe): billing_portal.Session.create(customer=sub.provider_customer_id, return_url=.../app/settings).
-    """
-    raise HTTPException(501, {"code": "portal_not_wired", "message": "Billing management is almost ready."})
+    return stripe_billing.portal_url(db, workspace, f"{settings.frontend_url.rstrip('/')}/app/settings")

backend/app/services/email.py

@@ -181,6 +181,29 @@ class EmailService:
             )
         )
 
+    # Billing
+
+    def send_payment_action(self, to: str, kind: str, url: str) -> bool:
+        """kind: 'confirm' (the bank wants 3D Secure for a renewal) or 'failed' (card declined; Stripe retries)."""
+        if kind == "confirm":
+            title, subject = "Confirm your payment", "Your bank needs you to confirm your Notestack payment"
+            body = ("Your bank asked for a quick confirmation (3D Secure) before your Notestack renewal can go "
+                    "through. It takes a few seconds, and your plan stays active meanwhile.")
+            cta = "Confirm payment"
+        else:
+            title, subject = "Your payment did not go through", "Your Notestack payment failed"
+            body = ("We could not charge your card for Notestack. We will retry automatically over the next few "
+                    "days; update your card to keep your plan without interruption.")
+            cta = "Update payment"
+        return self._send(
+            OutgoingEmail(
+                to=to,
+                subject=subject,
+                html=_layout(title, html.escape(body) + _button(cta, url)),
+                text=f"{body}\n\n{cta}: {url}",
+            )
+        )
+
     # Internal alerts
 
     def send_alert(self, subject: str, text: str) -> bool:

backend/app/services/plans.py

@@ -124,7 +124,8 @@ def effective_plan(db: Session, workspace: Workspace) -> Plan:
     if not settings.billing_enabled:
         return PLANS["studio"]
     sub = db.query(Subscription).filter_by(workspace_id=workspace.id).one_or_none()
-    if not sub or sub.status not in {"active", "trialing"}:
+    # past_due keeps the plan while Stripe retries the card (grace period); unpaid or canceled drop to Free.
+    if not sub or sub.status not in {"active", "trialing", "past_due"}:
         return PLANS["free"]
     return PLANS.get(sub.plan, PLANS["free"])
 

backend/app/services/stripe_billing.py

@@ -0,0 +1,351 @@
+"""Stripe: hosted Checkout, the customer portal, plan changes and webhooks.
+
+Hard parts handled here:
+- 3D Secure / SCA. Checkout runs 3DS on the first payment. Renewals that need it arrive as
+  invoice.payment_action_required: the plan stays active and the owner gets the hosted invoice link to
+  confirm. Upgrades use payment_behavior=pending_if_incomplete, so the new plan applies only after the
+  payment succeeds; if the bank wants 3DS the user is sent to the invoice page to confirm.
+- Failed payments. past_due keeps the plan (Stripe retries per the dashboard's dunning settings) and the
+  owner is emailed a link to fix the card; unpaid, canceled or incomplete_expired drop to Free.
+- Webhooks. Signatures are verified against the raw body. Every handler re-reads the subscription from
+  Stripe instead of trusting the event payload, so retries and out of order deliveries converge on the
+  true state. Side effects (emails, alerts) run once per event id (billing_events table).
+- Duplicates. One Stripe customer per workspace, created before checkout and reused; a workspace that
+  already has a live subscription changes plan in place instead of opening a second subscription.
+- Redirect before webhook. The success URL carries the Checkout Session id and the app confirms it
+  directly (confirm_checkout), so the plan shows up even if the webhook is late.
+- Prices. Found by lookup key notestack_<plan>_<cycle>, created from services/plans.py when missing
+  (so test and live mode both work without dashboard setup), or pinned with STRIPE_PRICE_* env vars.
+"""
+
+import logging
+import uuid
+from datetime import UTC, datetime
+
+import stripe
+from fastapi import HTTPException
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app.config import settings
+from app.models import BillingEvent, Subscription, User, Workspace
+from app.services.plans import PLANS, Plan, annual_prices
+
+log = logging.getLogger(__name__)
+
+LIVE = {"active", "trialing", "past_due"}  # statuses that keep the paid plan (past_due = grace while retrying)
+_prices: dict[str, str] = {}
+
+
+def client() -> stripe.StripeClient:
+    if not settings.stripe_secret_key:
+        raise HTTPException(503, {"code": "stripe_not_configured", "message": "Payments are not configured yet."})
+    return stripe.StripeClient(settings.stripe_secret_key, max_network_retries=2)
+
+
+def _get(obj, key, default=None):
+    """Read a field from a StripeObject or a plain dict."""
+    try:
+        value = obj[key]
+    except (KeyError, TypeError, AttributeError):
+        return default
+    return default if value is None else value
+
+
+def _ts(value) -> datetime | None:
+    return datetime.fromtimestamp(int(value), UTC) if value else None
+
+
+# Prices
+
+
+def lookup_key(plan_id: str, cycle: str) -> str:
+    return f"notestack_{plan_id}_{cycle}"
+
+
+def price_id(sc: stripe.StripeClient, plan: Plan, cycle: str) -> str:
+    pinned = getattr(settings, f"stripe_price_{plan.id}_{cycle}", "")
+    if pinned:
+        return pinned
+    key = lookup_key(plan.id, cycle)
+    if key in _prices:
+        return _prices[key]
+    found = sc.v1.prices.list({"lookup_keys": [key], "active": True, "limit": 1}).data
+    if found:
+        _prices[key] = found[0].id
+        return found[0].id
+    product_id = f"notestack_{plan.id}"
+    try:
+        sc.v1.products.retrieve(product_id)
+    except stripe.InvalidRequestError:
+        sc.v1.products.create({"id": product_id, "name": f"Notestack {plan.name}", "metadata": {"plan": plan.id}})
+    amount = plan.price_monthly_usd if cycle == "monthly" else annual_prices(plan)[1]
+    price = sc.v1.prices.create({
+        "product": product_id,
+        "currency": "usd",
+        "unit_amount": round(amount * 100),
+        "recurring": {"interval": "month" if cycle == "monthly" else "year"},
+        "lookup_key": key,
+        "transfer_lookup_key": True,
+        "metadata": {"plan": plan.id, "cycle": cycle},
+    })
+    _prices[key] = price.id
+    return price.id
+
+
+def plan_for_price(price) -> str | None:
+    """Plan id for a Stripe Price: pinned env ids, then lookup key, then metadata."""
+    pid = _get(price, "id")
+    for plan_id in ("writer", "studio"):
+        for cycle in ("monthly", "annual"):
+            if pid and getattr(settings, f"stripe_price_{plan_id}_{cycle}", "") == pid:
+                return plan_id
+    key = _get(price, "lookup_key") or ""
+    if key.startswith("notestack_"):
+        plan_id = key.split("_")[1]
+        if plan_id in PLANS:
+            return plan_id
+    plan_id = _get(_get(price, "metadata", {}), "plan")
+    return plan_id if plan_id in PLANS else None
+
+
+# Customers and subscriptions
+
+
+def _subscription_row(db: Session, workspace_id: uuid.UUID) -> Subscription:
+    sub = db.scalar(select(Subscription).where(Subscription.workspace_id == workspace_id))
+    if not sub:
+        sub = Subscription(workspace_id=workspace_id, plan="free", status="active")
+        db.add(sub)
+        db.flush()
+    return sub
+
+
+def ensure_customer(sc: stripe.StripeClient, db: Session, user: User, workspace: Workspace) -> str:
+    sub = _subscription_row(db, workspace.id)
+    if sub.provider_customer_id:
+        return sub.provider_customer_id
+    customer = sc.v1.customers.create(
+        {"email": user.email, "name": user.name or None, "metadata": {"workspace_id": str(workspace.id)}},
+        {"idempotency_key": f"customer-{workspace.id}"},
+    )
+    sub.provider, sub.provider_customer_id = "stripe", customer.id
+    db.commit()
+    return customer.id
+
+
+def sync_subscription(db: Session, workspace_id: uuid.UUID, stripe_sub) -> Subscription:
+    """Store the subscription's true state. Safe to call any number of times, in any order."""
+    items = _get(_get(stripe_sub, "items", {}), "data", [])
+    first = items[0] if items else {}
+    status = _get(stripe_sub, "status", "canceled")
+    plan_id = plan_for_price(_get(first, "price", {})) or _get(_get(stripe_sub, "metadata", {}), "plan")
+    period_end = _get(stripe_sub, "current_period_end") or _get(first, "current_period_end")
+    sub = _subscription_row(db, workspace_id)
+    sub.provider = "stripe"
+    sub.provider_customer_id = _get(stripe_sub, "customer") or sub.provider_customer_id
+    sub.provider_subscription_id = _get(stripe_sub, "id")
+    sub.status = status
+    sub.plan = plan_id if (plan_id in PLANS and status in LIVE) else "free"
+    sub.current_period_end = _ts(period_end)
+    db.commit()
+    return sub
+
+
+def _workspace_for(db: Session, stripe_sub=None, customer_id: str | None = None) -> uuid.UUID | None:
+    ws = _get(_get(stripe_sub, "metadata", {}), "workspace_id") if stripe_sub is not None else None
+    if ws:
+        return uuid.UUID(ws)
+    sub_id = _get(stripe_sub, "id") if stripe_sub is not None else None
+    customer_id = customer_id or (_get(stripe_sub, "customer") if stripe_sub is not None else None)
+    row = None
+    if sub_id:
+        row = db.scalar(select(Subscription).where(Subscription.provider_subscription_id == sub_id))
+    if not row and customer_id:
+        row = db.scalar(select(Subscription).where(Subscription.provider_customer_id == customer_id))
+    return row.workspace_id if row else None
+
+
+# Checkout, plan changes, portal
+
+
+def start_checkout(db: Session, user: User, workspace: Workspace, plan: Plan, cycle: str,
+                   success_url: str, cancel_url: str) -> str:
+    sc = client()
+    price = price_id(sc, plan, cycle)
+    row = _subscription_row(db, workspace.id)
+    if row.provider_subscription_id and row.status in LIVE:
+        return change_plan(sc, db, workspace, row, price, success_url)
+    customer = ensure_customer(sc, db, user, workspace)
+    meta = {"workspace_id": str(workspace.id), "plan": plan.id, "cycle": cycle}
+    session = sc.v1.checkout.sessions.create({
+        "mode": "subscription",
+        "customer": customer,
+        "client_reference_id": str(workspace.id),
+        "line_items": [{"price": price, "quantity": 1}],
+        "metadata": meta,
+        "subscription_data": {"metadata": meta},
+        "allow_promotion_codes": True,
+        "billing_address_collection": "auto",
+        "customer_update": {"address": "auto", "name": "auto"},
+        # 3D Secure: Checkout asks the bank whenever it wants it (SCA, Radar rules), nothing to force here.
+        "success_url": success_url + "&session_id={CHECKOUT_SESSION_ID}",
+        "cancel_url": cancel_url,
+    })
+    return session.url
+
+
+def change_plan(sc: stripe.StripeClient, db: Session, workspace: Workspace, row: Subscription, price: str,
+                success_url: str) -> str:
+    """Move a live subscription to a new price, prorated. The change only sticks once paid; if the bank
+    wants 3D Secure, send the user to the invoice page to confirm it."""
+    current = sc.v1.subscriptions.retrieve(row.provider_subscription_id)
+    item = _get(current, "items")["data"][0]
+    updated = sc.v1.subscriptions.update(row.provider_subscription_id, {
+        "items": [{"id": item["id"], "price": price}],
+        "proration_behavior": "always_invoice",
+        "payment_behavior": "pending_if_incomplete",
+        "expand": ["latest_invoice"],
+    })
+    invoice = _get(updated, "latest_invoice")
+    if _get(updated, "pending_update") and _get(invoice, "status") == "open":
+        # Not paid yet: the bank wants 3D Secure, or the card was declined. Stripe's hosted invoice page
+        # handles both (confirm, or pay with another card); the plan switches when that payment succeeds.
+        hosted = _get(invoice, "hosted_invoice_url")
+        if hosted:
+            return hosted
+        raise HTTPException(402, {"code": "payment_needs_action",
+                                  "message": "The upgrade payment needs your attention. Check your email."})
+    sync_subscription(db, workspace.id, updated)
+    return success_url
+
+
+def portal_url(db: Session, workspace: Workspace, return_url: str) -> str:
+    row = db.scalar(select(Subscription).where(Subscription.workspace_id == workspace.id))
+    if not row or not row.provider_customer_id:
+        raise HTTPException(404, {"code": "no_billing_account", "message": "There is no billing account yet."})
+    try:
+        session = client().v1.billing_portal.sessions.create({"customer": row.provider_customer_id, "return_url": return_url})
+    except stripe.InvalidRequestError as exc:
+        log.error("stripe portal failed: %s", exc)
+        raise HTTPException(503, {"code": "portal_unavailable",
+                                  "message": "Billing management is unavailable right now. Please try again soon."}) from exc
+    return session.url
+
+
+def confirm_checkout(db: Session, workspace: Workspace, session_id: str) -> Subscription | None:
+    """Apply a finished Checkout right away, without waiting for the webhook."""
+    sc = client()
+    session = sc.v1.checkout.sessions.retrieve(session_id, {"expand": ["subscription"]})
+    if _get(session, "client_reference_id") != str(workspace.id):
+        raise HTTPException(404, "Checkout session not found")
+    stripe_sub = _get(session, "subscription")
+    if not stripe_sub or _get(session, "status") != "complete":
+        return None
+    if isinstance(stripe_sub, str):
+        stripe_sub = sc.v1.subscriptions.retrieve(stripe_sub)
+    return sync_subscription(db, workspace.id, stripe_sub)
+
+
+# Webhooks
+
+HANDLED = {
+    "checkout.session.completed",
+    "checkout.session.async_payment_succeeded",
+    "checkout.session.async_payment_failed",
+    "customer.subscription.created",
+    "customer.subscription.updated",
+    "customer.subscription.deleted",
+    "customer.subscription.paused",
+    "customer.subscription.resumed",
+    "invoice.paid",
+    "invoice.payment_failed",
+    "invoice.payment_action_required",
+    "charge.dispute.created",
+}
+
+
+def parse_event(payload: bytes, signature: str | None):
+    if not settings.stripe_webhook_secret:
+        raise HTTPException(503, "STRIPE_WEBHOOK_SECRET is not set")
+    try:
+        return stripe.Webhook.construct_event(payload, signature or "", settings.stripe_webhook_secret)
+    except (ValueError, stripe.SignatureVerificationError) as exc:
+        raise HTTPException(400, "Invalid Stripe signature") from exc
+
+
+def _first_time(db: Session, event) -> bool:
+    """Record the event id; False when this delivery was already handled (Stripe retries)."""
+    db.add(BillingEvent(id=event["id"], type=event["type"], created_at=datetime.now(UTC)))
+    try:
+        db.commit()
+        return True
+    except IntegrityError:
+        db.rollback()
+        return False
+
+
+def _owner_email(db: Session, workspace_id: uuid.UUID | None) -> str | None:
+    if not workspace_id:
+        return None
+    ws = db.get(Workspace, workspace_id)
+    owner = db.get(User, ws.owner_id) if ws else None
+    return owner.email if owner else None
+
+
+def handle_event(db: Session, event) -> str:
+    from app.services.email import email_service
+
+    kind = event["type"]
+    if kind not in HANDLED:
+        return "ignored"
+    first = _first_time(db, event)
+    obj = event["data"]["object"]
+    sc = client()
+
+    if kind.startswith("checkout.session."):
+        if _get(obj, "mode") != "subscription" or not _get(obj, "subscription"):
+            return "skipped"
+        ws = _get(obj, "client_reference_id") or _get(_get(obj, "metadata", {}), "workspace_id")
+        if not ws:
+            return "no workspace"
+        sync_subscription(db, uuid.UUID(ws), sc.v1.subscriptions.retrieve(_get(obj, "subscription")))
+        return "synced"
+
+    if kind.startswith("customer.subscription."):
+        ws = _workspace_for(db, obj)
+        if not ws:
+            log.warning("stripe %s for unknown subscription %s", kind, _get(obj, "id"))
+            return "unknown"
+        # Re-read: the payload can be older than the current state when deliveries arrive out of order.
+        try:
+            fresh = sc.v1.subscriptions.retrieve(_get(obj, "id"))
+        except stripe.InvalidRequestError:
+            fresh = obj
+        sync_subscription(db, ws, fresh)
+        return "synced"
+
+    if kind.startswith("invoice."):
+        sub_id = _get(obj, "subscription") or _get(_get(_get(obj, "parent", {}), "subscription_details", {}), "subscription")
+        ws = _workspace_for(db, {"id": sub_id} if sub_id else None, customer_id=_get(obj, "customer"))
+        if ws and sub_id:
+            sync_subscription(db, ws, sc.v1.subscriptions.retrieve(sub_id))
+        if first and kind in {"invoice.payment_action_required", "invoice.payment_failed"}:
+            # The first invoice of a Checkout is handled on the Checkout page itself.
+            if _get(obj, "billing_reason") != "subscription_create":
+                to = _get(obj, "customer_email") or _owner_email(db, ws)
+                url = _get(obj, "hosted_invoice_url") or f"{settings.frontend_url.rstrip('/')}/app/settings"
+                if to:
+                    email_service.send_payment_action(to, "confirm" if kind.endswith("action_required") else "failed", url)
+        return "synced" if ws else "unknown"
+
+    if kind == "charge.dispute.created" and first:
+        email_service.send_alert(
+            "Stripe dispute opened",
+            f"Dispute {_get(obj, 'id')} for {(_get(obj, 'amount', 0) or 0) / 100:.2f} "
+            f"{str(_get(obj, 'currency', '')).upper()}, reason: {_get(obj, 'reason')}. "
+            "Respond in the Stripe dashboard before the deadline.",
+        )
+        return "alerted"
+    return "ok"

frontend/index.html

@@ -6,6 +6,23 @@
     <meta name="theme-color" content="#000000" />
     <meta name="description" content="Notestack turns any blog, newsletter, site or markdown files into a grounded research notebook, audio overviews, videos and a launch kit, all in your own voice." />
     <link rel="icon" href="/logo.svg" />
+    <!-- Link previews (X, LinkedIn, Bluesky, Threads, Facebook, Slack, Discord, iMessage). %SITE_URL% is filled in at build. -->
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="Notestack" />
+    <meta property="og:title" content="Notestack: your knowledge, in orbit" />
+    <meta property="og:description" content="Notestack turns any blog, newsletter, site or markdown files into a grounded research notebook, audio overviews, videos and a launch kit, all in your own voice." />
+    <meta property="og:url" content="%SITE_URL%/" />
+    <meta property="og:image" content="%SITE_URL%/og-image.jpg" />
+    <meta property="og:image:secure_url" content="%SITE_URL%/og-image.jpg" />
+    <meta property="og:image:type" content="image/jpeg" />
+    <meta property="og:image:width" content="1280" />
+    <meta property="og:image:height" content="720" />
+    <meta property="og:image:alt" content="Notestack: your knowledge, in orbit" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="Notestack: your knowledge, in orbit" />
+    <meta name="twitter:description" content="Notestack turns any blog, newsletter, site or markdown files into a grounded research notebook, audio overviews, videos and a launch kit, all in your own voice." />
+    <meta name="twitter:image" content="%SITE_URL%/og-image.jpg" />
+    <meta name="twitter:image:alt" content="Notestack: your knowledge, in orbit" />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Space+Grotesk:wght@500;600;700&display=swap" rel="stylesheet" />

frontend/vite.config.ts

@@ -6,7 +6,12 @@ import { sitemapPlugin } from "./seo/sitemap";
 const SITE_URL = process.env.SITE_URL ?? "https://notestack.ai";
 
 export default defineConfig({
-  plugins: [react(), sitemapPlugin(SITE_URL)],
+  plugins: [
+    react(),
+    sitemapPlugin(SITE_URL),
+    // Link preview tags need absolute URLs: fill %SITE_URL% in index.html.
+    { name: "site-url", transformIndexHtml: (html) => html.replaceAll("%SITE_URL%", SITE_URL.replace(/\/$/, "")) },
+  ],
   // Read the shared root .env. Only these prefixes reach the browser; the Google client ID is
   // public by design, so it can be shared with the backend under its plain name.
   envDir: "..",