phase D milestones 1+2: referral system + paid-access gate

Lays the billing-prep spine before Paddle lands in D.3.

D.1 — referrals
- users.referral_code: unique 8-char URL-safe code (alphabet excludes the
  ambiguous 0/O/1/I/L). Generated lazily on first /settings hit so existing
  accounts pick one up without a backfill migration.
- users.referred_by_user_id + new referrals audit table (referrer,
  referred, created_at, converted_at, credited_at). converted_at /
  credited_at stay null until D.3 fills them via the Paddle webhook.
- POST /login accepts ?ref=<code>; the code rides on the signed
  pending-verify cookie so it survives the GET → POST → /verify hop.
- /settings page: email, tier badge, referral code chip + invite link
  with one-click copy, pending/converted/active-credits stats grid.
  Settings nav link added to the top bar.

Reward shape: when the referred user makes their first paid Paddle
subscription, both they and the referrer get 50% off for 3 months.
(D.3 wires the actual credit application via the Paddle webhook.)

D.2 — paid-access gate
- users.credit_until: timestamp until which a free-tier account has
  paid-tier access. Null = no credit. Populated by admin CLI now and the
  D.3 webhook later.
- app.services.access exposes paid_status(user) → PaidStatus dataclass
  (active / source / expires_at / days_remaining), is_paid_active() with
  admin-bearer-token bypass, and a require_paid FastAPI dependency that
  raises 402 Payment Required for free-tier callers.
- POST /api/analyze (portfolio AI commentary) gated behind require_paid.
- Settings page surfaces credit window when active ("free · credit · N
  day(s) remaining (expires YYYY-MM-DD)") and the upgrade hint when not.
- Admin CLI: python -m app.cli {grant-credit,revoke-credit,show-status}.
  grant-credit is idempotent — extends from max(now, current expiry) so
  re-running the command never erodes an existing grant.

Migrations 0013 (referrals) and 0014 (credit_until). Tests cover the
paid-status truth table, code generation + normalisation, CLI argument
parsing, and the pending-cookie ref roundtrip (29 new tests).

app/routers/auth.py

@@ -36,7 +36,7 @@ from app.config import get_settings
 from app.db import get_session, utcnow
 from app.logging import get_logger
 from app.services.auth_service import AuthError, get_or_create_user, get_user
-from app.services import otp_service
+from app.services import otp_service, referral_service
 from app.services.email_service import EmailSendError, send_otp
 from app.templates_env import templates
 
@@ -67,10 +67,15 @@ def _set_session_cookie(response: RedirectResponse, user_id: int) -> None:
     )
 
 
-def _set_pending_cookie(response: RedirectResponse, email: str, user_id: int) -> None:
+def _set_pending_cookie(
+    response: RedirectResponse,
+    email: str,
+    user_id: int,
+    ref: str | None = None,
+) -> None:
     response.set_cookie(
         key=PENDING_COOKIE_NAME,
-        value=sign_pending(email, user_id),
+        value=sign_pending(email, user_id, ref=ref),
         max_age=PENDING_TTL_SECONDS,
         httponly=True,
         samesite="lax",
@@ -101,10 +106,29 @@ async def _issue_and_send_otp(session: AsyncSession, email: str) -> bool:
 
 
 @router.get("/login", response_class=HTMLResponse)
-async def login_page(request: Request, next: str | None = None, error: str | None = None):
+async def login_page(
+    request: Request,
+    next: str | None = None,
+    error: str | None = None,
+    ref: str | None = None,
+    session: AsyncSession = Depends(get_session),
+):
+    # If a valid referral code is supplied, surface a small "invited"
+    # banner. We resolve it server-side so the banner can show the
+    # referrer's actual greeting (and a bad code silently degrades).
+    ref_norm = referral_service.normalise_code(ref) if ref else None
+    referrer = (
+        await referral_service.lookup_referrer(session, ref_norm)
+        if ref_norm else None
+    )
     return templates.TemplateResponse(
         request, "login.html",
-        {"next_path": _safe_next(next), "error": error},
+        {
+            "next_path": _safe_next(next),
+            "error": error,
+            "ref": ref_norm if referrer else None,
+            "referrer_present": referrer is not None,
+        },
     )
 
 
@@ -113,9 +137,24 @@ async def login_submit(
     request: Request,
     email: str = Form(...),
     next: str | None = Form(default=None),
+    ref: str | None = Form(default=None),
     session: AsyncSession = Depends(get_session),
 ):
     s = get_settings()
+    # Look up the referrer up front so a bad code doesn't pollute the
+    # rest of the flow. Self-referral protection lives in
+    # referral_service.link_new_user.
+    ref_norm = referral_service.normalise_code(ref) if ref else None
+    referrer = (
+        await referral_service.lookup_referrer(session, ref_norm)
+        if ref_norm else None
+    )
+
+    # Track whether THIS request creates the user row (i.e. a referral
+    # capture window). Cleanest way: probe for existence first.
+    from app.services.auth_service import get_user_by_email
+    was_new = (await get_user_by_email(session, email)) is None
+
     try:
         user = await get_or_create_user(
             session, email, create_if_missing=s.CASSANDRA_SIGNUP_ENABLED,
@@ -123,10 +162,19 @@ async def login_submit(
     except AuthError as e:
         return templates.TemplateResponse(
             request, "login.html",
-            {"next_path": _safe_next(next), "error": str(e), "email": email},
+            {"next_path": _safe_next(next), "error": str(e), "email": email,
+             "ref": ref_norm if referrer else None,
+             "referrer_present": referrer is not None},
             status_code=400,
         )
 
+    # First-time signup with a valid referrer → persist the linkage now.
+    # We do this BEFORE OTP-verify because the row is already created;
+    # if the user abandons OTP we'll have an orphan link but that's
+    # harmless audit data.
+    if was_new and referrer is not None:
+        await referral_service.link_new_user(session, user, referrer)
+
     # Issue OTP only if cooldown allows; if a fresh one was sent in the
     # last 60s we just reuse the existing one (silently) to avoid
     # spamming the user's inbox on a refreshed form submit.
@@ -135,7 +183,13 @@ async def login_submit(
         await _issue_and_send_otp(session, user.email)
 
     resp = RedirectResponse(url="/verify", status_code=303)
-    _set_pending_cookie(resp, user.email, user.id)
+    # Stash the referral code on the pending cookie too — handy for
+    # showing the "invited" badge on the /verify page so the friend
+    # knows the discount is still tracking.
+    _set_pending_cookie(
+        resp, user.email, user.id,
+        ref=ref_norm if referrer is not None else None,
+    )
     return resp
 
 

app/routers/pages.py

@@ -8,10 +8,12 @@ from fastapi.responses import HTMLResponse
 from sqlalchemy import desc, func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.auth import require_token
+from app.auth import CurrentUser, require_auth, require_token
 from app.config import get_settings, load_groups
 from app.db import get_session
-from app.models import StrategicLog
+from app.models import Referral, StrategicLog, User
+from app.services.access import paid_status
+from app.services.referral_service import assign_code_if_missing
 from app.templates_env import templates
 
 router = APIRouter(dependencies=[Depends(require_token)])
@@ -84,3 +86,51 @@ async def log_page_day(
 ):
     target = await _resolve_log_date(session, day)
     return templates.TemplateResponse(request, "log.html", _log_page_context(target))
+
+
+@router.get("/settings", response_class=HTMLResponse)
+async def settings_page(
+    request: Request,
+    session: AsyncSession = Depends(get_session),
+    principal: CurrentUser = Depends(require_auth),
+):
+    """Per-user settings. Currently shows email, tier, and the referral
+    block (own code + invite link + counts of pending/converted
+    referrals). The Credit / Paddle pieces land in D.3."""
+    user = principal.user
+    if user is None:
+        # Bearer-token admin path — no per-user settings to show.
+        return templates.TemplateResponse(
+            request, "settings.html",
+            {"user": None, "invite_url": None,
+             "pending_count": 0, "converted_count": 0},
+        )
+
+    # Lazily assign a referral code on first visit.
+    user = await assign_code_if_missing(session, user)
+
+    # Stats: how many people have signed up with their code so far, and
+    # how many of those converted (paid). D.3 will fill `converted_at`.
+    pending_count = (await session.execute(
+        select(func.count(Referral.id))
+        .where(Referral.referrer_user_id == user.id)
+        .where(Referral.converted_at.is_(None))
+    )).scalar() or 0
+    converted_count = (await session.execute(
+        select(func.count(Referral.id))
+        .where(Referral.referrer_user_id == user.id)
+        .where(Referral.converted_at.is_not(None))
+    )).scalar() or 0
+
+    invite_url = str(request.url_for("login_page")) + f"?ref={user.referral_code}"
+
+    return templates.TemplateResponse(
+        request, "settings.html",
+        {
+            "user": user,
+            "invite_url": invite_url,
+            "pending_count": int(pending_count),
+            "converted_count": int(converted_count),
+            "paid": paid_status(user),
+        },
+    )

app/routers/universe.py

@@ -42,6 +42,7 @@ from app.db import get_session, utcnow
 from app.logging import get_logger
 from app.models import Quote, QuoteDaily
 from app.services import fx, portfolio_analysis, ticker_universe
+from app.services.access import require_paid
 from app.services.csv_import import CSVImportError, parse_t212_csv
 from app.services.instrument_map import resolve_slice
 from app.services.market import fetch as market_fetch
@@ -310,7 +311,7 @@ async def parse_portfolio(
 # ---------------------------------------------------------------------------
 
 
-@router.post("/analyze")
+@router.post("/analyze", dependencies=[Depends(require_paid)])
 async def analyze_portfolio(
     request: Request,
     session: AsyncSession = Depends(get_session),
@@ -318,7 +319,10 @@ async def analyze_portfolio(
     """Generate AI commentary for the supplied pie. The pie is held in
     memory only for the duration of the LLM call; nothing about holdings
     is persisted. The ai_calls ledger row records tokens + cost, never
-    holdings."""
+    holdings.
+
+    Gated behind ``require_paid`` (Phase D.2): free-tier users get 402.
+    Admin bearer-token bypasses the gate for testing."""
     # Read JSON body manually so we can enforce a hard size cap. FastAPI's
     # default body limit is generous; we want tighter control here.
     body = await request.body()