feat: ZIP → rep lookup, member page redesign, letter improvements

ZIP lookup (GET /api/members/by-zip/{zip}):
- Two-step geocoding: Nominatim (ZIP → lat/lng) then Census TIGERweb
  Legislative identify (lat/lng → congressional district via GEOID)
- Handles at-large states (AK, DE, MT, ND, SD, VT, WY)
- Added rep_lookup health check to admin External API Health panel

congress_api.py fixes:
- parse_member_from_api: normalize state full name → 2-letter code
  (Congress.gov returns "Florida", DB expects "FL")
- parse_member_from_api: read district from top-level data field,
  not current_term (district is not inside the term object)

Celery beat: schedule sync_members daily at 1 AM UTC so chamber,
district, and contact info stay current without manual triggering

Members page redesign: photo avatars, party/state/chamber chips,
phone + website links, ZIP lookup form to find your reps

Draft letter improvements: pass rep_name from ZIP lookup so letter
opens with "Dear Representative Franklin," instead of generic salutation;
add has_document filter to bills list endpoint

UX additions: HelpTip component, How It Works page, "How it works"
sidebar nav link, collections page description copy

Authored-By: Jack Levy

frontend/components/bills/DraftLetterPanel.tsx

@@ -1,9 +1,10 @@
 "use client";
 
 import { useState, useEffect, useRef } from "react";
-import { ChevronDown, ChevronRight, Copy, Check, Loader2, PenLine } from "lucide-react";
-import type { BriefSchema, CitedPoint } from "@/lib/types";
-import { billsAPI } from "@/lib/api";
+import { useQuery } from "@tanstack/react-query";
+import { ChevronDown, ChevronRight, Copy, Check, ExternalLink, Loader2, Phone, PenLine } from "lucide-react";
+import type { BriefSchema, CitedPoint, Member } from "@/lib/types";
+import { billsAPI, membersAPI } from "@/lib/api";
 import { useIsFollowing } from "@/lib/hooks/useFollows";
 
 interface DraftLetterPanelProps {
@@ -27,6 +28,15 @@ function chamberToRecipient(chamber?: string): "house" | "senate" {
   return chamber?.toLowerCase() === "senate" ? "senate" : "house";
 }
 
+function formatRepName(member: Member): string {
+  // DB stores name as "Last, First" — convert to "First Last" for the letter
+  if (member.name.includes(", ")) {
+    const [last, first] = member.name.split(", ");
+    return `${first} ${last}`;
+  }
+  return member.name;
+}
+
 export function DraftLetterPanel({ billId, brief, chamber }: DraftLetterPanelProps) {
   const [open, setOpen] = useState(false);
   const existing = useIsFollowing("bill", billId);
@@ -53,6 +63,27 @@ export function DraftLetterPanel({ billId, brief, chamber }: DraftLetterPanelPro
   const [error, setError] = useState<string | null>(null);
   const [copied, setCopied] = useState(false);
 
+  // Zip → rep lookup (debounced via React Query enabled flag)
+  const zipTrimmed = zipCode.trim();
+  const isValidZip = /^\d{5}$/.test(zipTrimmed);
+  const { data: zipReps, isFetching: zipFetching } = useQuery({
+    queryKey: ["members-by-zip", zipTrimmed],
+    queryFn: () => membersAPI.byZip(zipTrimmed),
+    enabled: isValidZip,
+    staleTime: 24 * 60 * 60 * 1000,
+    retry: false,
+  });
+
+  // Filter reps to match the bill's chamber
+  const relevantReps = zipReps?.filter((m) =>
+    recipient === "senate"
+      ? m.chamber === "Senate"
+      : m.chamber === "House of Representatives"
+  ) ?? [];
+
+  // Use first matched rep's name for the letter salutation
+  const repName = relevantReps.length > 0 ? formatRepName(relevantReps[0]) : undefined;
+
   const keyPoints = brief.key_points ?? [];
   const risks = brief.risks ?? [];
   const allPoints = [
@@ -96,6 +127,7 @@ export function DraftLetterPanel({ billId, brief, chamber }: DraftLetterPanelPro
         selected_points: selectedPoints,
         include_citations: includeCitations,
         zip_code: zipCode.trim() || undefined,
+        rep_name: repName,
       });
       setDraft(result.draft);
     } catch (err: unknown) {
@@ -253,20 +285,23 @@ export function DraftLetterPanel({ billId, brief, chamber }: DraftLetterPanelPro
           </div>
 
           {/* Options row */}
-          <div className="flex flex-wrap items-center gap-4">
-            <div className="space-y-0.5">
-              <input
-                type="text"
-                value={zipCode}
-                onChange={(e) => setZipCode(e.target.value)}
-                placeholder="ZIP code"
-                maxLength={10}
-                className="text-xs bg-background border border-border rounded px-2 py-1.5 text-foreground w-28 placeholder:text-muted-foreground"
-              />
+          <div className="flex flex-wrap items-start gap-4">
+            <div className="space-y-1">
+              <div className="flex items-center gap-2">
+                <input
+                  type="text"
+                  value={zipCode}
+                  onChange={(e) => setZipCode(e.target.value)}
+                  placeholder="ZIP code"
+                  maxLength={10}
+                  className="text-xs bg-background border border-border rounded px-2 py-1.5 text-foreground w-28 placeholder:text-muted-foreground"
+                />
+                {zipFetching && <Loader2 className="w-3.5 h-3.5 animate-spin text-muted-foreground" />}
+              </div>
               <p className="text-[10px] text-muted-foreground">optional · not stored</p>
             </div>
 
-            <label className="flex items-center gap-1.5 cursor-pointer text-xs text-muted-foreground">
+            <label className="flex items-center gap-1.5 cursor-pointer text-xs text-muted-foreground mt-1.5">
               <input
                 type="checkbox"
                 checked={includeCitations}
@@ -277,6 +312,72 @@ export function DraftLetterPanel({ billId, brief, chamber }: DraftLetterPanelPro
             </label>
           </div>
 
+          {/* Rep lookup results */}
+          {isValidZip && !zipFetching && relevantReps.length > 0 && (
+            <div className="space-y-1.5">
+              <p className="text-xs font-medium text-muted-foreground">
+                Your {recipient === "senate" ? "senators" : "representative"}
+              </p>
+              {relevantReps.map((rep) => (
+                <div
+                  key={rep.bioguide_id}
+                  className="flex items-center gap-3 bg-muted/40 border border-border rounded-md px-3 py-2"
+                >
+                  {rep.photo_url && (
+                    <img
+                      src={rep.photo_url}
+                      alt={rep.name}
+                      className="w-8 h-8 rounded-full object-cover shrink-0 border border-border"
+                    />
+                  )}
+                  <div className="flex-1 min-w-0">
+                    <p className="text-xs font-medium">{formatRepName(rep)}</p>
+                    {rep.party && (
+                      <p className="text-[10px] text-muted-foreground">{rep.party} · {rep.state}</p>
+                    )}
+                  </div>
+                  <div className="flex items-center gap-2 shrink-0">
+                    {rep.phone && (
+                      <a
+                        href={`tel:${rep.phone.replace(/\D/g, "")}`}
+                        className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground transition-colors"
+                        title="Office phone"
+                      >
+                        <Phone className="w-3 h-3" />
+                        {rep.phone}
+                      </a>
+                    )}
+                    {rep.official_url && (
+                      <a
+                        href={rep.official_url}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="flex items-center gap-1 text-[10px] text-primary hover:underline"
+                        title="Contact form"
+                      >
+                        <ExternalLink className="w-3 h-3" />
+                        Contact
+                      </a>
+                    )}
+                  </div>
+                </div>
+              ))}
+              {repName && (
+                <p className="text-[10px] text-muted-foreground">
+                  Letter will be addressed to{" "}
+                  {recipient === "senate" ? "Senator" : "Representative"} {repName}.
+                </p>
+              )}
+            </div>
+          )}
+
+          {isValidZip && !zipFetching && relevantReps.length === 0 && zipReps !== undefined && (
+            <p className="text-[10px] text-amber-500">
+              Could not find your {recipient === "senate" ? "senators" : "representative"} for that ZIP.
+              The letter will use a generic salutation.
+            </p>
+          )}
+
           {/* Generate button */}
           <button
             onClick={handleGenerate}

frontend/components/shared/BillCard.tsx

@@ -1,5 +1,5 @@
 import Link from "next/link";
-import { TrendingUp, Calendar, User, FileText, FileClock, FileX } from "lucide-react";
+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";
@@ -28,12 +28,15 @@ export function BillCard({ bill, compact = false }: BillCardProps) {
               </span>
             )}
             {tags.map((tag) => (
-              <span
+              <Link
                 key={tag}
-                className="text-xs px-1.5 py-0.5 rounded-full bg-accent text-accent-foreground"
+                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" />
                 {tag}
-              </span>
+              </Link>
             ))}
           </div>
 

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/Sidebar.tsx

@@ -4,6 +4,7 @@ import Link from "next/link";
 import { usePathname, useRouter } from "next/navigation";
 import {
   Bookmark,
+  HelpCircle,
   LayoutDashboard,
   FileText,
   Users,
@@ -28,6 +29,7 @@ const NAV = [
   { href: "/following", label: "Following", icon: Heart, 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 },
 ];