hermes-agent/optional-skills/security/unbroker/references/methods.md

Opt-out method playbooks

How the agent executes each broker optout.method using native Hermes tools. Obey least-disclosure: submit only the subject's OWN identifiers, and only the fields a broker's official channel requires (pdd.py plan lists them per broker). Never disclose more than that, and confirm a listing is really the subject's before acting on any THIRD-PARTY / indirect record (see "Distinguish the subject" and "Indirect exposure"). See the posture section below for when a confirmed listing is NOT a prerequisite.

Autonomy: pdd.py next <subject> sequences all of this - it decides which method applies, orders parents first, and routes human-only work to the digest. In autonomy=full (default), execute its actions without pausing per submission; the consent recorded at intake is the authorization. These playbooks are the HOW for each action type.

Opt-out posture: blind opt-out is the default (not a fallback)

Operator-directed posture: submit an opt-out or deletion on EVERY site that exposes an accessible removal channel, even when a listing was not first confirmed - whichever of opt-out / deletion is optimal per site. Do not hand back a to-do list of "we could not search these."

• Why it is sound (does NOT violate least-disclosure): a blind opt-out sends only the subject's own identifiers to the broker's own official removal channel. You are giving the broker the subject's data to remove it, not exposing new data or acting on a third party. (Third-party / indirect records are the exception: those still require confirming the exposure first.)
• The opt-out flow doubles as the authoritative search. Guided flows that match on email + DOB + legal name and then say "no results" are a stronger not_found than any scrape - the broker ran its own matcher against real identifiers. On guided-flow sites, "run the opt-out" and "search" are one action (e.g. CheckPeople; see site-playbooks.md).

Blocked form -> default to the cited rights-email (the headline rule)

When a removal form is automation-hostile (hard CAPTCHA, a Cloudflare wall that will not clear, a JS paywall funnel), default to the broker's cited rights-request email rather than recording blocked and deferring to a human - unless there is an easy in-browser solve. Decision order per site:

1. Easy in-browser solve? (one-click remove; a guided flow whose CAPTCHA auto-clears on the residential browser; plain email-verify) -> do it in the browser.
2. Form blocked but a cited rights-email exists? -> send a deletion/opt-out email from the operator's webmail (name + state + contact email only). This is now preferred over recording blocked.
3. No easy solve AND no cited email -> blocked (or human_task_queued with the exact end-state).
4. Only lane requires gov-ID / physical mail -> do NOT pursue autonomously (least-disclosure); surface as a human decision.

"Cited" = published by the broker itself (privacy policy / opt-out page / a working deletion alias). Do not email addresses sourced only from third-party blogs or Reddit. Per-site lanes and gotchas are pre-recorded in references/site-playbooks.md so future runs execute rather than re-derive.

Triage an external OSINT list before scanning

When cross-checking any external "people OSINT" catalog, separate first-party brokers (removal targets) from meta-search / link-out aggregators (no first-party data -> no-ops, do not file opt-outs), cluster front-ends (covered by a parent, e.g. addresses.com -> Intelius), and non-broker tools / APIs / wrong-jurisdiction (skip). The skip-lists live in site-playbooks.md.

Scan ladder (all methods)

Build the exposure map cheapest first (on a site with an accessible removal channel you may still blind-opt-out even if the scan is inconclusive - see the posture section above). Run every search_vectors entry from pdd.py plan (each name x location, phone, email, and address the broker's search.by supports) - different vectors surface different listings for the same person; dedupe found URLs.

1. web_extract on the broker search.url (fast HTML -> markdown). Look for search.match_signal. Build per-vector URLs from search.url_patterns and heed search.url_format_quirks (see below). 1b. site: search-engine probe (cheap, do it early and in parallel). web_search with site:<broker-domain> "First Last" (add a city/ZIP or a unique phone/address to cut namesake noise) often returns the exact profile-slug URL in one shot - which both confirms the listing exists AND hands you the opaque /find/person/<id> or /p/<slug> URL you'd otherwise have to derive. Two big wins seen in the field: (a) it disambiguates namesakes fast - the SERP snippet shows age/city so you can tell the subject from a same-name relative before fetching anything; and (b) a broad "First Last" <ZIP OR unique-address> search (no site:) surfaces brokers not yet in your DB (e.g. information.com, peoplefinders.com) - record those as bonus exposures. Note: empty site: results are INCONCLUSIVE (many broker pages aren't indexed / are noindex), not not_found.
2. If the page is JS-rendered or returns nothing useful, browser_navigate + browser_snapshot (and browser_type/browser_click to run the site's search box).
3. If blocked by stealth/Cloudflare, use the scrapling skill via terminal. If the broker record has search.antibot set (e.g. datadome), results are behind a device-check CAPTCHA: a cloud/stealth browser (Browserbase) or scrapling may get through; if none is available, do not burn attempts - pdd.py record <subject> <broker> blocked and move on (a re-scan with a stealth backend can pick it up later). 3b. Operator-browser path (the reliable unblock for anti-bot sites). Cloudflare/DataDome key on datacenter IPs + headless fingerprints, so web_extract, the proxyless agent browser, and even a cloud browser often fail - but the operator's own everyday browser (residential IP, real fingerprint) sails straight through. For any blocked site, hand the operator a paste-ready search URL (built from search.url_patterns), give them the identity anchors to judge by (current
   • prior addresses, age, a distinguishing detail) and the namesake/relative watch-list, and ask for the verdict or a screenshot (the agent can read screenshots). This is a first-class scan path, not a fallback - treat the operator's live check as authoritative and record the real verdict (found / not_found / indirect_exposure), citing scanned_via: operator_browser. Same for opt-out forms the agent's browser can't reach: guide the operator field-by-field (least-disclosure), pausing before submit. (This is exactly why the same trick clears email-verification links the agent can't open - see the Verification loop.)
4. Capture evidence: save listing URLs and a browser screenshot into the subject's evidence/ dir, then pdd.py record <subject> <broker> found --found true --evidence '{"listing_urls":[...]}'.

If a listing genuinely does not exist: pdd.py record <subject> <broker> not_found and move on.

A 404 (or empty body) is INCONCLUSIVE, not "not_found"

A constructed search URL that 404s almost always means the URL pattern is wrong, not that the person is absent. Never record not_found off a 404. Instead:

1. Re-check the broker's search.url_patterns / url_format_quirks and rebuild the URL.
2. Fall back to the on-site search box: browser_navigate to the search page, browser_type the raw query, browser_click Search, then read the canonical result URL the site lands on.
3. Only after the site's own search returns an empty result set do you record not_found.
4. If a pattern was wrong, fix it in references/brokers/<id>.json (url_patterns + url_format_quirks) so the next run is correct - see the rule below.

Log URL/format quirks for every site you scrape

Whenever you discover how a broker's URLs are actually shaped (path layout, hyphen-vs-slash joins, whether ZIP is required, abbreviation handling, query-param search, anti-bot gating), record it in that broker's references/brokers/<id>.json under search.url_patterns (the templates) and search.url_format_quirks (the gotchas, including which forms 404). Bump last_verified. This makes the deterministic URL path reliable across runs and subjects instead of rediscovered each time. If the opt-out form's real requirements differ from the record (extra required fields, a CAPTCHA, an account), fix optout.requires / optout.inputs / optout.tier too - those drive tier selection and least-disclosure. Log opt-out mechanics gotchas (a broker that needs a profile URL but doesn't expose one for the subject, an email-only fallback, an authorized-agent toggle) in optout.quirks - the planner surfaces these as optout_quirks per broker. Example: Radaris sometimes shows the subject only as a static address-table row with no "View Profile" link, so /control-privacy (which needs a profile URL) can't be used - fall back to optout.email rather than submitting a namesake's URL.

Distinguish the subject from namesakes and relatives

People-search sites are dense with namesakes and family clusters. Before recording found, confirm the record is the subject themselves (corroborate via DOB, a known current/prior address, or the identifier you searched). Two non-removable patterns to record as evidence but NOT as the subject's own listing:

• Namesake: same name, different person (different DOB/location with no overlap). Not the subject.
• Relative record: the listing is about a different person (a relative) and merely names the subject in a "Family" field, or carries the subject's email/phone as a secondary datum. This is a third party's record - the consent gate correctly blocks acting on it. See "Indirect exposure" in the web_form section for what the subject can still request.

Two more false-positive traps that a naive scan records as found when it should not:

• Property record != PII (address-anchored sites). Reverse-address / property sites (rehold, clustrmaps-style) can match on a public property record (build year, beds/baths, last sale price, incidents) without exposing the subject's personal info - the resident/owner NAME is behind a "View full report" paywall/signup. Distinguish "this address exists in a public property DB" (non-removable, not_found) from "the subject's personal profile is displayed" (removable, found). Record found ONLY if a resident name matching the subject is publicly shown; an address-only match is not_found - there is nothing to opt out of, and public property records are not removable anyway. See rehold.json search.match_signal_notes.
• SEO-templated title/H1 fakes a "found". Many people-search sites auto-insert the query into the page <title>, H1, and intro copy ("FREE public records found for {Name} in {City}", "Over 100+ FREE public records found for {Name}"). That echo is templating, not a result - the actual result cards are often unrelated namesakes in other states. A match_signal on title/intro text yields false positives. Require a real result card corroborated by the subject's address or DOB, and ignore the templated title/intro/H1 entirely. See truepeoplesearch.json / fastpeoplesearch.json search.match_signal_notes.

Both are why the parent re-verifies every found before acting rule is load-bearing (pdd.py show <subject> <broker> reads back a subagent's recorded evidence so the parent can re-verify without re-deriving the listing URL). If a found turns out to be a false positive, correct it with a fresh record ... not_found carrying an evidence note explaining the retraction.

web_form

1. browser_navigate to optout.url; browser_snapshot to read the form.
2. Fill only the planned disclosure_fields with browser_type/browser_click; for profile_url, paste the confirmed listing URL from evidence.
3. Submit; browser_snapshot to confirm the success state; screenshot to evidence/.
4. pdd.py record <subject> <broker> submitted --disclosed <field> --disclosed <field> --channel web_form.
5. If the broker requires email verification, follow Verification loop below.

Indirect exposure (named as a relative / your email on someone else's record)

You asked the right question: if a broker lists a relative and names you in their "Family" field, or shows your email/phone on their record, that IS personal information about you - even though the record's primary subject is a third party. Resolve it in two distinct lanes:

• The self-service opt-out form does NOT cover this. That form removes a record whose primary subject is you. It has no notion of "scrub my identifiers from this other person's record," and submitting it with the relative's address to force a match would be (a) disclosing data the listing doesn't tie to you and (b) acting on a third party's record. Don't. The consent gate exists to stop exactly that.
• What you CAN do - a targeted "delete my personal information" request (CCPA 1798.105 / GDPR Art.17). These rights attach to your personal information wherever the business holds it, including as a data point on another person's profile. So the subject may email the broker's privacy address and request suppression of their own specific identifiers (this email address, this phone number, my name in family/relative associations), citing the relative listings as the locations. This is a narrower request than a full opt-out and does not require the relative's consent - you are only asking them to delete data about you. Use render-email with the ccpa/gdpr template, list only the subject's own identifiers + the URLs where they appear, and record it as a normal submitted → awaiting_processing email case. Verify by re-scanning those identifier vectors (email/phone) after the statutory window - confirmed_removed only when the subject's identifier no longer appears.
• Caveat: the broker may decline to alter a third party's record beyond removing your specific identifiers, and "your name in a family graph" can be derived from public records they'll re-list. Note residual exposure in the report rather than marking a clean removal. (Operational guidance, not legal advice.)

email

pdd.py send-email <subject> <broker> --listing <url> [--kind ccpa|gdpr|ccpa_indirect] always does the deterministic parts (recipient locked to an address the broker record declares, refusing anything else; --listing mandatory; records submitted, logs disclosure, stamps next_recheck_at). How it actually sends depends on email_mode:

1. browser mode (no password, autonomous): the command returns a recipient-locked compose payload (to/subject/body). Compose a NEW message in the operator's logged-in webmail via browser_* (paste compose.body exactly, disclosing nothing beyond it) and send. No credentials stored. Requires the inbox signed in in the browser Hermes uses.
2. programmatic mode (SMTP creds): the command SMTP-sends it directly, no human.
3. draft_only fallback: pdd.py render-email <subject> <broker> --listing <url>; a digest entry tells the operator to send it, and the agent records submitted --channel email afterward.

Then follow the Verification loop if the broker emails a confirmation link.

Verification loop (email_verification brokers)

• browser mode (autonomous, no password): open the broker's confirmation email in the operator's webmail (browser_*), then pdd.py verify-link <subject> <broker> --text '<email body>' returns the anti-phishing-scored link. browser_navigate it in the same browser (several brokers, e.g. PeopleConnect, bind the session to the browser that opens the link), finish the flow, record awaiting_processing.
• programmatic mode (IMAP): pdd.py poll-verification <subject> polls IMAP for every in-flight case, extracts the link (anti-phishing scored: only opt-out-looking links on the broker's own domains), and auto-advances submitted → verification_pending. Then browser_navigate the link in the agent's own browser, finish the flow, record awaiting_processing.
• draft_only: the digest tells the operator to click the link in the subject's inbox; the agent records awaiting_processing on their word.
• Either way, the due queue (pdd.py due) brings the case back after the broker's processing window for the verifying re-scan; only that re-scan justifies confirmed_removed.

phone_callback (e.g. Whitepages)

Submit the web form, then the site places an automated call with a numeric code. If the operator is available to read the code, capture it and complete the form (T2). Otherwise queue a human task.

phone (voice menu) / fax / mail / gov_id -> human task (T3)

Do not attempt to automate. Create a todo task and pdd.py record <subject> <broker> human_task_queued with exact instructions and an explicit withhold list (never SSN; never a driver's-license number unless the subject chooses to and crosses out the ID number). Capture the confirmation reference back into the ledger when the operator completes it.

captcha

Default: soft/managed CAPTCHAs clear automatically. The recommended baseline backend is the Browserbase cloud browser (setup --auto selects it when BROWSERBASE_API_KEY is set). Being a real browser on a residential IP, it passes managed challenges - Cloudflare Turnstile, hCaptcha / reCAPTCHA checkbox - as normal operation, so those brokers stay T1 and you just proceed. This is not CAPTCHA solving: no solver service, no fingerprint spoofing.

Only a hard challenge the browser genuinely can't pass (interactive image grids, behavioral scoring that flags the session) becomes a fallback: record ... blocked and requeue it for the stealth/operator-browser pass (methods.md → scan ladder 3b - the operator's own residential browser is the reliable unblock). Without a cloud browser configured, soft-CAPTCHA brokers drop to T2 and become human tasks. Never use a third-party CAPTCHA-defeating service.

CAPTCHA policy, clarified (on a consenting first-party opt-out)

• Do NOT defeat behavioral / token challenges: a Cloudflare Turnstile that will not auto-clear, DataDome, and "slide-to-verify" gesture-entropy sliders (the InfoPay lane). These are hard stops -> take the email lane (rule above) or record blocked.
• Acceptable to solve on the subject's own first-party opt-out: a static distorted-text image CAPTCHA (read it with the vision tool) or a plain arithmetic CAPTCHA ("8 + 13 = ?"). That is OCR / arithmetic on a consenting removal, not evasion of a bot-detection system.
• But if the site then rejects the whole submission ("Captcha verification failed / feature not available") after a correct answer, it is fingerprinting the automation itself, not grading the answer -> stop, do not loop (e.g. PrivateRecords' distorted-text-THEN-arithmetic double gate). If no cited rights-email exists, that is a genuine blocked.

Browser backends: scan vs execute

Two different jobs need two different browsers. Getting this wrong is the single biggest cause of a run stalling in Phase 2.

• Phase 1 (scan, read-only): a cloud stealth browser (Browserbase) or the scrapling skill is ideal. On a residential IP with a real fingerprint it passes managed challenges (Cloudflare Turnstile, hCaptcha checkbox) and reads anti-bot people-search pages that web_extract and the proxyless agent browser cannot. This is what the skill's browser_backend setting governs (auto picks Browserbase when BROWSERBASE_API_KEY is present - now also read from $HERMES_HOME/.env, not just the shell env, so doctor/setup --auto detect the key Hermes already loads for its own tools).
• Phase 2 (execute: opt-out forms, webmail sends, session-bound multi-step gates): the work must run in the operator's own everyday browser - real fingerprint, residential IP, AND the operator's logged-in sessions. A headless cloud browser is the WRONG default here for two reasons: (1) it is not signed into the operator's webmail, so browser-mode email sends and confirmation-link opens have no inbox to act in; and (2) it is itself Cloudflare/DataDome-gated on exactly the multi-step flows that matter (e.g. PeopleConnect guided-mode, whose verify link is session- and device-bound to the browser that opens it - a cloud browser both fails the challenge and breaks the binding).
• How to drive the operator's browser (CDP). Point Hermes's browser tools at the operator's real Chrome over the DevTools protocol: launch chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.hermes/chrome-debug" and connect the browser backend to 127.0.0.1:9222. Use a dedicated debug profile (chrome-debug), NOT the operator's Default Chrome profile, and have the operator sign into their webmail (and any needed broker accounts) in that profile once. That single browser then carries residential IP + real fingerprint + logged-in sessions, which is precisely what Phase-2 flows need. (This is a Hermes-side browser setup, not a pdd config value; browser_backend above only selects the Phase-1 scan browser.) The skill launches this for you: pdd.py cdp finds a Chrome/Chromium/Brave/Edge binary, starts it detached on the dedicated profile, waits for the debug port, and prints the CDP endpoint (webSocketDebuggerUrl). pdd.py cdp --check reports whether a debug browser is already live (and never launches a second one); pdd.py cdp --print just emits the exact command for the operator to run themselves. Point the browser tools at the endpoint it returns.
• Always-available fallback: if no CDP browser is wired up, use the operator-in-the-loop path (scan ladder 3b) - hand over paste-ready URLs and field-by-field least-disclosure guidance, pausing before submit. It never fails; it just needs a human present.

Backend precedence, most to least autonomous: operator Chrome over CDP (Phase 2, hands-off once the profile is signed in) > Browserbase cloud stealth (Phase 1 scanning, plus managed-captcha forms that need no login) > proxyless agent browser (only already-unblocked sites) > operator-in-the-loop (paste-ready URLs; the last-resort unblock that always works).

Ownership clusters - DO PARENTS FIRST (playbooks live in the broker records)

Many brokers are resold shells of a few parents, so one parent removal clears a whole cluster of children (see owns in each record). In Phase 2 you MUST work the cluster parents first, then the standalone listings - doing a child before its parent wastes a submission the parent would have covered. pdd.py plan <subject> --batch orders the found group parents-first and emits a parent_playbook whose steps come verbatim from each record's optout.playbook - the single source of truth, field-verified, updated as live runs discover mechanics. What follows is the operating doctrine; the exact steps are in references/brokers/<id>.json.

Deletion USUALLY beats suppression, email lanes beat forms -- but check the record. Each parent record carries a structured optout.deletion lane (via: in_flow | email | email_followup, a privacy address, and prefer). The autopilot routes accordingly, and when deletion.prefer is false it emits prefer_suppression instead of prefer_deletion:

• in_flow (PeopleConnect, prefer: false): the deletion control lives inside the web flow, but for this cluster it is the WRONG lever for search-visibility (see the exception below). Complete the suppression flow and maintain it; do not press Delete unless the goal is a data-purge.
• via: email (Whitepages): the fully-autonomous lane - send-email the request (residency-picked kind: CCPA for US-CA, GDPR for EU/UK, generic otherwise), then poll-verification for their reply and answer identity questions with least-disclosure. This is also the rescue lane: any broker whose form demands a phone-callback/gov-ID/account but that declares a deletion email gets routed here instead of the human digest.
• email_followup (BeenVerified, Spokeo): the opt-out form is the fast primary (it clears the listing), and the playbook then sends a right-to-delete email for full erasure beyond suppression.

Verified parent facts (live-checked 2026-07-02; details + steps in the records):

• Intelius/PeopleConnect (~15+ sites in one flow) -- EXCEPTION to deletion-beats-suppression. Portal entry asks only email + consent → verify link is session-bound to the browser that opens it → guided-mode. Complete the SUPPRESSION flow and keep the account on file: suppression is the do-not-display list that removes you. Per their privacy-center, 'DELETE MY USER DATA' deletes your suppressions and does NOT stop the sites from showing you (public records re-list), so use it only for a deliberate data-purge. privacy@peopleconnect.us is the rights-request address for that path; published metrics: 33.5k deletion requests, median response < 1 day.
• Whitepages: privacyrequest@whitepages.com (or the Zendesk form) handles removal + CCPA deletion without the phone-callback tool - that phone call is only required by the automated tool. One removal also drops "all known connected listings". ≤15 days; check 411.com + Premium.
• BeenVerified: opt-out tool (footer "Do Not Sell" link → /svc/optout/search/optouts) + email verification; one opt-out per email address. Then privacy@beenverified.com deletion follow-up - controller is The Lifetime Value Co., so name their sister properties (NeighborWho, Ownerly, NumberGuru, Bumper) in the same request, and verify each separately.
• Spokeo: form takes ONE listing URL at a time and each listing must be opted out individually - collect every listing URL from all search vectors first, then submit one opt-out per URL. 24-48h processing. privacy@spokeo.com for full deletion beyond free-search suppression.

After each parent removal is confirmed, re-scan its children before submitting anything for them - usually they drop out and need no separate opt-out.

Any other parent

A parent without a hand-verified optout.playbook gets synthesised steps from its structured record (URL/email, requires flags, deletion lane, notes/quirks). Follow those, and write what you learn back into references/brokers/<id>.json (optout.playbook, optout.deletion, quirks, last_verified) so the next run is exact - that file, not this one, is where per-broker knowledge accrues.