feat: PocketVeto v1.0.0 — initial public release

Self-hosted US Congress monitoring platform with AI policy briefs,
bill/member/topic follows, ntfy + RSS + email notifications,
alignment scoring, collections, and draft-letter generator.

Authored by: Jack Levy

frontend/components/shared/AuthGuard.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { useAuthStore } from "@/stores/authStore";
+import { Sidebar } from "./Sidebar";
+import { MobileHeader } from "./MobileHeader";
+
+const NO_SHELL_PATHS = ["/login", "/register", "/share"];
+const AUTH_REQUIRED = ["/following", "/notifications", "/collections"];
+
+export function AuthGuard({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const token = useAuthStore((s) => s.token);
+  // Zustand persist hydrates asynchronously — wait for it before rendering
+  const [hydrated, setHydrated] = useState(false);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  useEffect(() => {
+    setHydrated(true);
+  }, []);
+
+  useEffect(() => {
+    if (!hydrated) return;
+    const needsAuth = AUTH_REQUIRED.some((p) => pathname.startsWith(p));
+    if (!token && needsAuth) {
+      router.replace("/login");
+    }
+  }, [hydrated, token, pathname, router]);
+
+  if (!hydrated) return null;
+
+  // Login/register/share pages render without the app shell
+  if (NO_SHELL_PATHS.some((p) => pathname.startsWith(p))) {
+    return <>{children}</>;
+  }
+
+  // Auth-required pages: blank while redirecting
+  const needsAuth = AUTH_REQUIRED.some((p) => pathname.startsWith(p));
+  if (!token && needsAuth) return null;
+
+  // Authenticated or guest browsing: render the full app shell
+  return (
+    <div className="flex h-screen bg-background">
+      {/* Desktop sidebar — hidden on mobile */}
+      <div className="hidden md:flex">
+        <Sidebar />
+      </div>
+
+      {/* Mobile slide-in drawer */}
+      {drawerOpen && (
+        <div className="fixed inset-0 z-50 md:hidden">
+          <div className="absolute inset-0 bg-black/50" onClick={() => setDrawerOpen(false)} />
+          <div className="absolute left-0 top-0 bottom-0">
+            <Sidebar onClose={() => setDrawerOpen(false)} />
+          </div>
+        </div>
+      )}
+
+      {/* Content column */}
+      <div className="flex-1 flex flex-col min-h-0">
+        <MobileHeader onMenuClick={() => setDrawerOpen(true)} />
+        <main className="flex-1 overflow-auto">
+          <div className="container mx-auto px-4 md:px-6 py-6 max-w-7xl">
+            {children}
+          </div>
+        </main>
+      </div>
+    </div>
+  );
+}

frontend/components/shared/AuthModal.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import Link from "next/link";
+import * as Dialog from "@radix-ui/react-dialog";
+import { X } from "lucide-react";
+
+interface AuthModalProps {
+  open: boolean;
+  onClose: () => void;
+}
+
+export function AuthModal({ open, onClose }: AuthModalProps) {
+  return (
+    <Dialog.Root open={open} onOpenChange={onClose}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0" />
+        <Dialog.Content className="fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2 w-full max-w-sm bg-card border border-border rounded-lg shadow-lg p-6 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95">
+          <Dialog.Title className="text-base font-semibold">
+            Sign in to follow bills
+          </Dialog.Title>
+          <Dialog.Description className="mt-2 text-sm text-muted-foreground">
+            Create a free account to follow bills, set Pocket Veto or Pocket Boost modes, and receive alerts.
+          </Dialog.Description>
+          <div className="flex gap-3 mt-4">
+            <Link href="/register" onClick={onClose} className="flex-1 px-4 py-2 text-sm font-medium text-center rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors">
+              Create account
+            </Link>
+            <Link href="/login" onClick={onClose} className="flex-1 px-4 py-2 text-sm font-medium text-center rounded-md border border-border text-foreground hover:bg-accent transition-colors">
+              Sign in
+            </Link>
+          </div>
+          <Dialog.Close className="absolute right-4 top-4 p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-accent transition-colors">
+            <X className="w-4 h-4" />
+          </Dialog.Close>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

frontend/components/shared/BillCard.tsx

@@ -0,0 +1,103 @@
+import Link from "next/link";
+import { TrendingUp, Calendar, User, FileText, FileClock, FileX, Tag } from "lucide-react";
+import { Bill } from "@/lib/types";
+import { billLabel, chamberBadgeColor, cn, formatDate, partyBadgeColor, trendColor } from "@/lib/utils";
+import { FollowButton } from "./FollowButton";
+import { TOPIC_LABEL, TOPIC_TAGS } from "@/lib/topics";
+
+interface BillCardProps {
+  bill: Bill;
+  compact?: boolean;
+}
+
+export function BillCard({ bill, compact = false }: BillCardProps) {
+  const label = billLabel(bill.bill_type, bill.bill_number);
+  const score = bill.latest_trend?.composite_score;
+  const tags = (bill.latest_brief?.topic_tags || []).filter((t) => TOPIC_TAGS.has(t)).slice(0, 3);
+
+  return (
+    <div className="bg-card border border-border rounded-lg p-4 hover:border-primary/30 transition-colors">
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-2 mb-1.5 flex-wrap">
+            <span className="text-xs font-mono font-semibold text-muted-foreground bg-muted px-1.5 py-0.5 rounded">
+              {label}
+            </span>
+            {bill.chamber && (
+              <span className={cn("text-xs px-1.5 py-0.5 rounded font-medium", chamberBadgeColor(bill.chamber))}>
+                {bill.chamber}
+              </span>
+            )}
+            {tags.map((tag) => (
+              <Link
+                key={tag}
+                href={`/bills?topic=${tag}`}
+                onClick={(e) => e.stopPropagation()}
+                className="inline-flex items-center gap-0.5 text-xs px-1.5 py-0.5 rounded-full bg-accent text-accent-foreground hover:bg-accent/70 transition-colors"
+              >
+                <Tag className="w-2.5 h-2.5" />
+                {TOPIC_LABEL[tag] ?? tag}
+              </Link>
+            ))}
+          </div>
+
+          <Link href={`/bills/${bill.bill_id}`}>
+            <h3 className="text-sm font-medium leading-snug hover:text-primary transition-colors line-clamp-2">
+              {bill.short_title || bill.title || "Untitled Bill"}
+            </h3>
+          </Link>
+
+          {!compact && bill.sponsor && (
+            <div className="flex items-center gap-1.5 mt-1.5 text-xs text-muted-foreground">
+              <User className="w-3 h-3" />
+              <Link href={`/members/${bill.sponsor.bioguide_id}`} className="hover:text-foreground transition-colors">
+                {bill.sponsor.name}
+              </Link>
+              {bill.sponsor.party && (
+                <span className={cn("px-1 py-0.5 rounded text-xs font-medium", partyBadgeColor(bill.sponsor.party))}>
+                  {bill.sponsor.party}
+                </span>
+              )}
+              {bill.sponsor.state && (
+                <span>{bill.sponsor.state}</span>
+              )}
+            </div>
+          )}
+        </div>
+
+        <div className="flex flex-col items-end gap-2 shrink-0">
+          <FollowButton type="bill" value={bill.bill_id} supportsModes />
+          {score !== undefined && score > 0 && (
+            <div className={cn("flex items-center gap-1 text-xs font-medium", trendColor(score))}>
+              <TrendingUp className="w-3 h-3" />
+              {Math.round(score)}
+            </div>
+          )}
+          {bill.latest_brief ? (
+            <div className="flex items-center gap-1 text-xs text-emerald-600 dark:text-emerald-400" title="Analysis available">
+              <FileText className="w-3 h-3" />
+              <span>Brief</span>
+            </div>
+          ) : bill.has_document ? (
+            <div className="flex items-center gap-1 text-xs text-amber-500" title="Text retrieved, analysis pending">
+              <FileClock className="w-3 h-3" />
+              <span>Pending</span>
+            </div>
+          ) : (
+            <div className="flex items-center gap-1 text-xs text-muted-foreground/50" title="No bill text published">
+              <FileX className="w-3 h-3" />
+              <span>No text</span>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {!compact && bill.latest_action_text && (
+        <p className="mt-2 text-xs text-muted-foreground line-clamp-2 border-t border-border pt-2">
+          <Calendar className="w-3 h-3 inline mr-1" />
+          {formatDate(bill.latest_action_date)} — {bill.latest_action_text}
+        </p>
+      )}
+    </div>
+  );
+}

frontend/components/shared/FollowButton.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+import { useRef, useEffect, useState } from "react";
+import { Heart, Shield, Zap, ChevronDown } from "lucide-react";
+import { useAddFollow, useIsFollowing, useRemoveFollow, useUpdateFollowMode } from "@/lib/hooks/useFollows";
+import { useAuthStore } from "@/stores/authStore";
+import { AuthModal } from "./AuthModal";
+import { cn } from "@/lib/utils";
+
+const MODES = {
+  neutral: {
+    label: "Following",
+    icon: Heart,
+    color: "bg-red-100 text-red-700 hover:bg-red-200 dark:bg-red-900/30 dark:text-red-400",
+  },
+  pocket_veto: {
+    label: "Pocket Veto",
+    icon: Shield,
+    color: "bg-amber-100 text-amber-700 hover:bg-amber-200 dark:bg-amber-900/30 dark:text-amber-400",
+  },
+  pocket_boost: {
+    label: "Pocket Boost",
+    icon: Zap,
+    color: "bg-green-100 text-green-700 hover:bg-green-200 dark:bg-green-900/30 dark:text-green-400",
+  },
+} as const;
+
+type FollowMode = keyof typeof MODES;
+
+interface FollowButtonProps {
+  type: "bill" | "member" | "topic";
+  value: string;
+  label?: string;
+  supportsModes?: boolean;
+}
+
+export function FollowButton({ type, value, label, supportsModes = false }: FollowButtonProps) {
+  const existing = useIsFollowing(type, value);
+  const add = useAddFollow();
+  const remove = useRemoveFollow();
+  const updateMode = useUpdateFollowMode();
+  const token = useAuthStore((s) => s.token);
+  const [open, setOpen] = useState(false);
+  const [showAuthModal, setShowAuthModal] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  function requireAuth(action: () => void) {
+    if (!token) { setShowAuthModal(true); return; }
+    action();
+  }
+
+  const isFollowing = !!existing;
+  const currentMode: FollowMode = (existing?.follow_mode as FollowMode) ?? "neutral";
+  const isPending = add.isPending || remove.isPending || updateMode.isPending;
+
+  // Close dropdown on outside click
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [open]);
+
+  // Simple toggle for non-bill follows
+  if (!supportsModes) {
+    const handleClick = () => {
+      requireAuth(() => {
+        if (isFollowing && existing) {
+          remove.mutate(existing.id);
+        } else {
+          add.mutate({ type, value });
+        }
+      });
+    };
+    return (
+      <>
+        <button
+          onClick={handleClick}
+          disabled={isPending}
+          className={cn(
+            "flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm font-medium transition-colors",
+            isFollowing
+              ? "bg-red-100 text-red-700 hover:bg-red-200 dark:bg-red-900/30 dark:text-red-400"
+              : "bg-muted text-muted-foreground hover:bg-accent hover:text-foreground"
+          )}
+        >
+          <Heart className={cn("w-3.5 h-3.5", isFollowing && "fill-current")} />
+          {isFollowing ? "Unfollow" : label || "Follow"}
+        </button>
+        <AuthModal open={showAuthModal} onClose={() => setShowAuthModal(false)} />
+      </>
+    );
+  }
+
+  // Mode-aware follow button for bills
+  if (!isFollowing) {
+    return (
+      <>
+        <button
+          onClick={() => requireAuth(() => add.mutate({ type, value }))}
+          disabled={isPending}
+          className="flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm font-medium transition-colors bg-muted text-muted-foreground hover:bg-accent hover:text-foreground"
+        >
+          <Heart className="w-3.5 h-3.5" />
+          {label || "Follow"}
+        </button>
+        <AuthModal open={showAuthModal} onClose={() => setShowAuthModal(false)} />
+      </>
+    );
+  }
+
+  const { label: modeLabel, icon: ModeIcon, color } = MODES[currentMode];
+  const otherModes = (Object.keys(MODES) as FollowMode[]).filter((m) => m !== currentMode);
+
+  const switchMode = (mode: FollowMode) => {
+    requireAuth(() => {
+      if (existing) updateMode.mutate({ id: existing.id, mode });
+      setOpen(false);
+    });
+  };
+
+  const handleUnfollow = () => {
+    requireAuth(() => {
+      if (existing) remove.mutate(existing.id);
+      setOpen(false);
+    });
+  };
+
+  const modeDescriptions: Record<FollowMode, string> = {
+    neutral: "Alert me on all material changes",
+    pocket_veto: "Alert me only if this bill advances toward passage",
+    pocket_boost: "Alert me on all changes + remind me to contact my rep",
+  };
+
+  return (
+    <>
+      <div className="relative" ref={dropdownRef}>
+        <button
+          onClick={() => setOpen((v) => !v)}
+          disabled={isPending}
+          className={cn(
+            "flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm font-medium transition-colors",
+            color
+          )}
+        >
+          <ModeIcon className={cn("w-3.5 h-3.5", currentMode === "neutral" && "fill-current")} />
+          {modeLabel}
+          <ChevronDown className="w-3 h-3 ml-0.5 opacity-70" />
+        </button>
+
+        {open && (
+          <div className="absolute right-0 mt-1 w-64 bg-card border border-border rounded-md shadow-lg z-50 py-1">
+            {otherModes.map((mode) => {
+              const { label: optLabel, icon: OptIcon } = MODES[mode];
+              return (
+                <button
+                  key={mode}
+                  onClick={() => switchMode(mode)}
+                  title={modeDescriptions[mode]}
+                  className="w-full text-left px-3 py-2 text-sm bg-card hover:bg-accent text-card-foreground transition-colors flex flex-col gap-0.5"
+                >
+                  <span className="flex items-center gap-1.5 font-medium">
+                    <OptIcon className="w-3.5 h-3.5" />
+                    Switch to {optLabel}
+                  </span>
+                  <span className="text-xs text-muted-foreground pl-5">{modeDescriptions[mode]}</span>
+                </button>
+              );
+            })}
+            <div className="border-t border-border mt-1 pt-1">
+              <button
+                onClick={handleUnfollow}
+                className="w-full text-left px-3 py-2 text-sm bg-card hover:bg-accent text-destructive transition-colors"
+              >
+                Unfollow
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+      <AuthModal open={showAuthModal} onClose={() => setShowAuthModal(false)} />
+    </>
+  );
+}

frontend/components/shared/HelpTip.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import { HelpCircle } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface HelpTipProps {
+  content: string;
+  className?: string;
+}
+
+export function HelpTip({ content, className }: HelpTipProps) {
+  const [visible, setVisible] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!visible) return;
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setVisible(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [visible]);
+
+  return (
+    <div className={cn("relative inline-flex items-center", className)} ref={ref}>
+      <button
+        type="button"
+        onMouseEnter={() => setVisible(true)}
+        onMouseLeave={() => setVisible(false)}
+        onClick={() => setVisible((v) => !v)}
+        aria-label="Help"
+        className="text-muted-foreground hover:text-foreground transition-colors"
+      >
+        <HelpCircle className="w-3.5 h-3.5" />
+      </button>
+      {visible && (
+        <div className="absolute left-5 top-0 z-50 w-64 bg-popover border border-border rounded-md shadow-lg p-3 text-xs text-muted-foreground leading-relaxed">
+          {content}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/components/shared/MobileHeader.tsx

@@ -0,0 +1,16 @@
+"use client";
+import { Menu, Landmark } from "lucide-react";
+
+export function MobileHeader({ onMenuClick }: { onMenuClick: () => void }) {
+  return (
+    <header className="md:hidden flex items-center justify-between px-4 py-3 border-b border-border bg-card shrink-0">
+      <button onClick={onMenuClick} className="p-2 rounded-md hover:bg-accent transition-colors" aria-label="Open menu">
+        <Menu className="w-5 h-5" />
+      </button>
+      <div className="flex items-center gap-2">
+        <Landmark className="w-5 h-5 text-primary" />
+        <span className="font-semibold text-sm">PocketVeto</span>
+      </div>
+    </header>
+  );
+}

frontend/components/shared/Sidebar.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import Link from "next/link";
+import { usePathname, useRouter } from "next/navigation";
+import {
+  Bookmark,
+  ChevronLeft,
+  ChevronRight,
+  HelpCircle,
+  LayoutDashboard,
+  FileText,
+  Users,
+  Tags,
+  Heart,
+  Bell,
+  Settings,
+  BarChart2,
+  Landmark,
+  LogOut,
+  X,
+} from "lucide-react";
+import { useQueryClient } from "@tanstack/react-query";
+import { cn } from "@/lib/utils";
+import { ThemeToggle } from "./ThemeToggle";
+import { useAuthStore } from "@/stores/authStore";
+
+const NAV = [
+  { href: "/", label: "Dashboard", icon: LayoutDashboard, adminOnly: false, requiresAuth: false },
+  { href: "/bills", label: "Bills", icon: FileText, adminOnly: false, requiresAuth: false },
+  { href: "/members", label: "Members", icon: Users, adminOnly: false, requiresAuth: false },
+  { href: "/topics", label: "Topics", icon: Tags, adminOnly: false, requiresAuth: false },
+  { href: "/following", label: "Following", icon: Heart, adminOnly: false, requiresAuth: true },
+  { href: "/alignment", label: "Alignment", icon: BarChart2, adminOnly: false, requiresAuth: true },
+  { href: "/collections", label: "Collections", icon: Bookmark, adminOnly: false, requiresAuth: true },
+  { href: "/notifications", label: "Notifications", icon: Bell, adminOnly: false, requiresAuth: true },
+  { href: "/how-it-works", label: "How it works", icon: HelpCircle, adminOnly: false, requiresAuth: false },
+  { href: "/settings", label: "Admin", icon: Settings, adminOnly: true, requiresAuth: false },
+];
+
+export function Sidebar({ onClose }: { onClose?: () => void }) {
+  const pathname = usePathname();
+  const router = useRouter();
+  const qc = useQueryClient();
+  const user = useAuthStore((s) => s.user);
+  const token = useAuthStore((s) => s.token);
+  const logout = useAuthStore((s) => s.logout);
+  const [collapsed, setCollapsed] = useState(false);
+
+  // Mobile drawer always shows full sidebar
+  const isMobile = !!onClose;
+  const isCollapsed = collapsed && !isMobile;
+
+  useEffect(() => {
+    const saved = localStorage.getItem("sidebar-collapsed");
+    if (saved === "true") setCollapsed(true);
+  }, []);
+
+  function toggleCollapsed() {
+    setCollapsed((v) => {
+      localStorage.setItem("sidebar-collapsed", String(!v));
+      return !v;
+    });
+  }
+
+  function handleLogout() {
+    logout();
+    qc.clear();
+    router.replace("/login");
+  }
+
+  return (
+    <aside
+      className={cn(
+        "shrink-0 border-r border-border bg-card flex flex-col transition-all duration-200",
+        isCollapsed ? "w-14" : "w-56"
+      )}
+    >
+      {/* Header */}
+      <div
+        className={cn(
+          "h-14 border-b border-border flex items-center gap-2 px-4",
+          isCollapsed && "justify-center px-0"
+        )}
+      >
+        <Landmark className="w-5 h-5 text-primary shrink-0" />
+        {!isCollapsed && (
+          <>
+            <span className="font-semibold text-sm flex-1">PocketVeto</span>
+            {onClose && (
+              <button
+                onClick={onClose}
+                className="p-1 rounded-md hover:bg-accent transition-colors"
+                aria-label="Close menu"
+              >
+                <X className="w-4 h-4" />
+              </button>
+            )}
+          </>
+        )}
+      </div>
+
+      {/* Nav */}
+      <nav className="flex-1 p-2 space-y-0.5">
+        {NAV.filter(({ adminOnly, requiresAuth }) => {
+          if (adminOnly && !user?.is_admin) return false;
+          if (requiresAuth && !token) return false;
+          return true;
+        }).map(({ href, label, icon: Icon }) => {
+          const active = href === "/" ? pathname === "/" : pathname.startsWith(href);
+          return (
+            <Link
+              key={href}
+              href={href}
+              onClick={onClose}
+              title={isCollapsed ? label : undefined}
+              className={cn(
+                "flex items-center gap-3 px-3 py-2 rounded-md text-sm transition-colors",
+                isCollapsed && "justify-center px-0",
+                active
+                  ? "bg-primary text-primary-foreground"
+                  : "text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+              )}
+            >
+              <Icon className="w-4 h-4 shrink-0" />
+              {!isCollapsed && label}
+            </Link>
+          );
+        })}
+      </nav>
+
+      {/* Footer */}
+      <div className={cn("p-3 border-t border-border space-y-2", isCollapsed && "p-2")}>
+        {token ? (
+          user && (
+            <div className={cn("flex items-center justify-between", isCollapsed && "justify-center")}>
+              {!isCollapsed && (
+                <span className="text-xs text-muted-foreground truncate max-w-[120px]" title={user.email}>
+                  {user.email}
+                </span>
+              )}
+              <button
+                onClick={handleLogout}
+                className="p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-accent"
+                title="Sign out"
+              >
+                <LogOut className="w-3.5 h-3.5" />
+              </button>
+            </div>
+          )
+        ) : !isCollapsed ? (
+          <div className="flex flex-col gap-2">
+            <Link
+              href="/register"
+              onClick={onClose}
+              className="w-full px-3 py-1.5 text-sm font-medium text-center rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
+            >
+              Register
+            </Link>
+            <Link
+              href="/login"
+              onClick={onClose}
+              className="w-full px-3 py-1.5 text-sm font-medium text-center rounded-md border border-border text-foreground hover:bg-accent transition-colors"
+            >
+              Sign in
+            </Link>
+          </div>
+        ) : null}
+
+        <div className={cn("flex items-center justify-between", isCollapsed && "justify-center")}>
+          {!isCollapsed && <span className="text-xs text-muted-foreground">Theme</span>}
+          <ThemeToggle />
+        </div>
+
+        {/* Collapse toggle — desktop only */}
+        {!isMobile && (
+          <button
+            onClick={toggleCollapsed}
+            title={isCollapsed ? "Expand sidebar" : "Collapse sidebar"}
+            className="w-full flex items-center justify-center p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
+          >
+            {isCollapsed ? <ChevronRight className="w-4 h-4" /> : <ChevronLeft className="w-4 h-4" />}
+          </button>
+        )}
+      </div>
+    </aside>
+  );
+}

frontend/components/shared/ThemeToggle.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { Moon, Sun } from "lucide-react";
+import { useTheme } from "next-themes";
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <button
+      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+      className="p-1.5 rounded-md hover:bg-accent transition-colors text-muted-foreground hover:text-foreground"
+      aria-label="Toggle theme"
+    >
+      <Sun className="w-4 h-4 hidden dark:block" />
+      <Moon className="w-4 h-4 dark:hidden" />
+    </button>
+  );
+}

frontend/components/shared/WelcomeBanner.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { X, BookOpen, GitCompare, ShieldCheck } from "lucide-react";
+import Link from "next/link";
+import { useAuthStore } from "@/stores/authStore";
+
+const STORAGE_KEY = "pv_seen_welcome";
+
+export function WelcomeBanner() {
+  const token = useAuthStore((s) => s.token);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    if (!token && localStorage.getItem(STORAGE_KEY) !== "1") {
+      setVisible(true);
+    }
+  }, [token]);
+
+  const dismiss = () => {
+    localStorage.setItem(STORAGE_KEY, "1");
+    setVisible(false);
+  };
+
+  if (!visible) return null;
+
+  return (
+    <div className="relative bg-card border border-border rounded-lg p-5 pr-10">
+      <button
+        onClick={dismiss}
+        title="Dismiss"
+        className="absolute top-3 right-3 p-1 rounded text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
+      >
+        <X className="w-4 h-4" />
+      </button>
+
+      <h2 className="font-semibold text-base mb-3">Welcome to PocketVeto</h2>
+
+      <ul className="space-y-2 mb-4">
+        <li className="flex items-start gap-2.5 text-sm text-muted-foreground">
+          <BookOpen className="w-4 h-4 mt-0.5 shrink-0 text-primary" />
+          Follow bills, members, or topics — get low-noise alerts when things actually move
+        </li>
+        <li className="flex items-start gap-2.5 text-sm text-muted-foreground">
+          <GitCompare className="w-4 h-4 mt-0.5 shrink-0 text-primary" />
+          See <em>what changed</em> in plain English when bills are amended
+        </li>
+        <li className="flex items-start gap-2.5 text-sm text-muted-foreground">
+          <ShieldCheck className="w-4 h-4 mt-0.5 shrink-0 text-primary" />
+          Verify every AI claim with <strong>Back to Source</strong> citations from the bill text
+        </li>
+      </ul>
+
+      <div className="flex items-center gap-2">
+        <Link
+          href="/bills"
+          onClick={dismiss}
+          className="px-3 py-1.5 text-sm font-medium bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors"
+        >
+          Browse Bills
+        </Link>
+        <button
+          onClick={dismiss}
+          className="px-3 py-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors"
+        >
+          Dismiss
+        </button>
+      </div>
+    </div>
+  );
+}