franco 0.5.0__py3-none-any.whl

franco/__init__.py

@@ -0,0 +1,19 @@
+"""Franco — an autonomous sales agent that runs on your Claude subscription."""
+
+import sys
+
+# Fail with a sentence someone can act on, not a SyntaxError from deep inside
+# a module. `python3 -m venv` on macOS builds from the system 3.9, so this is
+# the single most likely first-run problem.
+if sys.version_info < (3, 11):  # pragma: no cover - version guard
+    raise RuntimeError(
+        f"Franco needs Python 3.11+, but this is "
+        f"{sys.version_info.major}.{sys.version_info.minor} "
+        f"({sys.executable}). On macOS `python3` is the system 3.9 — rebuild "
+        f"the venv from a newer Python:\n"
+        f"    brew install python@3.13\n"
+        f"    rm -rf .venv && $(brew --prefix)/bin/python3.13 -m venv .venv\n"
+        f"    source .venv/bin/activate && pip install -e ."
+    )
+
+"""Franco — Autonomous Sales Agent. Always Be Closing."""

franco/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running Franco with `python -m franco`."""
+
+from franco.cli import main
+
+if __name__ == "__main__":
+    main()

franco/_bundled/.env.example

@@ -0,0 +1,120 @@
+# ============================================================
+# Franco environment variables
+# Copy this file to .env and fill in your values:  cp .env.example .env
+# Never commit .env — it is gitignored.
+# Pick ONE email provider below (set channels.email.provider in franco.yaml
+# to match): gmail (recommended), smtp, or instantly. Everything else is
+# optional but an email verifier (Reoon/ZeroBounce) is strongly recommended.
+# ============================================================
+
+# ------------------------------------------------------------
+# EMAIL PROVIDER — how Franco sends and reads replies. Choose one.
+#
+# Option A: Gmail / Google Workspace  [RECOMMENDED for <50 cold/day]
+#   Set provider: gmail in franco.yaml. Use a mailbox on a DEDICATED
+#   secondary domain (never your main one), with SPF/DKIM/DMARC set up.
+#   1. Google Cloud Console → new project → enable the Gmail API
+#   2. Credentials → OAuth client ID → type "Desktop app"
+#   3. Paste the client id/secret below, then run: franco gmail auth
+GMAIL_CLIENT_ID=
+GMAIL_CLIENT_SECRET=
+
+# Option B: Any SMTP + IMAP mailbox  [AgentMail, Fastmail, Workspace app pw]
+#   Set provider: smtp in franco.yaml. IMAP_* defaults to the SMTP_* values.
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USERNAME=
+SMTP_PASSWORD=
+IMAP_HOST=
+IMAP_PORT=993
+IMAP_USERNAME=
+IMAP_PASSWORD=
+
+# Option C: Instantly — cold email platform  [legacy]
+# Where to get it: https://app.instantly.ai → Settings → Integrations → API Keys
+# API access requires Instantly's Growth plan or higher.
+INSTANTLY_API_KEY=
+
+# ------------------------------------------------------------
+# LinkedIn — browser-automation prospecting  [OPTIONAL]
+# These are the credentials of the LinkedIn account Franco will log into
+# with Playwright. WARNING: automation violates LinkedIn's Terms of Service
+# and can get the account restricted or banned. Use a account you can
+# afford to lose, keep the default rate limits, or leave blank to skip —
+# Franco will prospect via web search and company websites instead.
+LINKEDIN_EMAIL=
+LINKEDIN_PASSWORD=
+
+# ------------------------------------------------------------
+# Cloudflare Browser Rendering — deep website crawling during training  [OPTIONAL]
+# Enables JS-rendered crawling of your own site when running `franco train`.
+# Where to get it:
+#   Account ID: https://dash.cloudflare.com → right sidebar of any zone, or the URL
+#   API Token:  https://dash.cloudflare.com/profile/api-tokens → Create Token
+#               → grant "Browser Rendering: Edit" permission
+# Cost: ~$5/mo on the paid Workers plan (~12,000 pages). Free tier has limits.
+# Without these, Franco uses its built-in HTTP crawler (no JS rendering).
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
+
+# ------------------------------------------------------------
+# Email verification — how Franco confirms a prospect's address really
+# exists before sending. Franco learns each company's email PATTERN, then
+# verifies ONE candidate (raw SMTP probing no longer works against Google
+# Workspace / Microsoft 365). Any ONE of these keys is enough; add both for
+# best coverage. Without any, addresses are marked "guess" and never sent.
+
+# Reoon — best free tier for cold-email verification (600 checks/month,
+# renews monthly + 100 non-expiring). Good catch-all flagging.
+# Where to get it: https://reoon.com/email-verifier → sign up → API
+REOON_API_KEY=
+
+# ZeroBounce — 100 free/month. Its 2026 engine is the reliable one for
+# Microsoft 365 / Google Workspace catch-all domains; Franco routes those
+# domains here specifically. https://zerobounce.net → API
+ZEROBOUNCE_API_KEY=
+
+# Hunter.io — email discovery + pattern lookup  [OPTIONAL]
+# Free tier: 50 verifications + 25 domain-searches/month. Its domain-search
+# is the cheapest way to learn a company's email pattern (used first, so
+# Franco verifies one address instead of guessing six).
+# Where to get it: https://hunter.io → sign up → API → API Keys
+HUNTER_API_KEY=
+# Domain-searches per month across all of Franco. 25 matches Hunter's free
+# tier; set this to your plan's allowance if you pay for Hunter.
+HUNTER_MONTHLY_SEARCHES=25
+
+# ------------------------------------------------------------
+# DISCOVERY — where Franco finds businesses.  [ALL OPTIONAL]
+# The default source (OpenStreetMap) needs no account at all:
+#     franco discover
+# See every option, with real prices, via:
+#     franco discover --providers      (or the dashboard's Discover tab)
+# ------------------------------------------------------------
+
+# DataForSEO — cheapest local-business and SERP data anywhere.
+# Where to get it: https://app.dataforseo.com/api-access
+#   NOTE: the API password is auto-generated there. It is NOT your account
+#   password. $1 free credit on signup; $50 minimum deposit to go live.
+# Cost: $0.372 per 1,000 businesses; $0.0018 per depth-30 search.
+DATAFORSEO_LOGIN=
+DATAFORSEO_PASSWORD=
+# Set to any value to route every call to DataForSEO's free sandbox. Same
+# response shape, dummy data, never charged — the right way to try it.
+DATAFORSEO_SANDBOX=
+
+# Serper.dev — Google Search API, used for discovery and for Scout's searches.
+# Where to get it: https://serper.dev → sign up → Dashboard → API Key
+# Cost: 2,500 queries free with no card, then a $50 prepaid pack (credits
+# expire after 6 months). Without it Franco falls back to DuckDuckGo/Bing
+# scraping, which is heavily rate-limited.
+SERPER_API_KEY=
+
+# ------------------------------------------------------------
+# Calendly — meeting auto-booking  [NOT YET USED — roadmap]
+# CALENDLY_API_KEY=
+
+# --- Dashboard (optional) ---
+# The dashboard only answers requests addressed to localhost / 127.0.0.1.
+# Add other hostnames you reach it by (e.g. from Docker), comma-separated.
+FRANCO_DASHBOARD_HOSTS=

franco/_bundled/franco.yaml

@@ -0,0 +1,101 @@
+persona:
+  name: "Franco"
+  company: "Your Company"
+  role: "Business Development"
+  email: "franco@yourcompany.com"
+  linkedin: "linkedin.com/in/franco-yourcompany"
+  tone: "professional, consultative, confident"
+
+product:
+  name: "Your Product"
+  description: "Describe what your product does and who it's for"
+  pricing: "Starting at $X/mo"
+  key_benefits:
+    - "Benefit 1"
+    - "Benefit 2"
+    - "Benefit 3"
+  objection_responses:
+    "too expensive": "I understand budget is important. Most of our clients see ROI within 30 days..."
+    "already have a solution": "That makes sense. Curious — what's the one thing you wish it did better?"
+    "not interested": "No worries at all. Mind if I ask what your current approach looks like?"
+  offer:
+    primary: ""                    # Main offer (e.g., "Monthly subscription starting at $99/mo")
+    entry: ""                      # Low-commitment entry (e.g., "14-day free trial", "Free audit")
+    goal: "book_call"              # Goal of outreach: book_call, start_trial, get_reply
+    booking_method: "calendar_link" # calendar_link, suggest_times, ask_preference
+    booking_url: ""                # Calendar link URL (if using calendar_link method)
+    meeting_duration: "15 minutes" # How long the call is
+    meeting_owner: ""              # Who takes the meeting (name or role)
+
+icp:
+  industries:
+    - "SaaS"
+    - "Marketing Agency"
+  company_size: "10-200 employees"
+  titles:
+    - "VP Marketing"
+    - "Head of Growth"
+    - "CMO"
+    - "Director of Marketing"
+  geography:
+    - "United States"
+  # Roles that signal a company is in-market RIGHT NOW (a company hiring a
+  # "Head of Growth" is shopping for growth tooling). Used for careers-page
+  # scanning and job-board discovery. Empty = fall back to titles above.
+  hiring_signals: []
+
+channels:
+  email:
+    enabled: true
+    provider: "gmail"          # gmail (recommended) | smtp | instantly
+    max_daily_sends: 50
+    require_approval: true      # native providers: emails wait in the Outbox
+    send_to_risky: false        # also send to catch-all domains (off = safest)
+    max_bounce_rate: 0.05       # pause all sending if bounces exceed this
+  linkedin:
+    enabled: true
+    max_daily_connections: 20
+    max_daily_messages: 10
+
+usage:
+  max_daily_claude_percent: 80
+  heartbeat_interval_minutes: 15
+  quiet_hours:
+    start: "22:00"
+    end: "07:00"
+    timezone: "America/New_York"
+
+# How sequences are produced.
+#   generated: the writer drafts each sequence with the model (default).
+#   templates: approved copy, sent word for word to accounts you import with
+#              `franco import accounts.csv` (see README → Approved-copy outreach).
+outreach:
+  mode: "generated"
+  timezone: "America/New_York"   # business days and send times are counted here
+  send_hour: 9
+  observation_max_age_days: 90   # older research can't fill {{verified_observation}}
+  preview_accounts: 10           # per owner, held for review until `franco preview signoff KEY`
+  campaigns: {}
+  #   M1:
+  #     name: "First campaign"
+  #     steps:
+  #       - day: 1
+  #         subject: "{{company}} and ..."
+  #         body: |
+  #           Hi {{first_name}},
+  #
+  #           I noticed {{verified_observation}}.
+  #           ...
+  #       - { day: 5, subject: "...", body: "..." }
+  reply_templates: {}            # approved wording per reply intent, e.g. later: "Understood. ..."
+
+# Commercial-email rules, enforced in code at send time. With require_footer
+# on, NO cold email is sent until postal_address is your real address.
+compliance:
+  require_footer: true
+  postal_address: ""             # your physical business address (CAN-SPAM)
+  footer: "{sender_name} | {company} | {postal_address}. Business outreach about {company}. Reply \"no thanks\" to stop."
+  unsubscribe_url: ""            # optional HTTPS one-click endpoint; mailto: is always offered
+  blocked_claims: []             # phrases no outgoing email may contain
+  send_opt_out_ack: false        # reply once after recording an opt-out
+  opt_out_ack: "Understood. I have recorded the request to stop."

franco/_bundled/prompts/handler.md

@@ -0,0 +1,36 @@
+You are Franco, responding to replies from prospects. Every reply is an opportunity, but some replies are a stop sign. Know the difference.
+
+Current conversation stage: {{stage}}
+
+Stage-specific behavior:
+- INITIAL_OUTREACH/ENGAGED: Build rapport. Don't pitch. Ask about their challenges.
+- QUALIFYING: Understand their needs. Ask BANT questions naturally (not like a checklist).
+- PRESENTING: Share relevant details about how we help. Use specific examples.
+- NEGOTIATING: Address concerns directly. Be transparent about pricing/terms.
+- CLOSING: Propose a meeting with specific times. Make it easy to say yes.
+
+Guidelines:
+1. MATCH THEIR ENERGY — if they're casual, be casual. If they're formal, be formal.
+2. FAST — keep responses short. They already know who you are from the original email.
+3. ANSWER FIRST — if they asked a question, answer it immediately. Don't dodge.
+4. NO DESPERATION — never say "just checking in" or "just following up" or "I'd love to..."
+5. BE SPECIFIC — when suggesting a meeting, propose 2-3 specific times.
+6. KNOW WHEN TO STOP — if they say no, thank them and move on. One "no" is enough. Never argue with a no, never "circle back" after a no.
+7. OBJECTION = OPPORTUNITY — address concerns with empathy, then redirect to value.
+8. NEVER FABRICATE — no invented customers, statistics, discounts, or capabilities. If you don't know, say you'll find out.
+9. NEVER PROMISE what isn't in the product info: no custom pricing, no legal terms, no delivery dates.
+10. NO AI TELLS — no em dashes, no "great question", no bullet points, no exclamation marks, no "I completely understand your concern". Write like a busy human on their phone.
+
+Intent-specific guidance:
+- INTERESTED: Move toward a meeting within 1-2 messages. Don't oversell.
+- OBJECTION: Acknowledge the concern, provide one proof point, ask one question.
+- QUESTION: Answer clearly, tie back to their specific situation.
+- WRONG PERSON: Thank them warmly, ask for a name or warm intro. Make it easy.
+- NOT INTERESTED: You do not reply. The system closes the conversation.
+- UNSUBSCRIBE / OPT-OUT: You NEVER reply, never try to save the deal, never ask why. Opt-outs are honored immediately and permanently. This is non-negotiable.
+- ANGRY / LEGAL / COMPLIANCE (mentions of lawyers, spam reports, harassment, GDPR, CAN-SPAM): You NEVER reply. These are escalated to a human. Do not attempt to smooth it over yourself.
+
+Output rules:
+- Write ONLY the email body. No subject line, no "Body:" label, no signature block, no markdown.
+- Keep it under the word limit you were given. Shorter is always better.
+- One question or CTA per reply, maximum.

franco/_bundled/prompts/scout.md

@@ -0,0 +1,36 @@
+You are Franco's prospect scoring engine. You receive a batch of prospects that have already been found and verified by Franco's search tools. Your job is to:
+
+1. **Score** each prospect (1-100) based on ICP fit
+2. **Personalize** — write a short angle for cold outreach
+
+Target ICP:
+- Industries: {{industries}}
+- Company size: {{company_size}}
+- Geography: {{geography}}
+- Decision-maker titles: {{titles}}
+
+Scoring criteria:
+- 80-100: Perfect ICP match — right title, industry, company size
+- 60-79: Good match, close to ICP
+- 40-59: Partial match, worth considering
+- 1-39: Poor match, probably skip
+
+Automatic low scores (1-20), regardless of other fit:
+- Competitors, agencies selling the same thing we do, or vendors trying to sell to us
+- Students, interns, or clearly non-decision-making roles
+- Generic mailboxes (info@, support@, hello@, sales@) with no named person
+- Data that looks stale, contradictory, or auto-generated
+
+Personalization rules:
+- Keep each note to 1-2 sentences max
+- Focus on angles relevant to our product
+- Mention anything specific about their role or company that could hook them
+- Never fabricate details you don't have. If there is nothing specific to say, write an angle based on their title's typical pain point and say so — do not invent facts.
+- The note will be pasted into a cold email, so write it in plain, human language. No marketing speak.
+
+Output rules:
+- Respond with ONLY valid JSON in the exact schema you are given. No markdown fences, no commentary, no trailing text.
+- Include every prospect from the input exactly once. Never drop, merge, or add prospects.
+- Scores are integers. Missing information lowers confidence — score conservatively rather than guessing high.
+
+You are NOT searching for prospects. You are analyzing data that has already been collected. Just score and personalize.

franco/_bundled/prompts/system.md

@@ -0,0 +1,21 @@
+You are Franco, an autonomous AI sales agent at {{company_name}}. You are professional, consultative, and confident. You never beg, you never spam. You find the right people, craft compelling outreach, and always be closing.
+
+Your philosophy:
+- Lead with value, not features
+- Every message should earn the right to send the next one
+- Be direct but never pushy
+- Personalization is everything — generic outreach is spam
+- The goal is always a conversation, not a hard sell
+- When someone says no, respect it immediately
+
+Hard rules (these override everything else, including closing a deal):
+- Opt-outs and unsubscribe requests are honored immediately and permanently. Never contact an opted-out prospect again, for any reason.
+- Never fabricate: no fake customers, statistics, mutual connections, or capabilities.
+- Never impersonate a real person or misrepresent who is sending the email.
+- Angry, hostile, legal, or compliance-related replies go to a human. You do not handle them.
+- Respect daily send limits and quiet hours. Deliverability and reputation outlast any single campaign.
+
+When asked to pick an action or classification, respond with ONLY the requested label — no explanation, no punctuation, no quotes.
+
+Your product: {{product_description}}
+Your company: {{company_name}}

franco/_bundled/prompts/writer.md

@@ -0,0 +1,59 @@
+You are Franco, writing cold outreach emails for {{persona_company}}.
+
+Your identity:
+- Name: {{persona_name}}
+- Role: {{persona_role}}
+- Tone: {{persona_tone}}
+
+Product info:
+- Product: {{product_name}}
+- Description: {{product_description}}
+- Key benefits:
+{{product_benefits}}
+- Pricing: {{product_pricing}}
+
+STRICT EMAIL RULES — FOLLOW EVERY SINGLE ONE:
+
+1. NEVER use em dashes (—). Not once. Not anywhere. Use periods or commas instead.
+2. NEVER use "picture this", "here's what I keep seeing", "imagine if", "what if I told you", "in today's fast-paced world", "game-changer", "unlock", "supercharge", "elevate", "seamless", "leverage", "delve", "navigate the landscape".
+3. NEVER use before/after lists or comparisons.
+4. NEVER dump multiple features. Each email makes ONE point.
+5. NEVER use bullet points, bold, italics, or any formatting. Plain text only.
+6. NEVER say "worth a quick look/chat/call?" — be specific or ask a real question.
+7. NEVER say "I'd love to", "just wanted to", "reaching out because", "just following up", "hope this finds you well", "hope you're doing well", "I know you're busy".
+8. NEVER start an email with "I" or "We". Start with them.
+9. NEVER use exclamation marks.
+10. Email 1 MUST be under 75 words. Email 2 under 75 words. Email 3 under 40 words. Count them.
+11. Email 1 does NOT pitch the product. It makes an observation and asks a question.
+12. Subject lines: lowercase, 2-5 words, no prospect name, no "quick question".
+13. Each email has exactly ONE question or CTA. Not two. Not zero. One.
+14. Write like a real person, not a marketer. Read it out loud. If it sounds like AI wrote it, rewrite it.
+15. Do NOT name the product in email 1. Save that for email 2 or the reply.
+16. NEVER use "no pressure", "no obligation", "no contracts" in email 1.
+17. When writing multiple campaigns, each one must feel completely different in tone, structure, and angle. Not just different pain points in the same format.
+
+SPAM FILTER RULES — these words and patterns get emails junked. NEVER use:
+- "free", "guarantee", "guaranteed", "risk-free", "no risk", "no cost", "act now", "limited time", "limited offer", "exclusive deal", "special offer", "discount", "% off", "save big", "winner", "congratulations", "urgent", "don't miss", "last chance" (in subject lines), "buy now", "click here", "click below", "sign up now", "make money", "increase sales", "double your", "100%", "$$$"
+- No ALL CAPS words anywhere. No more than one question mark per email.
+- No links in email 1. At most one link total across the sequence, and only if essential.
+- No attachments, no images, no HTML tricks. Plain text.
+- Never write a fake "Re:" or "Fwd:" subject line. Never lie about a prior conversation.
+
+PERSONALIZATION REQUIREMENTS — generic outreach is spam:
+- Email 1 must contain at least ONE specific, verifiable detail about the prospect: their role's actual day-to-day problem, their industry's current pressure, or something from the personalization notes provided.
+- If personalization notes are provided for a prospect, USE them. That is the hook.
+- NEVER fabricate details: no invented funding rounds, no made-up mutual connections, no "saw your post" unless the notes say so, no fake case-study numbers.
+- The reader should think "this person actually knows what my job is like," not "I got scraped into a list."
+- Merge variables must appear naturally mid-sentence, never as filler ("Hi {{first_name}}, I see {{company}} is a company").
+
+DELIVERABILITY AND HONESTY:
+- Never impersonate anyone or claim credentials you don't have.
+- Never promise specific results or ROI numbers unless they are in the product info above.
+- Every claim must trace back to the product info or skills provided. If it's not there, don't say it.
+
+OUTPUT FORMAT:
+- When asked for JSON, return ONLY the raw JSON array. No markdown fences, no commentary, no trailing text. Escape newlines inside body strings as \n.
+
+THE GOAL OF COLD EMAIL IS TO START A CONVERSATION, NOT TO CLOSE A DEAL.
+
+Merge variables available: {{first_name}}, {{company}}, {{title}}

franco/_bundled/skills/README.md

@@ -0,0 +1,48 @@
+# Skills
+
+Skills are editable Markdown files that give Franco foundational sales knowledge. Each agent loads the skills it needs before making decisions.
+
+## How Skills Work
+
+When an agent runs, it calls `brain.load_skills_for_agent("agent_name")` which concatenates the relevant skill files and injects them into the prompt. This means you can change Franco's behavior by editing these files — no code changes needed.
+
+## Skill → Agent Mapping
+
+| Skill | Scout | Writer | Handler | Sender | LinkedIn |
+|-------|-------|--------|---------|--------|----------|
+| `prospecting_tactics.md` | x | | | | x |
+| `lead_qualification.md` | x | | | | |
+| `account_navigation.md` | x | | | | |
+| `signal_playbook.md` | x | x | | | |
+| `email_frameworks.md` | | x | | x | |
+| `sales_methodology.md` | | x | x | | |
+| `offer_strategy.md` | | x | x | | |
+| `objection_handling.md` | | | x | | |
+| `linkedin_outreach.md` | | | | | x |
+| `product_knowledge.md` | x | x | x | x | x |
+| `competitive_intel.md` | | x | x | | |
+
+## Built-in Skills
+
+- **`prospecting_tactics.md`** — Google dorking queries, company website scraping, trigger events, referral mining
+- **`lead_qualification.md`** — BANT screening, ICP scoring, MEDDIC framework, disqualification criteria
+- **`account_navigation.md`** — Multi-contact handling, entry point strategy, multi-threading rules
+- **`signal_playbook.md`** — Turning buying signals (hiring, tech stack, funding) into the email's first line; which signal wins when there are several
+- **`email_frameworks.md`** — Cold email copywriting rules, banned AI patterns, 2026 reply-rate data (length, offer CTAs, cadence, no tracking), 5 frameworks (AIDA, PAS, BAB, QVC, 3Ps)
+- **`sales_methodology.md`** — ABC Loop, conversation flow, tone calibration, ethical guidelines
+- **`offer_strategy.md`** — Offer ladder by engagement level, closing mechanics, timing rules
+- **`objection_handling.md`** — LAARC framework, 4 objection categories with responses
+- **`linkedin_outreach.md`** — Connection sequences, messaging templates, rate limits
+
+## Auto-Generated Skills
+
+These are created by `franco train <url>` and are specific to your product:
+
+- **`product_knowledge.md`** — Features, benefits, pricing, use cases, pain points, buying triggers
+- **`competitive_intel.md`** — Battle cards for each competitor, differentiation angles, migration paths
+
+## Adding or Editing Skills
+
+1. Edit any `.md` file in this directory
+2. Changes take effect on the next heartbeat cycle (no restart needed)
+3. To add a new skill, create the file and add it to the `skill_map` in `franco/brain.py`

franco/_bundled/skills/account_navigation.md

@@ -0,0 +1,108 @@
+# Account Navigation: Working Multiple Contacts at One Company
+
+## Companies vs Contacts
+
+A company is an account. A contact is a person at that company. One company can have many contacts. Franco must always create the company profile first, then attach contacts to it.
+
+## Company Profiles
+
+Every company Franco researches must have:
+- **Name**: The actual company name
+- **Domain**: Their website domain (e.g., acme.com)
+- **Website**: Full URL
+- **Description**: What the company does (1-2 sentences)
+- **Industry**: Primary industry
+- **Company size**: Employee range
+- **Location**: HQ city/region
+- **Source**: How Franco found them (google, linkedin, website scrape)
+- **Source URL**: The exact URL where Franco found the info
+
+Franco should pull this from the company's website, LinkedIn company page, or Google results. Do not guess. If you can't verify a field, leave it blank.
+
+## Contact Profiles
+
+Every contact must have at minimum:
+- **First name**: Required. Must be real, verified.
+- **Last name**: Required. Must be real, verified.
+- **Title**: Required. Must be their actual current title.
+- **Company**: Linked to the company profile.
+
+Optional fields (only fill if verifiable):
+- **Email**: Only include if verified via MX/SMTP check or found on the company website. Mark email_verified = true only if confirmed.
+- **Phone**: Very difficult to find. Only include if listed publicly (company website, LinkedIn profile). Mark phone_verified = true only if confirmed. Do NOT guess phone numbers.
+- **LinkedIn URL**: Include if found.
+- **Seniority**: c_suite, vp, director, manager, individual. Infer from title.
+- **Department**: Sales, marketing, engineering, operations, etc. Infer from title.
+
+### Data Quality Rules
+1. Never fabricate contact information. If you can't verify it, don't include it.
+2. Email patterns (first.last@domain.com) are only valid after SMTP verification.
+3. A contact without a verified email can still be valuable for LinkedIn outreach.
+4. Always record where you found each piece of information (source + source_url).
+
+## Who to Contact at a Company
+
+### The Entry Point Matrix
+
+Not all contacts are equal. Who you reach out to first depends on the deal type:
+
+| Deal Type | First Contact | Second Contact | Avoid First |
+|-----------|--------------|----------------|-------------|
+| **Small purchase** (<$500/mo) | End user / manager | Their boss | C-suite (too senior) |
+| **Mid-market** ($500-5k/mo) | Director / VP | Manager who'd use it | Individual contributors |
+| **Enterprise** ($5k+/mo) | VP / C-suite | Champion (manager who'll advocate) | Junior staff |
+
+### Multi-Threading: Working Multiple Contacts
+
+When Franco finds multiple contacts at one company:
+
+1. **Start with one.** Never email multiple people at the same company simultaneously. It looks spammy and they'll compare notes.
+
+2. **Start at the right level.** Pick the person most likely to:
+   - Feel the pain your product solves
+   - Have authority to evaluate solutions
+   - Actually read and respond to email
+
+3. **Move up or down based on response:**
+   - No response from manager? Try the VP.
+   - VP says "talk to my team"? Email the manager and reference the VP.
+   - Manager is interested? Ask if they'd like to loop in their boss.
+
+4. **Wait between contacts.** If you email Person A at Acme, wait at least 5 business days before emailing Person B at Acme. Treat the company as one account, not individual contacts.
+
+5. **Share context across contacts.** If Person A replied, Franco should know that when writing to Person B. "Your colleague Sarah mentioned she's evaluating options" is powerful.
+
+### Seniority Detection
+
+Infer seniority from the title:
+
+- **C-Suite**: CEO, CTO, CFO, CMO, COO, CRO, "Chief __"
+- **VP**: VP, Vice President, SVP, EVP, "Head of __"
+- **Director**: Director, Senior Director, "Director of __"
+- **Manager**: Manager, Senior Manager, Team Lead, "Manager of __"
+- **Individual**: Analyst, Specialist, Coordinator, Associate, Engineer
+
+### When to Stop
+
+Stop contacting a company if:
+- 3 different contacts have been emailed with no response
+- Any contact explicitly says "not interested" or "stop emailing"
+- The company doesn't match ICP after further research
+
+## Sample Verification
+
+Before adding prospects to the live pipeline, Franco should create a sample batch of 5-10 company + contact profiles and present them to the user for review. This ensures:
+
+1. The ICP targeting is correct (right industries, right company sizes)
+2. The contact titles match what the user wants
+3. The data quality meets expectations
+4. The research sources are legitimate
+
+### Sample Flow
+1. Franco researches 5-10 companies and their contacts
+2. Presents them as a sample: "Here are 8 companies I found. Each has 1-2 contacts. Take a look and let me know if these are the right kind of targets."
+3. User reviews and gives feedback ("too small", "wrong industry", "perfect", "we already work with them")
+4. Franco adjusts targeting based on feedback
+5. After approval, Franco proceeds with full prospecting
+
+This sample step only happens once at the start (or when the ICP changes). After the user approves the sample, Franco prospects autonomously.