Research Links UX + ICP Library

1. Problem Statement

Reveal Live's research links flow has friction that slows down the live demo moment:

2. Current State

What Exists

What's Missing

3. Research Links UX Improvements

3.1 Smart Input — URL or Username

The research link input field accepts EITHER format:

Full URL:    https://linkedin.com/in/john-smith-a1b2c3
Username:    @johnsmith
Name only:   John Smith
Handle:      linkedin.com/in/john-smith

Resolution logic (LLM-assisted):

async function resolveResearchInput(
  input: string, platform: string
): Promise<string> {
  // 1. Already a full URL? Return as-is.
  if (input.startsWith('http://') || input.startsWith('https://')) {
    return normalizeUrl(input, platform)
  }

  // 2. Partial URL (e.g., "linkedin.com/in/john")? Prepend https://
  if (input.includes('.com/') || input.includes('.io/')) {
    return 'https://' + input
  }

  // 3. Username or name — LLM resolves to full URL
  // LinkedIn: @johnsmith → https://linkedin.com/in/johnsmith
  // Twitter/X: @johnsmith → https://x.com/johnsmith
  // Instagram: johnsmith → https://instagram.com/johnsmith
  return await llmResolveProfileUrl(input, platform)
}

UI behavior:

• Input field shows placeholder: Paste URL, @username, or full name
• On blur/submit, the resolved URL replaces the input with a "Resolved" indicator
• If resolution is ambiguous, show the resolved URL with an "Edit" link to correct

3.2 Multi-URL Support

Current: One URL field per platform (LinkedIn, Company, Social).
New: Dynamic list — add as many URLs as needed, tagged by type.

Auto-tagging: When a URL is added, auto-detect the platform:

• linkedin.com/in/* → LinkedIn (Personal)
• linkedin.com/company/* → LinkedIn (Company)
• x.com/* or twitter.com/* → X/Twitter
• instagram.com/* → Instagram
• *.substack.com → Substack
• Everything else → Website

3.3 Camera/OCR Capture

Two capture modes:

Mode A: Screenshot capture (user's phone)
The user takes a screenshot of the prospect's profile on their own phone, then uploads it.

• Already partially built: LinkedIn intel uses screenshot-to-text extraction
• Extend: Accept any screenshot (not just LinkedIn), extract username/URL/name
• UI: Camera icon next to the "+ Add link" button → opens file picker or camera
• Extraction: Send image to vision LLM → extract profile URL, name, handle
• Result: Auto-populate research links with extracted URLs

Mode B: Live camera capture (of client's phone/screen)
User points their phone camera at the prospect's phone/laptop showing their profile.

• Uses browser getUserMedia API (camera access, already used for QR scanning)
• Capture frame → send to vision LLM → extract visible URL, username, platform
• More error-prone than screenshots but faster in the moment

async function extractProfileFromImage(
  imageBase64: string
): Promise<ResearchLink[]> {
  const response = await llm.analyze({
    model: 'claude-sonnet-4-6',
    messages: [{
      role: 'user',
      content: [
        {
          type: 'image',
          source: { type: 'base64', data: imageBase64 }
        },
        {
          type: 'text',
          text: `Extract all visible profile information:
            - Full name
            - Username/handle
            - Profile URL (if visible)
            - Platform (LinkedIn, X, Instagram, etc.)
            - Company name (if visible)
            - Job title (if visible)
            Return as JSON array of
            { url, platform, name, title, company }`
        }
      ]
    }]
  })
  return parseExtractedLinks(response)
}

4. Psychographic Deep-Dive — Confirm Flow

4.1 Current Pipeline (Already Working)

4.2 What Gets Extracted Today

4.3 What SHOULD Happen (Psychographic Pass)

After the agent swarm extracts raw data, a psychographic synthesis pass should run:

4.4 Confirm: This Already Partially Exists

The CRM Profile Editor (CRMProfileEditor.tsx) captures dreams/fears/suspicions/DO/DON'T manually. The new flow auto-generates this from research data and saves it persistently.

5. ICP Contact Library

5.1 Schema

New table: contact_profiles

CREATE TABLE IF NOT EXISTS contact_profiles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES auth.users(id),
  team_id UUID REFERENCES teams(id),

  -- Identity
  full_name TEXT NOT NULL,
  email TEXT,
  company TEXT,
  title TEXT,
  linkedin_url TEXT,
  profile_image_url TEXT,

  -- Research links (all URLs used for research)
  research_links JSONB DEFAULT '[]',
  -- Format: [{ url, platform, added_at, extracted_data_summary }]

  -- Raw agent extraction (full output, for re-processing)
  raw_extraction JSONB,

  -- Psychographic profile (the synthesized intelligence)
  psychographic JSONB,
  -- Format: {
  --   implied_dreams: [],
  --   implied_fears: [],
  --   implied_suspicions: [],
  --   communication_style: "",
  --   decision_pattern: "",
  --   trigger_phrases: [],
  --   anti_patterns: [],
  --   do_rules: [],
  --   dont_rules: [],
  --   summary: ""
  -- }

  -- Usage tracking
  run_ids TEXT[] DEFAULT '{}',
  page_slugs TEXT[] DEFAULT '{}',
  last_researched_at TIMESTAMPTZ,

  -- Metadata
  tags TEXT[] DEFAULT '{}',
  notes TEXT,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- Indexes for lookup
CREATE INDEX idx_contact_profiles_user
  ON contact_profiles(user_id);
CREATE INDEX idx_contact_profiles_team
  ON contact_profiles(team_id);
CREATE INDEX idx_contact_profiles_name
  ON contact_profiles(full_name);
CREATE INDEX idx_contact_profiles_email
  ON contact_profiles(email);

5.2 When Profiles Are Created/Updated

5.3 Contact Library UI

New section in Reveal dashboard (or sidebar):

5.4 Profile Injection into Templates

When starting a new Reveal run, the user can:

1. Select existing contact from the library → pre-fills research links + psychographic data
2. "Use saved profile" checkbox → skips agent swarm (already researched), uses cached extraction
3. "Re-research" option → runs agents again with saved links, updates profile

5.5 Cross-Template Reuse

The contact library enables new template types that reference the saved profile:

6. Avatar Editor — Pre-Publish Steelman Review

6.1 Why This Matters

The page IS the demo. If a single line doesn't land with the prospect, credibility breaks. The psychographic profile gives us everything we need to simulate how the prospect will actually read the page — before it goes live.

6.2 How It Works

After page generation and before publish, the system spins up an avatar editor — an LLM persona constructed from the contact's psychographic profile. This avatar reads the proposed page copy as the prospect would, and provides:

1. Reaction audit — line-by-line reactions: what resonates, what feels generic, what triggers suspicion
2. Language alignment — flags where the copy uses trigger phrases (good) vs anti-patterns (bad) from the profile
3. Credibility check — identifies claims the prospect would challenge based on their known skepticism patterns
4. Tone match — scores whether the copy matches their communication style (formal/casual, data/story-driven)
5. Edit suggestions — specific rewrites that would land better with this person

6.3 Avatar Construction

The avatar is built from the saved psychographic profile:

Contact Profile (from ICP Library)
  ├── implied_dreams        → What they want to hear (lean into)
  ├── implied_fears          → What makes them defensive (avoid)
  ├── implied_suspicions     → What they'll fact-check first (substantiate)
  ├── communication_style    → How they process information
  ├── decision_pattern       → How they evaluate proposals
  ├── trigger_phrases        → Language that resonates
  ├── anti_patterns          → Language that repels
  ├── do_rules               → Engagement guidelines
  └── dont_rules             → Known dealbreakers

System prompt for avatar:

You are {full_name}, {title} at {company}.

Your communication style: {communication_style}
Your decision-making pattern: {decision_pattern}

Things you care about deeply: {implied_dreams}
Things that make you skeptical: {implied_suspicions}
Things you've been burned by before: {implied_fears}

Language that resonates with you: {trigger_phrases}
Language that turns you off: {anti_patterns}

Read the following page that was created for you. React honestly.
For each section, note:
- Does this feel like it was written FOR you or AT you?
- What would you challenge?
- What makes you want to keep reading?
- What makes you want to close the tab?

Be specific. Quote the exact lines that work or don't work.

6.4 Review UI Flow

6.5 Where the Contact Library Compounds

Without a saved profile, the avatar is constructed from whatever the agent swarm extracted during this run — good but shallow. With a saved profile that's been enriched across multiple interactions, the avatar is more accurate:

6.6 Connection to Existing Steelman

The audit engine (lib/reveal/audit.ts) already does factual steelman — verifying claims against web sources and scoring confidence. The avatar editor is the psychographic steelman — verifying that the copy will land with this specific person. They're complementary:

7. Implementation Sequence

8. What We're NOT Building (Yet)

9. Success Criteria

• Smart input: Pasting "@johnsmith" into LinkedIn field resolves to full URL
• Multi-URL: Can add 5+ research links for one prospect (LinkedIn personal + company + podcast + blog + X)
• Screenshot capture: Upload screenshot of profile → research links auto-populated
• Contact persistence: After a Reveal run, contact profile saved with full psychographic data
• Library lookup: Can find any previously-researched contact by name, email, or company
• Profile reuse: Starting a new run for a known contact skips agent swarm, uses cached profile
• Avatar review: Pre-publish steelman reads page as the prospect, flags what doesn't land, suggests edits
• Data survives: Contact profiles are reusable across templates (Reveal page today, email funnel tomorrow)