chore: import upstream snapshot with attribution

docs/source/use-cases/crypto.rst

@@ -0,0 +1,147 @@
+.. _use-case-crypto:
+
+Cryptocurrency & Web3 Investigations
+=====================================
+
+Blockchain transactions are public, but the people behind wallets are not. Maigret helps bridge this gap by finding Web3 accounts tied to a username, revealing the person behind a pseudonymous crypto persona.
+
+Why it matters
+--------------
+
+Crypto investigations often start with a wallet address or an ENS name but hit a wall — the blockchain tells you *what* happened, not *who* did it. A username, however, is reused across platforms. If someone trades on OpenSea as ``zachxbt`` and posts on Warpcast as ``zachxbt``, Maigret connects the dots and builds a full profile.
+
+Common scenarios:
+
+- **Scam attribution.** A rug-pull promoter uses the same alias on Fragment (Telegram username marketplace), OpenSea, and a personal blog.
+- **Sanctions compliance.** Verifying whether a counterparty's online footprint matches known sanctioned individuals.
+- **Due diligence.** Before an OTC deal or DAO vote, checking whether the other party has a consistent online presence or is a freshly created sockpuppet.
+- **Stolen funds tracing.** A stolen NFT appears on OpenSea under a new account — but the username matches a Warpcast profile with real-world links.
+
+Supported sites
+---------------
+
+Maigret currently checks the following crypto and Web3 platforms:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Site
+     - What it reveals
+     - Notes
+   * - **OpenSea**
+     - NFT collections, trading history, profile bio, linked website
+     -
+   * - **Rarible**
+     - NFT marketplace profile, collections, listing history
+     - Complements OpenSea for NFT attribution across marketplaces
+   * - **Zora**
+     - Zora Network profile, minted NFTs, creator activity
+     - Ethereum L2 creator platform; useful for on-chain art attribution
+   * - **Polymarket**
+     - Prediction-market profile, positions, public portfolio P&L
+     - Useful for political/financial prediction attribution
+   * - **Warpcast** (Farcaster)
+     - Decentralized social profile, posts, follower graph, Farcaster ID
+     - Every Farcaster ID maps to an Ethereum address via the on-chain ID registry
+   * - **Fragment**
+     - Telegram username ownership, TON wallet address, purchase date and price
+     - Valuable for linking Telegram identities to TON wallets
+   * - **Paragraph**
+     - Web3 blog/newsletter, ETH wallet address, linked Twitter handle
+     - Richest cross-platform data among crypto sites
+   * - **Tonometerbot**
+     - TON wallet balance, subscriber count, NFT collection, rankings
+     - TON blockchain analytics
+   * - **Spatial**
+     - Metaverse profile, linked social accounts (Discord, Twitter, Instagram, LinkedIn, TikTok)
+     - Rich cross-platform links
+   * - **Revolut.me**
+     - Payment handle: first/last name, country code, base currency, supported payment methods
+     - Not strictly Web3, but widely used by crypto OTC traders for fiat off-ramps; the public API returns structured KYC-adjacent data
+
+Real-world example: zachxbt
+---------------------------
+
+`ZachXBT <https://twitter.com/zachxbt>`_ is a well-known on-chain investigator. Let's see what Maigret can find from just the username ``zachxbt``:
+
+.. code-block:: console
+
+   maigret zachxbt --tags crypto
+
+Maigret finds 5 accounts and automatically extracts structured data from each:
+
+**Fragment** — confirms the Telegram username ``@zachxbt`` is claimed, reveals the TON wallet address (``EQBisZrk...``), purchase price (10 TON), and date (January 2023).
+
+**Paragraph** — the richest result. Returns the real name used on the platform (``ZachXBT``), bio (``Scam survivor turned 2D investigator``), an Ethereum wallet address (``0x23dBf066...``), and a linked Twitter handle (``zachxbt``). The ``wallet_address`` field is especially valuable — it directly links the pseudonym to an on-chain identity.
+
+**Warpcast** — Farcaster profile with a Farcaster ID (``fid: 20931``), profile image, and social graph (33K followers). Every Farcaster ID is tied to an Ethereum address via the on-chain ID registry, so this is another on-chain anchor.
+
+**OpenSea** — NFT marketplace profile with bio (``On-chain sleuth | 10x rug pull survivor``), avatar (hosted on ``seadn.io`` with an Ethereum address in the URL path), and a link to an external investigations page.
+
+**Hive Blog** — blockchain-based blog account created in March 2025. Low activity (1 post), but confirms the username is claimed across blockchain ecosystems.
+
+From a single username, Maigret produces:
+
+- **2 wallet addresses** — one TON (from Fragment), one Ethereum (from Paragraph)
+- **1 confirmed Twitter handle** — ``zachxbt`` (from Paragraph)
+- **1 Telegram username** — ``@zachxbt`` (from Fragment)
+- **1 external link** — ``investigations.notion.site`` (from OpenSea)
+- **Social graph data** — 33K Farcaster followers, blog activity timestamps
+
+This is enough to pivot into blockchain analysis tools (Etherscan, Arkham, Nansen) using the wallet addresses, or into social media analysis using the Twitter handle.
+
+Workflow: from username to wallet
+---------------------------------
+
+**Step 1: Search crypto platforms**
+
+.. code-block:: console
+
+   maigret <username> --tags crypto -v
+
+Review the results. Pay attention to:
+
+- **Fragment** — if the username is claimed, you get a TON wallet address directly.
+- **Paragraph** — blog profiles often contain an ETH address and a Twitter handle.
+- **Warpcast** — Farcaster IDs map to Ethereum addresses via the on-chain registry.
+- **OpenSea** — avatar URLs sometimes contain wallet addresses in the path.
+
+**Step 2: Expand with extracted identifiers**
+
+Maigret automatically extracts additional identifiers from found profiles (real names, linked accounts, profile URLs) and recursively searches for them. This is enabled by default. If Maigret finds a linked Twitter handle on a Paragraph profile, it will automatically search for that handle across all sites.
+
+**Step 3: Cross-reference with non-crypto platforms**
+
+The real power is connecting crypto personas to mainstream accounts. Drop the tag filter:
+
+.. code-block:: console
+
+   maigret <username> -a
+
+This checks all 3000+ sites. A match on GitHub, Reddit, or a forum can reveal the person behind the wallet.
+
+Workflow: from wallet to identity
+---------------------------------
+
+If you start with a wallet address rather than a username, you can use complementary tools to get a username first:
+
+1. **ENS / Unstoppable Domains** — resolve the wallet address to a human-readable name (``vitalik.eth``). Then search that name in Maigret.
+2. **Etherscan labels** — check if the address has a public label (exchange, known entity).
+3. **Fragment** — search the TON wallet address to find which Telegram usernames it purchased.
+4. **Arkham Intelligence / Nansen** — blockchain attribution platforms that may tag the address with a known identity.
+
+Once you have a username candidate, feed it to Maigret.
+
+Tips
+----
+
+- **Username reuse is the #1 signal.** Crypto-native users often reuse their ENS name (``alice.eth``) or a variation (``alice_eth``, ``aliceeth``) across platforms. Try all variations.
+- **Fragment is uniquely valuable** because it directly links Telegram usernames to TON wallet addresses — a rare on-chain / off-chain bridge.
+- **Warpcast profiles are Ethereum-native.** Every Farcaster account is tied to an Ethereum address via the ID registry contract. If you find a Warpcast profile, you implicitly have a wallet address.
+- **Paragraph often has the richest data** — wallet address, Twitter handle, bio, and activity timestamps in a single API response.
+- **Use** ``--exclude-tags`` **to skip irrelevant sites** when you're focused on crypto:
+
+  .. code-block:: console
+
+     maigret alice_eth --exclude-tags porn,dating,forum

docs/source/use-cases/scientists.rst

@@ -0,0 +1,97 @@
+.. _use-case-scientists:
+
+Academic & Research Investigations
+==================================
+
+Academic identity has a unique anchor that social-media identity does not: the **ORCID** (Open Researcher and Contributor ID). Every ORCID is verified, globally unique, and tied to a confirmed email — a single confirmed ORCID match between two platforms means the **same human**, with effectively zero false-positive rate.
+
+Maigret uses ORCID as a first-class identifier: extract it once from a username-keyed profile (iNaturalist, GitHub bio, lab homepage), then pivot into the academic graph (ORCID, OpenAlex, arXiv, DBLP, Scholia) — a chain of HTTP calls that turns an anonymous handle into a CV with employer, education, publication list, citation count, co-author graph, and topical area.
+
+Why it matters
+--------------
+
+Most OSINT work on academic targets stalls at the same bottleneck: people use one alias on a citizen-science site, a different alias on Twitter, a third in a forum signature, and only their real name on PubMed. Connecting the personas by hand means trawling Google Scholar, ResearchGate, university web pages, and old conference programmes. ORCID short-circuits this entirely — one verified identifier resolves all of them.
+
+Common scenarios:
+
+- **Researcher background check.** Before a collaboration, a preprint review, or a grant decision — verifying that a claimed h-index, employment history, and publication count actually match the public ORCID record.
+- **Co-author graph reconstruction.** From a single ORCID, OpenAlex returns every co-author, their institutions, and topical clusters — useful for spotting undisclosed conflicts of interest.
+- **Paper mill / fraud investigation.** When a suspicious paper's authors share an ORCID-claimed identity, the cross-platform footprint (or absence of one) is itself evidence.
+- **Pseudonym deanonymisation.** A wildlife photographer posts naturalist observations under the handle ``kueda``. iNaturalist's public API returns their ORCID, and one further request reveals their real name, employer (California Academy of Sciences), education (UC Berkeley), and 700+ citable observations.
+- **Award / appointment due diligence.** Confirming a Turing-Award claim, a tenure status, or a society fellowship via the DBLP and ORCID activity timelines rather than a CV PDF.
+
+Supported sites
+---------------
+
+Maigret currently checks the following ORCID-keyed platforms (use ``--id-type orcid`` when starting from a bare ORCID, or rely on the recursive chain when starting from a username):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 42 40
+
+   * - Site
+     - What it reveals
+     - Notes
+   * - **ORCID**
+     - Full name, biography, employment, education, researcher URLs (homepages and social), keywords, country, linked external IDs (Scopus, ResearcherID, Loop), publication summary, email-verified status
+     - All disciplines — ORCID is a field-agnostic identifier issued to any researcher.
+   * - **OpenAlex**
+     - Display name and name alternatives, works count, total citations, h-index, i10-index, last-known institutions (with country), topical areas, raw author-name variants from publications
+     - All disciplines — indexes works across the entire scholarly literature, from humanities to medicine.
+   * - **arXiv**
+     - Author preprint listing — paper titles, IDs, dates
+     - Strongly biased toward physics, math, CS (and quantitative biology, statistics, EE, quantitative finance, economics).
+   * - **DBLP**
+     - Full name, DBLP person ID, paper count, affiliation, awards (e.g. Turing Award), homepage URLs, links to Google Scholar / ResearchGate / Scopus
+     - Computer science only — a biologist or pure economist will not be in the index.
+   * - **Scholia**
+     - Wikidata QID for the author, linked publications, co-author graph, employer/affiliation timeline, topical clusters
+     - All disciplines, but only if the author has been curated in Wikidata — coverage is broadest for prominent figures (award winners, senior faculty, deceased researchers).
+
+Workflow: from username to ORCID
+--------------------------------
+
+**Step 1: Find a profile that publishes ORCID**
+
+The most reliable bridges from a username to an ORCID are platforms whose users *want* their academic identity discoverable. In practice:
+
+- **iNaturalist** — biologists, naturalists, citizen scientists. Public API ``api.inaturalist.org/v1/users/{username}`` returns the ORCID directly in the ``orcid`` field. Maigret extracts it automatically.
+- **GitHub** — scientists often paste their ORCID URL into the **bio** or **blog** field on their GitHub profile, or under a *generic* entry in ``/users/{u}/social_accounts``. A pattern like ``orcid\.org/(\d{4}-\d{4}-\d{4}-\d{3}[\dX])`` matches both ``http://orcid.org/...`` and ``orcid.org/...`` variants.
+- **Lab homepage / institutional bio.** Use ``--parse <URL>`` to scrape an arbitrary page for known identifiers — useful when the target's footprint lives at ``faculty.example.edu/~jdoe``.
+
+**Step 2: Let the recursive search run**
+
+.. code-block:: console
+
+   maigret <username> --tags science -v
+
+Recursive search is enabled by default. As soon as Maigret extracts an ``orcid`` field from any found profile, it queues an ``--id-type orcid`` second wave automatically. No manual chaining needed.
+
+**Step 3: Start from a bare ORCID**
+
+If you already have the ORCID (e.g. from a paper's author footer, a grant database, or a Wikidata entry):
+
+.. code-block:: console
+
+   maigret 0000-0002-9322-3515 --id-type orcid -a
+
+This bypasses the username-bridge step entirely.
+
+Workflow: from ORCID to mainstream identity
+-------------------------------------------
+
+The ORCID record itself contains the link back to ordinary social platforms:
+
+1. **ORCID ``researcher-urls``** — a list of self-declared external links. Typical entries: lab homepage, Twitter/Bluesky/Mastodon profile, personal blog. These are entered by the researcher and therefore confirmed.
+2. **ORCID ``external-identifiers``** — IDs from sibling academic systems (Scopus Author ID, ResearcherID/Publons, Loop profile). Each unlocks another extraction pipeline.
+3. **OpenAlex ``last_known_institutions``** — current employer with country, ROR ID, and OpenAlex institution ID; useful for pivoting into the institution's directory.
+4. **DBLP** ``<url>`` **tags** — DBLP records often embed direct links to Google Scholar, ResearchGate, and personal pages.
+5. **Scholia ``wikidata_qid``** — once you have a Wikidata QID, the SPARQL endpoint unlocks the broadest external ID set in any single OSINT system: VIAF, LCCN, GND, Twitter handle, Mastodon handle, IMDb, GitHub, ORCID, and ~200 others.
+
+Tips
+----
+
+- **Email comes from ORCID** — within the academic chain (ORCID, OpenAlex, arXiv, DBLP, Scholia) it is the only source that returns an email address, and only when the researcher has marked their primary email public. The same response also carries ``history.verified-primary-email``, an ORCID-confirmed flag that means the address was email-validated at registration. Use this as a strong pivot into email-keyed lookups (Holehe, HIBP, Gravatar, etc.).
+- **Outside the academic chain, GitLab is the dev platform most likely to leak an email** via its public ``public_email`` field — relevant for scientists who self-host code on a CERN/research-institute GitLab. GitHub's REST API does not expose email by default.
+- **Compare OpenAlex** ``raw_author_names`` **against the ORCID** ``other-names``. Discrepancies often expose pre-marriage names, transliterations from non-Latin scripts, or co-author misattributions worth flagging.
+- **Anything fed into** ``--id-type orcid`` **must match** ``^\d{4}-\d{4}-\d{4}-\d{3}[\dX]$``. The trailing character may legitimately be ``X`` (ISO checksum); strip ``https://orcid.org/`` prefixes before passing the bare ID.