From 7d927ab2374578537d8eeb1e72d829790f894f63 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sun, 13 Sep 2026 16:11:45 +0000
Subject: [PATCH] feat: retain public profile photos during enrichment

---
 .env.example                                 |   5 +-
 README.md                                    |  16 ++
 apps/server/src/index.ts                     |   7 +-
 apps/web/components/avatar.tsx               |   8 +-
 packages/pipeline/src/crawl.test.ts          |  21 ++-
 packages/pipeline/src/photos.test.ts         |  25 ++-
 packages/pipeline/src/photos.ts              |  48 +++++-
 packages/pipeline/src/pipeline.test.ts       |  76 ++++++++-
 packages/pipeline/src/pipeline.ts            |   8 +
 packages/providers/src/fan-out.test.ts       |  46 ++++++
 packages/providers/src/fan-out.ts            |  28 +++-
 packages/providers/src/github/client.ts      |   1 +
 packages/providers/src/github/github.test.ts |   5 +
 packages/providers/src/github/provider.ts    |   3 +
 packages/providers/src/index.ts              |   3 +
 packages/providers/src/photo.ts              |  23 +++
 packages/providers/src/provider.ts           |   7 +
 packages/providers/src/site/photos.test.ts   | 162 +++++++++++++++++++
 packages/providers/src/site/photos.ts        | 112 +++++++++++++
 packages/providers/src/site/provider.ts      |  21 +++
 20 files changed, 610 insertions(+), 15 deletions(-)
 create mode 100644 packages/providers/src/fan-out.test.ts
 create mode 100644 packages/providers/src/photo.ts
 create mode 100644 packages/providers/src/site/photos.test.ts
 create mode 100644 packages/providers/src/site/photos.ts

diff --git a/.env.example b/.env.example
index b109542..f2ac417 100644
--- a/.env.example
+++ b/.env.example
@@ -36,8 +36,9 @@ PDL_API_KEY=
 GITHUB_TOKEN=
 
 # Finds a lead's photo (and their LinkedIn profile URL, as research) by
-# searching their name, title and company. One image search per person,
-# roughly a quarter of a cent each. Unset, only Gravatar supplies pictures.
+# searching their name, title and company. One paid image search per person.
+# Optional: crawls, GitHub, social profiles and Gravatar also supply pictures
+# without image-search credits. LinkedIn image search requires this key.
 VALUESERP_API_KEY=
 # Ceiling on photo lookups per workspace per day. Default 300.
 PHOTO_LOOKUPS_PER_DAY=
diff --git a/README.md b/README.md
index 78eafe1..ccc030f 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,22 @@ typically yields three linked identities before any paid provider is touched.
 Each stage persists before the next runs, so a crash resumes rather than
 restarting, and a half-enriched prospect is still inspectable.
 
+## Public profile photos
+
+Prospects, approval cards and the daily digest show a photo when a public source
+supplies one. Crawls retain JSON-LD `Person.image` portraits and team images whose
+alt text names the person, including lazy-loaded images and relative URLs. GitHub
+enrichment keeps the public account's avatar. Photos are stored with the source
+page in field provenance; existing photos are kept, and a later crawl or enrichment
+can fill an empty photo even after image search previously missed.
+
+These paths use the pages and public API responses already being read. Gravatar
+and social profile intake remain available, and `VALUESERP_API_KEY` optionally
+enables the bounded image-search fallback for LinkedIn and company team pages.
+Nothing signs into LinkedIn or bypasses a blocked page. Missing or unavailable
+photos show initials. Previously imported people gain these photos on their next
+crawl or enrichment; this change does not run a production backfill.
+
 ## The three ideas worth knowing
 
 **The policy engine is arithmetic, not judgement.** Every outbound action
diff --git a/apps/server/src/index.ts b/apps/server/src/index.ts
index 13bff0b..e144805 100644
--- a/apps/server/src/index.ts
+++ b/apps/server/src/index.ts
@@ -247,8 +247,8 @@ if (!encryptionKey) {
 /**
  * Pictures of leads, by search.
  *
- * Optional, like every provider: unset, Gravatar is the only source and most
- * people stay as initials. Each lookup is a paid request, so the sweep is
+ * Optional: crawls, public profile enrichment and Gravatar also supply photos.
+ * Each search lookup is a paid request, so the sweep is
  * capped per workspace per day as well as per tick.
  */
 const photoFinder = process.env.VALUESERP_API_KEY
@@ -257,7 +257,8 @@ const photoFinder = process.env.VALUESERP_API_KEY
 
 const photoLookupsPerDay = Number(process.env.PHOTO_LOOKUPS_PER_DAY ?? 300);
 
-if (!photoFinder) console.log('no VALUESERP_API_KEY: lead photos come from Gravatar only');
+if (!photoFinder)
+  console.log('no VALUESERP_API_KEY: lead photos come from public profiles and crawls');
 
 /**
  * The feed clients for one campaign's own targets.
diff --git a/apps/web/components/avatar.tsx b/apps/web/components/avatar.tsx
index 66a9ab3..824bcfc 100644
--- a/apps/web/components/avatar.tsx
+++ b/apps/web/components/avatar.tsx
@@ -1,3 +1,7 @@
+'use client';
+
+import { useState } from 'react';
+
 /**
  * A face, or the initials standing in for one.
  *
@@ -25,9 +29,10 @@ export function Avatar({
   size?: keyof typeof SIZES;
   className?: string;
 }) {
+  const [failedSrc, setFailedSrc] = useState<string>();
   const box = `${SIZES[size]} shrink-0 rounded-full ${className}`;
 
-  if (src) {
+  if (src && src !== failedSrc) {
     return (
       // eslint-disable-next-line @next/next/no-img-element -- remote hosts are not known ahead of time
       <img
@@ -35,6 +40,7 @@ export function Avatar({
         alt=""
         loading="lazy"
         referrerPolicy="no-referrer"
+        onError={() => setFailedSrc(src)}
         className={`${box} bg-surface object-cover`}
       />
     );
diff --git a/packages/pipeline/src/crawl.test.ts b/packages/pipeline/src/crawl.test.ts
index 37902f3..1610020 100644
--- a/packages/pipeline/src/crawl.test.ts
+++ b/packages/pipeline/src/crawl.test.ts
@@ -35,7 +35,7 @@ const COMPANY_HTML = `<!doctype html><html><head>
   </script>
   <script type="application/ld+json">
     {"@context":"https://schema.org","@type":"Person","name":"Alex Chen",
-     "jobTitle":"Staff Engineer","sameAs":["https://github.com/alexchen"]}
+     "jobTitle":"Staff Engineer","sameAs":["https://github.com/alexchen"],"image":"/alex.jpg"}
   </script>
 </head><body>
   <footer>
@@ -112,13 +112,28 @@ describe('URL to approval card', () => {
       expect(summary.processed).toBe(1);
       expect(summary.succeeded).toBe(1);
 
-      const person = await queryOne<{ id: string; display_name: string; current_title: string }>(
+      const person = await queryOne<{
+        id: string;
+        display_name: string;
+        current_title: string;
+        avatar_url: string;
+        avatar_source: string;
+      }>(
         db,
-        'SELECT id, display_name, current_title FROM people WHERE display_name = ?',
+        'SELECT id, display_name, current_title, avatar_url, avatar_source FROM people WHERE display_name = ?',
         ['Alex Chen'],
       );
       expect(person?.display_name).toBe('Alex Chen');
       expect(person?.current_title).toBe('Staff Engineer');
+      expect(person?.avatar_url).toBe('https://loopwright.io/alex.jpg');
+      expect(person?.avatar_source).toBe('site');
+      const photoSource = await queryOne<{ source_record_id: string; provider: string }>(
+        db,
+        "SELECT source_record_id, provider FROM field_provenance WHERE entity_id = ? AND field = 'avatar_url'",
+        [person!.id],
+      );
+      expect(photoSource?.source_record_id).toBe('https://loopwright.io/');
+      expect(photoSource?.provider).toBe('site');
 
       // Filed into the workspace's campaign, or the card has nowhere to appear.
       const membership = await queryOne<{ status: string }>(
diff --git a/packages/pipeline/src/photos.test.ts b/packages/pipeline/src/photos.test.ts
index 05c9b87..1f8fcc4 100644
--- a/packages/pipeline/src/photos.test.ts
+++ b/packages/pipeline/src/photos.test.ts
@@ -9,8 +9,9 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { queryOne } from '@outreachgraph/db';
 import type { ProfilePhoto, ProfilePhotoFinder, ProfilePhotoQuery } from '@outreachgraph/providers';
+import { SiteProvider } from '@outreachgraph/providers';
 import { seedDatabase, SEED, type SeededDatabase } from '../../../apps/api/src/test-seed';
-import { sweepProfilePhotos, workspacesAwaitingPhotos } from './photos';
+import { storeDiscoveredPhoto, sweepProfilePhotos, workspacesAwaitingPhotos } from './photos';
 
 let seeded: SeededDatabase | undefined;
 
@@ -42,6 +43,28 @@ const LINKEDIN_HIT: ProfilePhoto = {
 };
 
 describe('sweepProfilePhotos', () => {
+  test('public crawl photos fill a previous search miss without spending another credit', async () => {
+    seeded = await seedDatabase('photos-later-crawl');
+    const { db } = seeded;
+    const { asked, finder: missed } = finder(undefined);
+    await sweepProfilePhotos({ db, finder: missed }, { workspaceId: SEED.workspaceId });
+    await storeDiscoveredPhoto(
+      db,
+      SEED.personId,
+      { url: 'https://acme.com/jane.jpg', pageUrl: 'https://acme.com/team' },
+      new SiteProvider().capabilities(),
+      new Date().toISOString(),
+    );
+    const person = await queryOne<{ avatar_url: string; photo_looked_up_at: string }>(
+      db,
+      'SELECT avatar_url, photo_looked_up_at FROM people WHERE id = ?',
+      [SEED.personId],
+    );
+    expect(person?.avatar_url).toBe('https://acme.com/jane.jpg');
+    expect(person?.photo_looked_up_at).toBeTruthy();
+    expect(asked).toHaveLength(1);
+    expect(await workspacesAwaitingPhotos(db)).toEqual([]);
+  });
   test('asks with everything known and records the picture and the profile', async () => {
     seeded = await seedDatabase('photos-hit');
     const { db } = seeded;
diff --git a/packages/pipeline/src/photos.ts b/packages/pipeline/src/photos.ts
index 5db8cc3..661366a 100644
--- a/packages/pipeline/src/photos.ts
+++ b/packages/pipeline/src/photos.ts
@@ -23,8 +23,12 @@
  */
 
 import { newId } from '@outreachgraph/domain';
-import type { ProfilePhotoFinder } from '@outreachgraph/providers';
-import { isLinkedInProfile } from '@outreachgraph/providers';
+import type {
+  CandidatePhoto,
+  ProfilePhotoFinder,
+  ProviderCapabilities,
+} from '@outreachgraph/providers';
+import { isLinkedInProfile, publicPhotoUrl } from '@outreachgraph/providers';
 import { now, queryAll, queryOne, type Client } from '@outreachgraph/db';
 
 /** Lookups per workspace per tick. */
@@ -32,6 +36,46 @@ const SWEEP_SIZE = 20;
 /** Lookups per workspace per day, absent a configured ceiling. */
 const DEFAULT_DAILY_CAP = 300;
 
+/** Fill a missing portrait, keeping the public source in the same transaction. */
+export async function storeDiscoveredPhoto(
+  db: Client,
+  personId: string,
+  photo: CandidatePhoto,
+  provider: ProviderCapabilities,
+  stamp: string,
+): Promise<void> {
+  const url = publicPhotoUrl(photo.url);
+  const pageUrl = publicPhotoUrl(photo.pageUrl);
+  if (!url || !pageUrl) return;
+  await db.batch(
+    [
+      {
+        sql: `INSERT INTO field_provenance (id, entity_kind, entity_id, field, value, source_type,
+              provider, source_record_id, license_class, confidence, observed_at, created_at)
+            SELECT ?, 'person', id, 'avatar_url', ?, ?, ?, ?, ?, 1.0, ?, ?
+              FROM people WHERE id = ? AND avatar_url IS NULL AND kind = 'person' AND status = 'active'`,
+        args: [
+          newId('fieldProvenance'),
+          url,
+          provider.sourceType,
+          provider.slug,
+          pageUrl,
+          provider.licenseClass,
+          stamp,
+          stamp,
+          personId,
+        ],
+      },
+      {
+        sql: `UPDATE people SET avatar_url = ?, avatar_source = ?, updated_at = ?
+              WHERE id = ? AND avatar_url IS NULL AND kind = 'person' AND status = 'active'`,
+        args: [url, provider.slug, stamp, personId],
+      },
+    ],
+    'write',
+  );
+}
+
 /**
  * How much to believe a LinkedIn URL found by search.
  *
diff --git a/packages/pipeline/src/pipeline.test.ts b/packages/pipeline/src/pipeline.test.ts
index b9e73f8..11e1b80 100644
--- a/packages/pipeline/src/pipeline.test.ts
+++ b/packages/pipeline/src/pipeline.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { GitHubProvider } from '@outreachgraph/providers';
+import { GitHubProvider, SiteProvider } from '@outreachgraph/providers';
 import { seedDatabase, SEED, type SeededDatabase } from '../../../apps/api/src/test-seed';
-import { runPipeline } from './pipeline';
+import { runPipeline, runPipelineForCandidate } from './pipeline';
 
 /** A GitHub profile with the self-declared cross-links the resolver needs. */
 const PROFILE = {
@@ -17,6 +17,7 @@ const PROFILE = {
   public_repos: 30,
   followers: 500,
   html_url: 'https://github.com/alexchen',
+  avatar_url: 'https://avatars.githubusercontent.com/u/4242?v=4',
   created_at: '2015-01-01T00:00:00Z',
   updated_at: '2026-08-01T00:00:00Z',
 };
@@ -120,6 +121,68 @@ function options(db: SeededDatabase['db']) {
 }
 
 describe('end to end', () => {
+  test('a crawled GitHub handle gains its public avatar with GitHub attribution', async () => {
+    const { db } = await fixture('portrait-fanout');
+    const result = await runPipelineForCandidate(
+      { ...options(db), providers: [stubGitHub()] },
+      {
+        fullName: 'Alex Chen',
+        title: 'Staff Engineer',
+        companyName: 'Loopwright',
+        identities: [{ network: 'github', handle: 'alexchen' }],
+        observedAt: new Date().toISOString(),
+      },
+      { capabilities: new SiteProvider().capabilities(), sourceUrl: 'https://loopwright.io/team' },
+    );
+    const person = await db.execute({
+      sql: 'SELECT avatar_url, avatar_source FROM people WHERE id = ?',
+      args: [result.personId!],
+    });
+    expect(person.rows[0]?.avatar_url).toBe(PROFILE.avatar_url);
+    expect(person.rows[0]?.avatar_source).toBe('github');
+    const provenance = await db.execute({
+      sql: "SELECT provider, source_type, source_record_id FROM field_provenance WHERE entity_id = ? AND field = 'avatar_url'",
+      args: [result.personId!],
+    });
+    expect(provenance.rows[0]).toMatchObject({
+      provider: 'github',
+      source_type: 'official_api',
+      source_record_id: PROFILE.html_url,
+    });
+  });
+  test('stores a GitHub portrait and provenance once, and keeps an existing photo', async () => {
+    const { db } = await fixture('portrait');
+    const result = await runPipeline(options(db), 'alexchen');
+    const person = await db.execute({
+      sql: 'SELECT avatar_url, avatar_source FROM people WHERE id = ?',
+      args: [result.personId!],
+    });
+    expect(person.rows[0]?.avatar_url).toBe(PROFILE.avatar_url);
+    expect(person.rows[0]?.avatar_source).toBe('github');
+    await runPipeline(options(db), 'alexchen');
+    const provenance = await db.execute({
+      sql: "SELECT value, provider, source_record_id, license_class FROM field_provenance WHERE entity_id = ? AND field = 'avatar_url'",
+      args: [result.personId!],
+    });
+    expect(provenance.rows).toHaveLength(1);
+    expect(provenance.rows[0]).toMatchObject({
+      value: PROFILE.avatar_url,
+      provider: 'github',
+      source_record_id: PROFILE.html_url,
+      license_class: 'public_api',
+    });
+    await db.execute({
+      sql: "UPDATE people SET avatar_url = 'https://example.com/chosen.jpg', avatar_source = 'profile' WHERE id = ?",
+      args: [result.personId!],
+    });
+    await runPipeline(options(db), 'alexchen');
+    const kept = await db.execute({
+      sql: 'SELECT avatar_url, avatar_source FROM people WHERE id = ?',
+      args: [result.personId!],
+    });
+    expect(kept.rows[0]?.avatar_url).toBe('https://example.com/chosen.jpg');
+    expect(kept.rows[0]?.avatar_source).toBe('profile');
+  });
   test('takes a bare handle all the way to the approval queue', async () => {
     const { db } = await fixture('happy');
 
@@ -292,11 +355,20 @@ describe('refusals', () => {
       sql: 'DELETE FROM recommendations WHERE person_id = ?',
       args: [first.personId!],
     });
+    await db.execute({
+      sql: 'UPDATE people SET avatar_url = NULL WHERE id = ?',
+      args: [first.personId!],
+    });
 
     const second = await runPipeline(options(db), 'alexchen');
 
     expect(second.stage).toBe('stopped');
     expect(second.stoppedBecause).toBe('suppressed');
+    const photo = await db.execute({
+      sql: 'SELECT avatar_url FROM people WHERE id = ?',
+      args: [first.personId!],
+    });
+    expect(photo.rows[0]?.avatar_url).toBeNull();
 
     const recommendations = await db.execute({
       sql: 'SELECT count(*) AS n FROM recommendations WHERE person_id = ?',
diff --git a/packages/pipeline/src/pipeline.ts b/packages/pipeline/src/pipeline.ts
index d4fd13e..311a76d 100644
--- a/packages/pipeline/src/pipeline.ts
+++ b/packages/pipeline/src/pipeline.ts
@@ -34,6 +34,7 @@ import { generateRecommendation, type CandidateSignal } from '@outreachgraph/rec
 import { draftForRecommendation, type TextModel } from '@outreachgraph/ai';
 import { rescoreProspect } from './jobs';
 import { recordDiscovered, recordStatus } from './stages';
+import { storeDiscoveredPhoto } from './photos';
 
 export interface PipelineOptions {
   readonly db: Client;
@@ -187,6 +188,10 @@ export async function runPipelineForCandidate(
     };
   }
 
+  if (candidate.photo) {
+    await storeDiscoveredPhoto(db, personId, candidate.photo, origin.capabilities, stamp);
+  }
+
   // -------------------------------------------------------------- resolve
   //
   // Ask the other configured providers what else they can vouch for before
@@ -196,6 +201,9 @@ export async function runPipelineForCandidate(
     options.providers.length > 0 ? await findIdentities(candidate, options.providers) : undefined;
 
   const enriched = fanned?.candidate ?? candidate;
+  if (fanned?.photo) {
+    await storeDiscoveredPhoto(db, personId, fanned.photo.value, fanned.photo.capabilities, stamp);
+  }
 
   // The page they were named on is itself an identity for them.
   //
diff --git a/packages/providers/src/fan-out.test.ts b/packages/providers/src/fan-out.test.ts
new file mode 100644
index 0000000..1f30f2b
--- /dev/null
+++ b/packages/providers/src/fan-out.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+import { findIdentities } from './fan-out';
+import { GitHubProvider } from './github/provider';
+import type { PersonCandidate } from './provider';
+
+const candidate: PersonCandidate = {
+  fullName: 'Jane Smith',
+  identities: [{ network: 'github', handle: 'janesmith' }],
+  observedAt: '2026-09-13T00:00:00Z',
+};
+
+function github(login: string) {
+  return new GitHubProvider({
+    fetchImpl: (async () =>
+      Response.json({
+        login,
+        id: 123,
+        name: 'Jane Smith',
+        html_url: `https://github.com/${login}`,
+        avatar_url: 'https://avatars.githubusercontent.com/u/123?v=4',
+      })) as unknown as typeof fetch,
+  });
+}
+
+describe('enrichment portraits', () => {
+  test('keeps a photo only when the response confirms a known account', async () => {
+    const result = await findIdentities(candidate, [github('janesmith')]);
+    expect(result.photo?.value.url).toBe('https://avatars.githubusercontent.com/u/123?v=4');
+    expect(result.photo?.capabilities.slug).toBe('github');
+    expect(result.photo?.capabilities.sourceType).toBe('official_api');
+  });
+
+  test('a different account with the same name cannot supply a portrait', async () => {
+    expect((await findIdentities(candidate, [github('somebodyelse')])).photo).toBeUndefined();
+  });
+
+  test('a provider error leaves the original candidate usable', async () => {
+    const provider = new GitHubProvider({
+      fetchImpl: (async () => new Response('', { status: 429 })) as unknown as typeof fetch,
+    });
+    const result = await findIdentities(candidate, [provider]);
+    expect(result.photo).toBeUndefined();
+    expect(result.candidate.fullName).toBe(candidate.fullName);
+    expect(result.attempts[0]?.ok).toBe(false);
+  });
+});
diff --git a/packages/providers/src/fan-out.ts b/packages/providers/src/fan-out.ts
index b3a26aa..0b8f2fd 100644
--- a/packages/providers/src/fan-out.ts
+++ b/packages/providers/src/fan-out.ts
@@ -13,7 +13,13 @@
  */
 
 import type { Network } from '@outreachgraph/domain';
-import type { CandidateIdentity, PersonCandidate, PersonEnrichmentProvider } from './provider';
+import type {
+  CandidateIdentity,
+  CandidatePhoto,
+  PersonCandidate,
+  PersonEnrichmentProvider,
+  ProviderCapabilities,
+} from './provider';
 
 export interface FanOutAttempt {
   readonly provider: string;
@@ -27,6 +33,8 @@ export interface FanOutResult {
   readonly candidate: PersonCandidate;
   readonly attempts: readonly FanOutAttempt[];
   readonly costUsd: number;
+  /** A portrait from a provider that answered for an identity we already held. */
+  readonly photo?: { readonly value: CandidatePhoto; readonly capabilities: ProviderCapabilities };
 }
 
 function key(identity: CandidateIdentity): string {
@@ -54,6 +62,7 @@ export async function findIdentities(
 
   const attempts: FanOutAttempt[] = [];
   let costUsd = 0;
+  let photo: FanOutResult['photo'];
 
   const known: Partial<Record<Network, string>> = {};
   for (const identity of candidate.identities) {
@@ -78,6 +87,22 @@ export async function findIdentities(
 
       costUsd += result.costUsd;
 
+      // A same-name search result may carry a plausible but wrong portrait.
+      // Only retain a photo when the provider confirmed a known account.
+      if (!photo && result.candidate?.photo && result.matchConfidence >= 0.85) {
+        const confirmed = result.candidate.identities.some((returned) =>
+          candidate.identities.some(
+            (known) =>
+              known.network === returned.network &&
+              ((known.platformUserId && known.platformUserId === returned.platformUserId) ||
+                (known.handle &&
+                  returned.handle &&
+                  known.handle.toLowerCase() === returned.handle.toLowerCase())),
+          ),
+        );
+        if (confirmed) photo = { value: result.candidate.photo, capabilities };
+      }
+
       let found = 0;
       for (const identity of result.candidate?.identities ?? []) {
         const id = key(identity);
@@ -101,5 +126,6 @@ export async function findIdentities(
     candidate: { ...candidate, identities: [...merged.values()] },
     attempts,
     costUsd,
+    ...(photo ? { photo } : {}),
   };
 }
diff --git a/packages/providers/src/github/client.ts b/packages/providers/src/github/client.ts
index 8a58742..8a3436a 100644
--- a/packages/providers/src/github/client.ts
+++ b/packages/providers/src/github/client.ts
@@ -23,6 +23,7 @@ export interface GitHubUser {
   public_repos: number;
   followers: number;
   html_url: string;
+  avatar_url?: string;
   created_at: string;
   updated_at: string;
 }
diff --git a/packages/providers/src/github/github.test.ts b/packages/providers/src/github/github.test.ts
index 11b52a3..315a4b7 100644
--- a/packages/providers/src/github/github.test.ts
+++ b/packages/providers/src/github/github.test.ts
@@ -23,6 +23,7 @@ const USER = {
   public_repos: 42,
   followers: 900,
   html_url: 'https://github.com/janesmith',
+  avatar_url: 'https://avatars.githubusercontent.com/u/27381?v=4',
   created_at: '2012-01-01T00:00:00Z',
   updated_at: '2026-08-01T00:00:00Z',
 };
@@ -44,6 +45,10 @@ function stubFetch(routes: Record<string, unknown>, status = 200): typeof fetch
 }
 
 describe('profile mapping', () => {
+  test('keeps the public avatar with its profile page, and rejects unsafe URLs', () => {
+    expect(toCandidate(USER).photo).toEqual({ url: USER.avatar_url, pageUrl: USER.html_url });
+    expect(toCandidate({ ...USER, avatar_url: 'data:image/svg+xml,unsafe' }).photo).toBeUndefined();
+  });
   test('turns self-declared profile fields into linked identities', () => {
     const candidate = toCandidate(USER as never);
 
diff --git a/packages/providers/src/github/provider.ts b/packages/providers/src/github/provider.ts
index e0979d1..e73297a 100644
--- a/packages/providers/src/github/provider.ts
+++ b/packages/providers/src/github/provider.ts
@@ -8,6 +8,7 @@
  */
 
 import type { CandidateIdentity, PersonCandidate } from '../provider';
+import { publicPhotoUrl } from '../photo';
 import type {
   PersonEnrichmentInput,
   PersonEnrichmentProvider,
@@ -155,9 +156,11 @@ export function toCandidate(user: GitHubUser): PersonCandidate {
   }
 
   const [firstName, lastName] = splitName(user.name ?? user.login);
+  const photoUrl = publicPhotoUrl(user.avatar_url);
 
   return {
     fullName: user.name ?? user.login,
+    ...(photoUrl ? { photo: { url: photoUrl, pageUrl: user.html_url } } : {}),
     ...(firstName ? { firstName } : {}),
     ...(lastName ? { lastName } : {}),
     ...(user.company ? { companyName: cleanCompany(user.company) } : {}),
diff --git a/packages/providers/src/index.ts b/packages/providers/src/index.ts
index 9d8a5fd..4c31251 100644
--- a/packages/providers/src/index.ts
+++ b/packages/providers/src/index.ts
@@ -8,6 +8,7 @@
 export {
   ProviderConfigurationError,
   type CandidateIdentity,
+  type CandidatePhoto,
   type PersonCandidate,
   type PersonEnrichmentInput,
   type PersonEnrichmentProvider,
@@ -17,6 +18,8 @@ export {
   type ProviderCapabilities,
 } from './provider';
 
+export { publicPhotoUrl } from './photo';
+
 export {
   attributeFields,
   enrichWithWaterfall,
diff --git a/packages/providers/src/photo.ts b/packages/providers/src/photo.ts
new file mode 100644
index 0000000..3708f73
--- /dev/null
+++ b/packages/providers/src/photo.ts
@@ -0,0 +1,23 @@
+/** Only ordinary remote image URLs; never inline content or embedded credentials. */
+export function publicPhotoUrl(value: unknown, base?: string): string | undefined {
+  if (typeof value !== 'string' || !value.trim() || value.trim().startsWith('#')) return undefined;
+  try {
+    const url = new URL(value.trim(), base);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+      return undefined;
+    const host = url.hostname.toLowerCase().replace(/\.$/, '');
+    if (
+      !host.includes('.') ||
+      /\.(localhost|local|internal)$/.test(host) ||
+      /^(0|10|127)\./.test(host) ||
+      /^169\.254\./.test(host) ||
+      /^192\.168\./.test(host) ||
+      /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+      /^\[/.test(host)
+    )
+      return undefined;
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/providers/src/provider.ts b/packages/providers/src/provider.ts
index 5f64a6b..a23dc60 100644
--- a/packages/providers/src/provider.ts
+++ b/packages/providers/src/provider.ts
@@ -60,8 +60,15 @@ export interface CandidateIdentity {
   readonly providerConfidence?: number;
 }
 
+/** A public portrait and the page that explicitly assigns it to this person. */
+export interface CandidatePhoto {
+  readonly url: string;
+  readonly pageUrl: string;
+}
+
 export interface PersonCandidate {
   readonly fullName: string;
+  readonly photo?: CandidatePhoto;
   /**
    * What this candidate is. Absent means a person. `company_inbox` is set
    * only by the crawl, for the shared mailbox of a company that named nobody;
diff --git a/packages/providers/src/site/photos.test.ts b/packages/providers/src/site/photos.test.ts
new file mode 100644
index 0000000..ccc7018
--- /dev/null
+++ b/packages/providers/src/site/photos.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, test } from 'bun:test';
+import { publicPhotoUrl } from '../photo';
+import { extractNamedPhotos } from './photos';
+import { SiteProvider } from './provider';
+
+const PAGE = 'https://acme.example/team/';
+const NAMES = ['Jane Smith', 'Martín Gómez'];
+const structured = (value: unknown) =>
+  `<script type="application/ld+json">${JSON.stringify(value)}</script>`;
+
+describe('public portraits', () => {
+  test('reads nested Person image objects and arrays, resolving against the source page', () => {
+    const photos = extractNamedPhotos(
+      structured({
+        '@graph': [
+          {
+            '@type': 'Organization',
+            employee: [
+              {
+                '@type': 'Person',
+                name: 'Jane Smith',
+                image: { '@type': 'ImageObject', contentUrl: '../jane.jpg' },
+              },
+              {
+                '@type': ['Person'],
+                name: 'Martín Gómez',
+                image: [null, { url: '//cdn.example/martin.jpg' }],
+              },
+            ],
+          },
+        ],
+      }),
+      PAGE,
+      NAMES,
+    );
+    expect(photos.get('Jane Smith')).toEqual({
+      url: 'https://acme.example/jane.jpg',
+      pageUrl: PAGE,
+    });
+    expect(photos.get('Martín Gómez')?.url).toBe('https://cdn.example/martin.jpg');
+  });
+
+  test('matches explicit portrait labels, not a nearby name or a partial match', () => {
+    const photos = extractNamedPhotos(
+      `
+      <h3>Jane Smith</h3><img src="/wrong.jpg" alt="Mary Jane Smith">
+      <img src="/logo.jpg"><img alt="Jane Smith headshot" data-src="/jane.jpg?x=1&amp;y=2" src="data:image/gif;base64,AAAA">
+      <img src=/martin.jpg alt="Portrait of MARTÍN GÓMEZ">
+      <img alt="Jane Smith" src="/pixel.gif" width="1" height="1">
+    `,
+      PAGE,
+      NAMES,
+    );
+    expect(photos.get('Jane Smith')?.url).toBe('https://acme.example/jane.jpg?x=1&y=2');
+    expect(photos.get('Martín Gómez')?.url).toBe('https://acme.example/martin.jpg');
+  });
+
+  test('structured portraits win over named markup, and a malformed block does not hide images', () => {
+    const html =
+      structured({ '@type': 'Person', name: 'Jane Smith', image: '/official.jpg' }) +
+      '<script type="application/ld+json">not json</script><img alt="Jane Smith" src="/jane.jpg">';
+    expect(extractNamedPhotos(html, PAGE, NAMES).get('Jane Smith')?.url).toBe(
+      'https://acme.example/official.jpg',
+    );
+  });
+
+  test('ignores generic share cards, unlabelled images, script strings and comments', () => {
+    const photos = extractNamedPhotos(
+      `
+      <meta property="og:image" content="/share.jpg"><h1>Jane Smith</h1><img src="/team.jpg">
+      <!-- <img alt="Jane Smith" src="/comment.jpg"> -->
+      <script>const x = '<img alt="Jane Smith" src="/script.jpg">';</script>
+    `,
+      PAGE,
+      NAMES,
+    );
+    expect(photos.size).toBe(0);
+  });
+
+  test('rejects an image claimed by multiple people, including an unextracted name', () => {
+    const photos = extractNamedPhotos(
+      '<img alt="Jane Smith" src="/shared.jpg"><img alt="Somebody Else" src="/shared.jpg">',
+      PAGE,
+      NAMES,
+    );
+    expect(photos.size).toBe(0);
+  });
+
+  test.each([
+    'javascript:alert(1)',
+    'data:image/svg+xml,x',
+    'file:///tmp/me.jpg',
+    '#portrait',
+    'http://127.0.0.1/me.jpg',
+    'http://2130706433/me.jpg',
+    'http://10.1.2.3/me.jpg',
+    'http://169.254.169.254/latest',
+    'http://[::1]/me.jpg',
+    'https://user:secret@cdn.example/me.jpg',
+  ])('rejects an unsafe photo URL: %s', (url) => {
+    expect(publicPhotoUrl(url, PAGE)).toBeUndefined();
+    expect(extractNamedPhotos(`<img alt="Jane Smith" src="${url}">`, PAGE, NAMES).size).toBe(0);
+  });
+
+  test('the crawl retains portraits from followed team pages without extra requests', async () => {
+    const requested: string[] = [];
+    const site = new SiteProvider({
+      fetchImpl: async (input) => {
+        const url = input.toString();
+        requested.push(url);
+        if (url.endsWith('/robots.txt')) return new Response('User-agent: *\nAllow: /');
+        const html =
+          url === 'https://acme.example/'
+            ? structured({ '@type': 'Person', name: 'Jane Smith' }) + '<a href="/team">Our team</a>'
+            : '<img src="/jane.jpg" alt="Jane Smith">';
+        return new Response(html, { headers: { 'content-type': 'text/html' } });
+      },
+    });
+    const result = await site.crawl('https://acme.example/');
+    expect(result.people[0]?.photo).toEqual({
+      url: 'https://acme.example/jane.jpg',
+      pageUrl: 'https://acme.example/team',
+    });
+    expect(result.usedSignals).toContain('photo');
+    expect(requested.filter((url) => !url.endsWith('/robots.txt'))).toEqual([
+      'https://acme.example/',
+      'https://acme.example/team',
+    ]);
+  });
+
+  test('a robots-denied team page cannot contribute a portrait', async () => {
+    const requested: string[] = [];
+    const site = new SiteProvider({
+      fetchImpl: async (input) => {
+        const url = input.toString();
+        requested.push(url);
+        if (url.endsWith('/robots.txt')) return new Response('User-agent: *\nDisallow: /team');
+        return new Response(
+          structured({ '@type': 'Person', name: 'Jane Smith' }) + '<a href="/team">Team</a>',
+        );
+      },
+    });
+    expect((await site.crawl('https://acme.example/')).people[0]?.photo).toBeUndefined();
+    expect(requested).not.toContain('https://acme.example/team');
+  });
+
+  test('rejects a shared image when another page names a different owner', async () => {
+    const site = new SiteProvider({
+      fetchImpl: async (input) => {
+        const url = input.toString();
+        if (url.endsWith('/robots.txt')) return new Response('');
+        const html =
+          url === 'https://acme.example/'
+            ? structured({ '@type': 'Person', name: 'Jane Smith', image: '/shared.jpg' }) +
+              '<a href="/team">Team</a>'
+            : '<img alt="Somebody Else" src="/shared.jpg">';
+        return new Response(html);
+      },
+    });
+    expect((await site.crawl('https://acme.example/')).people[0]?.photo).toBeUndefined();
+  });
+});
diff --git a/packages/providers/src/site/photos.ts b/packages/providers/src/site/photos.ts
new file mode 100644
index 0000000..cbe14c2
--- /dev/null
+++ b/packages/providers/src/site/photos.ts
@@ -0,0 +1,112 @@
+/**
+ * Portraits from HTML the crawler already read. The site must name the owner
+ * in a Person.image or in the image's alt text; proximity to a name and the
+ * company's OpenGraph card are not enough to assign somebody a face.
+ */
+import type { CandidatePhoto } from '../provider';
+import { publicPhotoUrl } from '../photo';
+import { collapse, decodeEntities } from './extract';
+
+function nameKey(value: string): string {
+  return collapse(value).normalize('NFC').toLowerCase();
+}
+
+function imageUrl(value: unknown, pageUrl: string): string | undefined {
+  if (typeof value === 'string') return publicPhotoUrl(decodeEntities(value), pageUrl);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const url = imageUrl(item, pageUrl);
+      if (url) return url;
+    }
+  } else if (value && typeof value === 'object') {
+    const image = value as Record<string, unknown>;
+    return imageUrl(image.contentUrl, pageUrl) ?? imageUrl(image.url, pageUrl);
+  }
+  return undefined;
+}
+
+function attribute(tag: string, name: string): string | undefined {
+  const match = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag);
+  const value = match?.[1] ?? match?.[2] ?? match?.[3];
+  return value === undefined ? undefined : decodeEntities(value);
+}
+
+export function extractNamedPhotos(
+  html: string,
+  pageUrl: string,
+  people: readonly string[],
+  /** Shared across pages so a reused image cannot acquire different owners. */
+  owners = new Map<string, Set<string>>(),
+): ReadonlyMap<string, CandidatePhoto> {
+  const names = new Map(people.map((name) => [nameKey(name), name]));
+  const found = new Map<string, CandidatePhoto>();
+  // Track all claimants, even names the model did not extract. A shared logo
+  // or placeholder labelled as several people is nobody's portrait.
+  const add = (name: string, url: string | undefined): void => {
+    if (!url) return;
+    const key = nameKey(name);
+    owners.set(url, (owners.get(url) ?? new Set()).add(key));
+    const person = names.get(key);
+    if (person && !found.has(person)) found.set(person, { url, pageUrl });
+  };
+
+  // Schema permits nested Person objects (author, employee, mainEntity),
+  // arrays, @graph, and ImageObject values. Walk those without guessing names.
+  const visit = (node: unknown, depth = 0): void => {
+    if (!node || typeof node !== 'object' || depth > 20) return;
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child, depth + 1);
+      return;
+    }
+    const object = node as Record<string, unknown>;
+    const types = Array.isArray(object['@type']) ? object['@type'] : [object['@type']];
+    if (types.includes('Person') && typeof object.name === 'string') {
+      add(object.name, imageUrl(object.image, pageUrl));
+    }
+    for (const child of Object.values(object)) visit(child, depth + 1);
+  };
+  const uncommented = html.replace(/<!--[\s\S]*?-->/g, '');
+  for (const match of uncommented.matchAll(
+    /<script\b[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi,
+  )) {
+    try {
+      visit(JSON.parse(match[1] ?? ''));
+    } catch {
+      // A broken structured-data block must not hide the page's named images.
+    }
+  }
+
+  const visible = uncommented.replace(
+    /<script\b[\s\S]*?<\/script>|<style\b[\s\S]*?<\/style>/gi,
+    '',
+  );
+  for (const match of visible.matchAll(/<img\b[^>]*>/gi)) {
+    const tag = match[0];
+    const label = attribute(tag, 'alt');
+    if (!label) continue;
+    const name = label
+      .trim()
+      .replace(
+        /^(?:(?:profile\s+)?(?:photo(?:graph)?|portrait|headshot|picture|image)(?:\s+of)?\s*[:\-]?\s+)/i,
+        '',
+      )
+      .replace(
+        /\s*[,\-–—:]?\s+(?:(?:profile\s+)?photo(?:graph)?|portrait|headshot|picture|image)$/i,
+        '',
+      );
+    const width = Number(attribute(tag, 'width'));
+    const height = Number(attribute(tag, 'height'));
+    if ((width > 0 && width < 32) || (height > 0 && height < 32)) continue;
+    // Lazy-load attributes carry the portrait when src is a placeholder.
+    const url =
+      imageUrl(attribute(tag, 'data-src'), pageUrl) ??
+      imageUrl(attribute(tag, 'data-lazy-src'), pageUrl) ??
+      imageUrl(attribute(tag, 'src'), pageUrl);
+    add(name, url);
+  }
+
+  for (const [person, photo] of found) {
+    if (owners.get(photo.url)?.size !== 1) found.delete(person);
+  }
+  return found;
+}
diff --git a/packages/providers/src/site/provider.ts b/packages/providers/src/site/provider.ts
index 202e7dc..02dba6b 100644
--- a/packages/providers/src/site/provider.ts
+++ b/packages/providers/src/site/provider.ts
@@ -28,6 +28,7 @@ import { extractSite, handleFromUrl, type ExtractedCompany } from './extract';
 import { attributeToPeople, mergeAttribution } from './attribute';
 import { extractWithModel, visibleText, type ExtractionModel } from './model-extract';
 import { assignEmails, findEmails } from './emails';
+import { extractNamedPhotos } from './photos';
 
 export interface SiteProviderOptions extends FetchOptions {
   /** Omit to run deterministic-only; the crawl still works, it just reads less. */
@@ -321,6 +322,26 @@ export class SiteProvider implements PersonEnrichmentProvider {
       }
     }
 
+    // Read named portraits only after the people are known, including names
+    // supplied by the model. No extra requests or image-search credits.
+    const photoOwners = new Map<string, Set<string>>();
+    const portraits = pages.map((read) =>
+      extractNamedPhotos(
+        read.html ?? '',
+        read.finalUrl,
+        people.map((person) => person.fullName),
+        photoOwners,
+      ),
+    );
+    people = people.map((person) => {
+      for (const pagePhotos of portraits) {
+        const photo = pagePhotos.get(person.fullName);
+        if (photo && photoOwners.get(photo.url)?.size === 1) return { ...person, photo };
+      }
+      return person;
+    });
+    if (people.some((person) => person.photo)) usedSignals.add('photo');
+
     // Addresses are read last, once the people are known: matching
     // `jane@acme.com` to a person needs the person, and the model pass is
     // often what produced them. Read across every page, because the address