first-customer-finder-skill 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "id": "z0rats",
+  "owner": {
+    "name": "z0rats"
+  },
+  "plugins": [
+    {
+      "name": "first-customer-finder",
+      "source": "./",
+      "description": "Find and qualify evidence-backed potential first customers for a startup from recent public signals — ICP analysis, verified pain/buying signals, scored shortlist, drafted outreach openers, locale playbooks for non-English markets, and a polished HTML report. Never sends messages."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "first-customer-finder",
+  "description": "Find and qualify evidence-backed potential first customers, early adopters, and design partners for a startup from recent public signals, with locale playbooks for non-English markets. Research-only: never sends outreach.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Francesco Mistero"
+  },
+  "homepage": "https://github.com/z0rats/first-customer-finder-skill",
+  "license": "MIT",
+  "skills": ["./first-customer-finder"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Mistero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Claude First Customer Finder Skill
+
+A Claude Code skill that turns a startup URL or product idea into a qualified shortlist of potential first customers using recent public pain, demand, and timing signals.
+
+It defines the ideal customer profile, researches public sources, links the evidence behind every prospect, ranks fit and timing, drafts a source-based opener with a concrete manual CTA, and creates a polished HTML report. It never sends outreach automatically.
+
+## What It Does
+
+- Analyzes a startup URL, repository, or product description
+- Defines the primary and adjacent ideal customer profiles
+- Finds explicit demand, pain, workaround, switching, and timing signals
+- Qualifies prospects with an evidence-based score
+- Links every primary prospect to the original public source
+- Drafts respectful, source-based outreach openers with concrete manual CTAs
+- Recommends official/public contact routes without private enrichment
+- Creates a responsive standalone HTML report
+- Keeps all outreach manual by default
+- Avoids private contact enrichment and sensitive personal data
+
+## Installation
+
+**npm installer** (fastest):
+
+```bash
+npx --yes first-customer-finder-skill@latest
+```
+
+This installs the skill into:
+
+```text
+~/.claude/skills/first-customer-finder
+```
+
+**Claude Code plugin** (this repo is its own marketplace):
+
+```text
+/plugin marketplace add z0rats/first-customer-finder-skill
+/plugin install first-customer-finder@z0rats
+```
+
+Restart Claude Code after installation.
+
+## How long it takes
+
+This is a deep-research skill, not a chat answer — it searches, and in `standard`/`deep` mode fetches and verifies real pages, before anything reaches the shortlist. Expect roughly **10–15 minutes for a `standard` run** in Claude Code; `deep` mode (up to twenty prospects) takes noticeably longer.
+
+To speed things up:
+
+- Say **"quick mode"** — five prospects instead of ten roughly halves the research.
+- You can shrink scope **mid-run**: say *"quick mode is fine — wrap up with what's verified"* and the skill re-plans instead of finishing every search bucket.
+- If your environment prompts for fetch/browse permission per domain, approving "allow all for this site" once avoids repeat prompts — research tends to cluster on a handful of domains, so prompts stop quickly.
+
+## Usage
+
+Claude Code activates the skill automatically when a request matches its description. Just ask naturally, for example:
+
+```text
+Find ten evidence-backed potential first customers for https://example.com and create the final HTML report.
+```
+
+Find design partners:
+
+```text
+Find first customers in design-partners mode for this startup: [URL]. Prioritize people publicly describing the problem and likely to give product feedback.
+```
+
+B2B research:
+
+```text
+Find first customers in b2b mode for [URL]. Find public business triggers, qualify the relevant companies, and draft one opener per prospect without sending anything.
+```
+
+## Output
+
+The report includes:
+
+1. Early-customer verdict
+2. Primary ICP and disqualifiers
+3. Highest-confidence prospect
+4. Evidence-backed prospect shortlist
+5. Fit and timing scores
+6. Source links and signal dates
+7. Personalized outreach openers with concrete CTAs
+8. Repeated pain patterns
+9. Seven-day manual outreach plan
+10. Research limitations
+
+Prospects are hypotheses based on public signals, not confirmed customers or guaranteed buyers.
+
+## Modes
+
+- `quick`: up to five strong prospects
+- `standard`: up to ten prospects across several source types
+- `deep`: up to twenty prospects and repeated-pattern analysis
+- `design-partners`: feedback-oriented early adopters
+- `b2b`: companies and public business triggers
+- `community`: explicit requests and public discussion signals
+
+## Manual Installation
+
+```bash
+git clone https://github.com/z0rats/first-customer-finder-skill.git
+mkdir -p ~/.claude/skills
+cp -R first-customer-finder-skill/first-customer-finder ~/.claude/skills/first-customer-finder
+```
+
+Restart Claude Code after installation.
+
+## Credits
+
+This repo started as a fork of [codex-first-customer-finder-skill](https://github.com/Kappaemme-git/codex-first-customer-finder-skill) by Francesco Mistero (the Codex-agent original) — see `LICENSE` for that project's copyright. Later revisions also borrowed structure, wording, and workflow ideas from [carolinacherry/claude-first-customer-finder-skill](https://github.com/carolinacherry/claude-first-customer-finder-skill) by Daniel An. This fork adds locale playbooks for non-English markets (starting with CIS/Russian-speaking) and other workflow changes on top of both.
+
+## License
+
+MIT

package/first-customer-finder/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: first-customer-finder
+description: Find and qualify evidence-backed potential first customers, early adopters, design partners, or beta users for a startup using recent public pain and buying signals. Use when analyzing a product URL or idea, defining an ideal customer profile, researching public discussions and business pages, identifying first-user prospects, ranking lead fit and timing, preparing source-based outreach drafts, or creating a shareable early-customer prospecting report without sending messages automatically.
+---
+
+# First Customer Finder
+
+Turn a startup URL or product description into a short, evidence-backed list of plausible first customers. Use public signals, preserve privacy, and distinguish a prospect from a confirmed buyer.
+
+Read [references/research-framework.md](references/research-framework.md) before researching or scoring prospects. Read [references/report-artifact.md](references/report-artifact.md) before creating the final report. Read [references/locale-playbooks.md](references/locale-playbooks.md) whenever the product's buyer, language, or stated geography is not English-language/US-EU-centric, and apply the matching playbook before building the search plan.
+
+## Workflow
+
+### 1. Understand the product
+
+- Inspect the supplied URL, repository, landing-page copy, or product description.
+- Identify the product, outcome, buyer, user, price or buying motion, geography, and strongest use case.
+- Define one primary ICP, one adjacent ICP, pain triggers, positive signals, and disqualifiers.
+- Infer missing context when safe and label the inference. Ask one concise question only when ambiguity would materially change the search.
+- Determine the buyer's likely language and market. If it is not English-language/US-EU-centric (e.g., CIS, Russian-speaking), read [references/locale-playbooks.md](references/locale-playbooks.md) and use the matching playbook for the rest of the workflow.
+
+### 2. Build a public-signal search plan
+
+Search current public sources for:
+
+- explicit tool or alternative requests
+- first-person descriptions of the target problem
+- manual workflows and repeated workaround complaints
+- migration, churn, or competitor-frustration signals
+- public company changes that create timing, such as hiring, launching, expanding, or adopting a relevant workflow
+
+Use the query buckets and source mix from the applicable locale playbook when one applies; otherwise use the base buckets above with general web search. When subagent delegation is available, run each query bucket as its own parallel research subagent — one bucket per agent, each returning candidate signals with source URLs, dates, and a summary close to the original wording. Give every agent the product brief and ICP so it can reject weak matches at the source, and instruct it to fetch and quote what it cites; an agent may not return a URL it did not open. Work the buckets sequentially instead if the environment has no subagent support. Prefer original pages over search snippets. Record the source URL, source type, publication date when visible, and the exact evidence supporting qualification.
+
+### 3. Research safely
+
+- Use public, intentionally shared professional or business information only.
+- Do not bypass login walls, paywalls, access controls, rate limits, or robots restrictions.
+- Do not use data brokers, leaked datasets, private groups, personal email discovery, phone enrichment, or sensitive personal information.
+- Do not infer protected traits or target people using health, financial hardship, political belief, sexuality, religion, or other sensitive attributes.
+- Prefer companies, public professional profiles, public requests, and community posts relevant to the product.
+- Quote minimally and paraphrase by default. Link every material pain or timing signal.
+
+### 4. Verify before you qualify
+
+Fetch the original page for every candidate signal before it can enter the shortlist. A search snippet, an aggregator summary, or a subagent's unquoted paraphrase is not evidence. Confirm the page exists, the signal says what was claimed, and the date. Drop anything that fails this check.
+
+Some high-value sources block server-side fetching (e.g., Reddit, G2/TrustRadius, Cloudflare-fronted job boards). Do not drop a candidate for that reason alone — verify through an alternate legitimate route instead: a browser session, an official API (e.g., HN Algolia for Hacker News), or the site's RSS feed. Third-party archives can run months stale, so prefer the live page and note which route confirmed it. When a subagent already fetched and quoted a source, spot-check its work, and always re-verify the top three prospects yourself before they reach the report.
+
+### 5. Qualify and deduplicate
+
+Score each prospect using the bundled framework:
+
+- pain strength
+- product fit
+- timing
+- public reachability
+- evidence quality
+
+Remove duplicates and weak matches. A prospect without a cited pain, need, or timing signal is only a speculative fit and must not appear in the primary shortlist.
+
+Never claim that a prospect is interested, has consented, or will buy. Label the output "potential customer based on public signals."
+
+### 6. Draft outreach, never send it
+
+- Recommend the most natural public or professional channel already associated with the source. Prefer concrete official/public routes such as a company form, public business email, relevant public thread, or professional profile. If no direct public route is found, say so instead of guessing.
+- Identify the likely target role or function, not just the company name.
+- Translate the product into the buyer's problem language. Do not lead with implementation-layer terms unless the source proves that audience already cares about them.
+- Make the next step concrete enough to accept, reject, or forward, such as a scenario, teardown, worksheet, checklist, benchmark, mockup, or sandbox walkthrough.
+- Write one short opener grounded only in the cited public context.
+- Include a specific CTA, preferably a routing or yes/no ask tied to that next step.
+- Note the likely target function and objection when useful for manual outreach planning.
+- Avoid pretending to know the person, overstating familiarity, or mentioning unrelated personal details.
+- Do not send messages, submit forms, connect, follow, comment, or create CRM records unless the user separately requests and authorizes that action.
+
+### 7. Produce the report
+
+Lead with the most actionable evidence. Use this order:
+
+1. **Verdict** — whether the startup has reachable early-customer signals.
+2. **ICP** — buyer, job, trigger, and disqualifiers.
+3. **Top prospect** — strongest evidence-backed candidate and why now.
+4. **Prospect shortlist** — source, pain signal, fit score, stage, why now, channel, and opener with a concrete CTA.
+5. **Repeated patterns** — pains and triggers appearing across prospects.
+6. **Seven-day outreach plan** — a manual, low-volume validation sequence.
+7. **Limits** — missing evidence and what must be confirmed through real conversations.
+
+Create a standalone HTML report unless the user explicitly requests chat-only output:
+
+1. Write structured JSON using `references/report-artifact.md`.
+2. Run `python3 scripts/generate_report.py <analysis.json> <report.html>`.
+3. Save the report in the workspace `outputs/` directory (create it if missing).
+4. Verify prospect cards, source links, scores, concrete contact routes, CTAs, patterns, outreach plan, and limitations.
+5. Return a clickable absolute file link (`file://...`) in the final response, or publish it as an Artifact if the user is working in an environment that supports that.
+
+## Modes
+
+- **quick**: Find and qualify up to five strong prospects.
+- **standard**: Find up to ten prospects across several public source types.
+- **deep**: Research up to twenty prospects and map repeated pain patterns.
+- **design-partners**: Prioritize users willing to test and give feedback over immediate buyers.
+- **b2b**: Prioritize companies, public business triggers, and relevant decision roles.
+- **community**: Prioritize public discussion and explicit request signals.
+
+Use `standard` by default. State the mode explicitly in the request, e.g. "find first customers for https://example.com in deep mode".
+
+## Gotchas
+
+- **Fabrication is the failure mode that kills this skill.** A plausible prospect with a dead or mismatched link is worse than no prospect — step 4's verification is not optional, even in quick mode.
+- **Two-sided products** (e.g., marketplaces) return a mixed bag of both sides from research. Filter to the primary ICP before scoring; note the adjacent side under patterns instead of blending both into one shortlist.
+- **Old signals** can still qualify — an explicit request from 18 months ago is fine to include — but cut its timing score and print the date next to it so the reader can judge freshness themselves.
+- **Ten strong beats thirty generic.** If verification leaves you with four great prospects instead of ten mediocre ones, ship four and say why.
+- **Respect impatience.** If the user asks you to hurry or wrap up mid-run, switch to quick mode immediately: stop waiting on unfinished search buckets, verify and score what you already have, and ship the report with a note about which buckets were cut short.
+
+## Quality bar
+
+- Link every prospect to at least one meaningful public signal.
+- Prefer ten strong matches over a long generic lead list.
+- Make uncertainty and stale evidence visible.
+- Personalize from the source, not from invented assumptions.
+- Make the manual next step operationally clear: who should receive it, what to ask, and what answer the outreach needs.
+- Keep outreach manual and respectful.
+- Treat the shortlist as a research hypothesis, not a customer database.

package/first-customer-finder/references/locale-playbooks.md

@@ -0,0 +1,69 @@
+# Locale Playbooks
+
+The default query buckets and source mix in `research-framework.md` are written for English-language, US/EU-centric products. Apply a locale playbook whenever the product's buyer, language, or stated geography points elsewhere, so the search plan does not default to English-only sources.
+
+## Detecting the locale
+
+Infer from, in order of priority:
+
+1. an explicit geography or language stated by the user
+2. the product's own language (landing page copy, README, UI strings)
+3. the TLD, company registration, or pricing currency
+4. the language prospects are likely to complain in, which may differ from the product's language
+
+Label the inference. If signals conflict (e.g., English product copy but a CIS-only pricing page), search both the product's language and the buyer's likely language.
+
+## CIS / Russian-speaking market
+
+Use this playbook when the buyer or product geography is Russia, Ukraine, Belarus, Kazakhstan, or another Russian-speaking market.
+
+### Query buckets (Russian-language equivalents)
+
+Search these alongside, not instead of, the English buckets if the audience is bilingual:
+
+1. **Explicit demand:** "ищу сервис", "посоветуйте инструмент", "кто чем пользуется для", "аналог [competitor]", "есть что-то для".
+2. **Pain:** "задолбался вручную", "занимает часы", "бесит когда", "неудобно", "постоянно ломается", "костыль".
+3. **Workaround:** таблицы (Google Sheets/Excel), копипаста между сервисами, боты в Telegram "на коленке", фрилансер/VA для рутины.
+4. **Switching:** "отказался от [конкурент]", "подорожал", "перестал устраивать", жалобы на цены/поддержку/блокировку.
+5. **Timing:** вакансии на hh.ru под смежную роль, анонсы запуска/расширения в Telegram-каналах компании, посты о найме или пивоте.
+
+Russian is heavily inflected — a single fixed phrase per bucket misses most matches. Vary case and person rather than searching one form only: "ищу" / "ищем" / "искали" / "ищет кто-нибудь", "задолбался" / "задолбались" / "задолбало", "аналог Notion" / "аналоги Notion" / "альтернатива Notion". Treat each bucket as a cluster of word forms, not a single string.
+
+### Source mix
+
+- **Habr (habr.com)** — technical/product audience; strong for developer tools, SaaS, infra pain posts and comments.
+- **VC.ru** — startup/business audience; launch posts, business-model discussions, comment threads with pain signals.
+- **Pikabu** — broad consumer audience; useful for consumer-facing products, less reliable for B2B.
+- **hh.ru** — vacancies as a timing signal (a company hiring for a role your product supports is a trigger); job descriptions also reveal current workflow and tooling.
+- **TenChat** — closest RU-market analog to LinkedIn-style professional posts; use for professional/business signals.
+- **VK public pages and communities** — company pages, industry groups; treat like public company pages, not private groups.
+- **Telegram public channels and chats** — browse via the public web preview (`t.me/s/<channel>`) or a public directory (e.g., TGStat, Telemetr) rather than trying to search inside the app; only cite channels/messages that are openly public, not invite-only groups.
+- **Public company registries** — a strong, underused timing source. For Russia: `rusprofile.ru` or `list-org.com` (registration date, OKVED activity codes, leadership/ownership changes, active/liquidation status). A recent registration, a leadership change, or a newly added activity code relevant to the product is a legitimate timing signal — cite the registry page itself, not a summary.
+
+### Payment rails and product fit
+
+Stripe and PayPal do not operate inside Russia, which affects `product_fit` and reachability for any product whose buying motion assumes them (checkout, subscription billing, payouts). When qualifying a Russia-based prospect for a product billed through Stripe/PayPal, note this as a disqualifier or a material caveat rather than silently scoring fit as if global checkout worked normally. Local alternatives prospects may already use — useful for recognizing existing workarounds under the "workaround" query bucket — include ЮKassa, CloudPayments, Т-Банк (Tinkoff) Acquiring, and Robokassa. This constraint is Russia-specific; Ukraine, Kazakhstan, and Belarus each have their own separate payment-rail landscape and shouldn't be assumed to share it.
+
+### Compliance caution
+
+When the product/company is based in a jurisdiction with export controls or sanctions programs (e.g., US, EU, UK) and a prospect is Russia-based, sanctions or export-control restrictions may prohibit selling or providing services to that prospect, depending on the product category, the specific entity, and current regulations. This is not something to resolve automatically — flag it, don't decide it:
+
+- Do not silently draft outreach to a Russia-based prospect for a Western-owned product without surfacing this.
+- Set the prospect's `caution` field to note the jurisdiction mismatch and that sanctions/export-control screening should happen before any outreach.
+- This is a flag for the user to verify, not legal advice — never assert that a prospect is or isn't compliant to contact.
+
+### Platform caveats
+
+- **LinkedIn is formally blocked in Russia** (Roskomnadzor, since 2016), but VPN use is widespread enough among the professional/tech audience that it remains a usable source — do not exclude it by default. Treat it as secondary to TenChat/VK/Habr for Russia-based prospects rather than off-limits, and expect lower coverage for less tech-savvy or non-VPN audiences.
+- **Telegram and VK content is often not indexed by general web search.** Do not assume a WebSearch query surfaces relevant channels or posts; fetch known public channels/communities directly, or use a public directory site to discover them first.
+- **Private/closed Telegram groups and VK communities remain off-limits**, same as any other private group under the base research-safety rules — do not join, request access, or use a member list to enrich contacts.
+
+### Reporting and outreach adjustments
+
+- Set `search_scope` in the report JSON to reflect the actual scope searched, e.g. `"Public Russian-language sources (Habr, VC.ru, hh.ru, Telegram), last 12 months"` instead of the English-language default.
+- Draft the opener in the same language as the cited public source, not automatically in English.
+- Base the seven-day outreach plan's cadence on the prospect's local business hours, not the product's home timezone. Russia, Belarus, and most of Kazakhstan sit roughly UTC+3 to UTC+6 (Moscow Time and east of it); Ukraine is UTC+2/+3. Note the relevant timezone in the plan when it would otherwise default to a Western business-hours assumption.
+
+## Adding another locale
+
+Follow the same shape: translated query buckets, a ranked source mix specific to that market, platform caveats (blocked/unreliable platforms, search-indexing gaps), and any reporting-language adjustment. Keep each playbook self-contained so the workflow can read only the one that applies.

package/first-customer-finder/references/report-artifact.md

@@ -0,0 +1,76 @@
+# Report Artifact
+
+Create a standalone HTML report from the final qualified prospect data. Use the bundled generator instead of writing report markup manually.
+
+## Generate
+
+```bash
+python3 scripts/generate_report.py analysis.json outputs/first-customer-finder-report.html
+```
+
+Return a clickable absolute `file://` link in the final response, or publish the HTML as an Artifact if the current environment supports it. Keep the JSON in a work or temporary directory unless the user asks for raw data.
+
+## JSON schema
+
+Fields are intentionally flat (`source_url`, `source_type`, `signal_date`, `pain_strength`, ...) rather than nested under a `source`/`scores` object. A model writing this JSON by hand is less likely to misplace or drop a field in a flat shape, and `generate_report.py` reads these exact keys — keep new fields flat too unless there's a concrete reason to nest.
+
+```json
+{
+  "title": "First Customer Finder",
+  "product": "Example product",
+  "product_url": "https://example.com",
+  "target_customer": "Independent gym owners",
+  "search_scope": "Public English-language sources, last 12 months",
+  "generated_at": "2026-07-12",
+  "verdict": "The strongest early demand comes from owners manually chasing failed membership payments.",
+  "prospects": [
+    {
+      "name": "Example Gym",
+      "type": "Company",
+      "stage": "Problem aware",
+      "score": 82,
+      "pain_signal": "The owner publicly described manually following up on overdue memberships.",
+      "evidence": "A recent public post describes the workflow and time cost.",
+      "why_fit": "The product automates the exact reminder and payment step.",
+      "why_now": "The post is recent and asks how other owners handle the process.",
+      "source_title": "How do you handle failed payments?",
+      "source_url": "https://example.com/public-post",
+      "source_type": "Public forum",
+      "signal_date": "2026-07-01",
+      "suggested_channel": "Reply to the public discussion",
+      "opener": "Saw your question about failed-payment follow-up. We are testing a checklist for reducing manual payment chasing. Worth sending to whoever owns membership billing?",
+      "caution": "Confirm the workflow is still active before pitching.",
+      "dimensions": {
+        "pain_strength": 5,
+        "product_fit": 5,
+        "timing": 4,
+        "reachability": 4,
+        "evidence_quality": 4
+      }
+    }
+  ],
+  "patterns": [
+    {
+      "title": "Manual follow-up",
+      "count": 4,
+      "insight": "Owners rely on spreadsheets and messaging apps after payments fail."
+    }
+  ],
+  "outreach_plan": {
+    "angle": "Offer a manual concierge test before asking for software adoption.",
+    "first_step": "Contact the three highest-scoring prospects with one source-based question.",
+    "follow_up": "Share a two-minute mockup only after they confirm the pain.",
+    "success": "Three conversations and one design-partner commitment within seven days."
+  },
+  "limits": [
+    "These are potential customers inferred from public signals, not confirmed buyers.",
+    "Verify current relevance before any outreach and keep contact manual."
+  ]
+}
+```
+
+Normal mode should contain up to ten qualified prospects. Every primary prospect must include a valid public source URL and a score from 0 to 100.
+
+Set `search_scope` to the sources actually searched, not the example above by default. When a locale playbook applied (see [locale-playbooks.md](locale-playbooks.md)), name the actual sources and language, e.g. `"Public Russian-language sources (Habr, VC.ru, hh.ru, Telegram), last 12 months"`.
+
+Use `opener` for a short source-grounded message with a concrete manual CTA. Avoid vague CTAs such as "would this be useful?" when a sharper routing ask is available.

package/first-customer-finder/references/research-framework.md

@@ -0,0 +1,123 @@
+# Research and Qualification Framework
+
+Use this framework to keep prospect research evidence-based, current, and respectful.
+
+## Research sequence
+
+### Product brief
+
+Define:
+
+- product and promised outcome
+- primary user and economic buyer
+- urgent job to be done
+- current alternative or workaround
+- likely adoption trigger
+- geography or language constraint
+- clear disqualifiers
+
+Do not begin broad lead collection until this brief is specific enough to reject weak matches.
+
+### Query buckets
+
+Search several buckets rather than repeating one query:
+
+1. **Explicit demand:** "looking for," "recommend a tool," "alternative to," "does anything exist."
+2. **Pain:** "takes hours," "manual," "frustrating," "hate," "difficult," "keeps breaking."
+3. **Workaround:** spreadsheets, copy-paste, virtual assistants, scripts, templates, or repeated manual steps.
+4. **Switching:** cancellation, migration, missing feature, pricing complaint, or competitor frustration.
+5. **Timing:** public launch, hiring, expansion, new workflow, regulation, integration, or process change relevant to the product.
+
+Adapt wording to the audience's language. Search the original public page and do not qualify from a search snippet alone.
+
+### Source mix
+
+Useful public sources include:
+
+- forums and public community discussions
+- public social posts and replies
+- product reviews and app marketplace reviews
+- GitHub issues and public feature requests
+- public company pages, job posts, changelogs, or announcements
+- public "looking for a tool" posts and directories
+
+Avoid private groups, gated communities, data brokers, scraped contact databases, and sources that prohibit access.
+
+## Verification rule
+
+Qualify only from the original public page, fetched and read — not from a search snippet, an aggregator summary, or memory. Each signal that reaches the shortlist needs: source URL, source title, source type, visible publication date (or "date unavailable"), and a note of what was directly observed versus inferred.
+
+Some high-value sources block server-side fetching (Reddit, G2/TrustRadius, Cloudflare-fronted job boards, among others). Do not drop a candidate for that alone — verify through an alternate legitimate route: a browser session, an official API (e.g., HN Algolia for Hacker News), or the site's RSS feed. Third-party archives and cached copies can run months stale; prefer the live page and record which route verified it.
+
+## Qualification score
+
+Score every dimension from 0 to 5:
+
+- **Pain strength (25%)** — directness, severity, repetition, and cost of the stated problem.
+- **Product fit (25%)** — how directly the startup solves the evidenced job.
+- **Timing (20%)** — freshness and presence of a current trigger.
+- **Public reachability (15%)** — a natural, relevant public or professional contact path exists.
+- **Evidence quality (15%)** — specificity, source reliability, and confidence that the signal belongs to the prospect.
+
+Calculate:
+
+```text
+score = pain_strength/5*25
+      + product_fit/5*25
+      + timing/5*20
+      + reachability/5*15
+      + evidence_quality/5*15
+```
+
+Interpretation:
+
+- **80–100:** strong first-customer candidate
+- **65–79:** promising, validate quickly
+- **50–64:** plausible but missing a material signal
+- **Below 50:** do not include in the primary shortlist
+
+An old explicit request can still be relevant, but reduce timing and label the date. A company that merely matches the industry without an evidenced trigger is not a qualified prospect.
+
+## Prospect stages
+
+- **High intent:** publicly requesting a solution or actively switching.
+- **Problem aware:** clearly describing the pain or expensive workaround.
+- **Trigger present:** a current business event makes the product relevant.
+- **Potential fit:** ICP match with incomplete evidence; keep outside the primary shortlist.
+
+## Outreach rules
+
+Draft one opener using this shape:
+
+1. mention the public context naturally
+2. connect it to the buyer's exact business problem
+3. offer a concrete next step
+4. ask one low-friction CTA that can be answered, forwarded, or declined
+
+Good CTAs are specific: "Worth sending to whoever owns billing?", "Should I send the teardown?", or "Is a 10-minute workflow review useful this week?" Weak CTAs ask only whether the product "would be useful" without giving the prospect a clear next action.
+
+For each prospect, make the outreach recommendation cover:
+
+- target role or function
+- official/public contact route
+- primary CTA
+- likely objection or risk
+
+Translate the product into the prospect's language. Avoid implementation details, platform mechanics, or internal jargon unless the public source shows the prospect already cares about those details.
+
+Keep the opener under 90 words by default. Never claim the message was sent. Do not include private emails, phone numbers, personal addresses, family information, or sensitive traits.
+
+## Evidence ledger
+
+For each qualified prospect record:
+
+- displayed company, project, or public professional name
+- source title and URL
+- visible publication date or "date unavailable"
+- source type
+- concise pain or timing signal
+- observed evidence versus inference
+- score breakdown
+- freshness warning when relevant
+
+Cite sources in the chat response whenever web research was performed.

package/first-customer-finder/scripts/generate_report.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""Generate a standalone First Customer Finder HTML report from JSON."""
+
+from __future__ import annotations
+
+import argparse
+import html
+import json
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+
+DIMENSIONS = {
+    "pain_strength": "Pain strength",
+    "product_fit": "Product fit",
+    "timing": "Timing",
+    "reachability": "Reachability",
+    "evidence_quality": "Evidence quality",
+}
+
+TOOLBAR_STYLES = """
+.toolbar{border:1px solid var(--line);border-radius:var(--radius);background:var(--panel);padding:16px;margin-bottom:16px}
+.toolbar-row{display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+.toolbar input[type=search],.toolbar select,.toolbar input[type=number]{background:var(--panel2);border:1px solid var(--line);color:var(--ink);border-radius:10px;padding:9px 12px;font:600 13px inherit}
+.toolbar input[type=search]{flex:1 1 220px;min-width:160px}
+.toolbar select{flex:0 0 auto}
+.score-filter{display:flex;align-items:center;gap:8px;color:var(--muted);font:700 12px ui-monospace,monospace;white-space:nowrap}
+.score-filter input{width:64px}
+.toolbar button{background:transparent;border:1px solid var(--line);color:var(--muted);border-radius:999px;padding:9px 14px;font:700 12px inherit;cursor:pointer}
+.toolbar button:hover{color:var(--ink);border-color:var(--acid)}
+.toolbar-status{margin:12px 2px 0;color:var(--muted);font:700 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.06em}
+#noResults{color:var(--muted);padding:24px;text-align:center;border:1px dashed var(--line);border-radius:var(--radius);margin-bottom:76px}
+"""
+
+TOOLBAR_SCRIPT = """
+(function(){
+  var list = document.getElementById('prospectsList');
+  if(!list) return;
+  var cards = Array.prototype.slice.call(list.querySelectorAll('.prospect'));
+  var searchInput = document.getElementById('searchInput');
+  var stageFilter = document.getElementById('stageFilter');
+  var sourceFilter = document.getElementById('sourceFilter');
+  var minScore = document.getElementById('minScore');
+  var sortSelect = document.getElementById('sortSelect');
+  var resetBtn = document.getElementById('resetFilters');
+  var resultCount = document.getElementById('resultCount');
+  var noResults = document.getElementById('noResults');
+  var total = cards.length;
+  if(!searchInput || !stageFilter || !sourceFilter || !minScore || !sortSelect) return;
+
+  function sortCards(list){
+    var mode = sortSelect.value;
+    return list.slice().sort(function(a, b){
+      if(mode === 'name-asc') return a.dataset.name.localeCompare(b.dataset.name);
+      var sa = Number(a.dataset.score), sb = Number(b.dataset.score);
+      return mode === 'score-asc' ? sa - sb : sb - sa;
+    });
+  }
+
+  function apply(){
+    var q = searchInput.value.trim().toLowerCase();
+    var stage = stageFilter.value;
+    var source = sourceFilter.value;
+    var min = Number(minScore.value) || 0;
+    var visible = 0;
+    sortCards(cards).forEach(function(card, i){
+      var matches = Number(card.dataset.score) >= min
+        && (!stage || card.dataset.stage === stage)
+        && (!source || card.dataset.source === source)
+        && (!q || card.dataset.name.toLowerCase().indexOf(q) !== -1);
+      card.style.display = matches ? '' : 'none';
+      card.style.order = String(i);
+      if(matches){
+        visible += 1;
+        var rank = card.querySelector('.rank');
+        if(rank) rank.textContent = String(visible).padStart(2, '0');
+      }
+    });
+    if(resultCount) resultCount.textContent = 'Showing ' + visible + ' of ' + total + ' prospects';
+    if(noResults) noResults.style.display = visible ? 'none' : '';
+  }
+
+  [searchInput, stageFilter, sourceFilter, minScore, sortSelect].forEach(function(el){
+    el.addEventListener('input', apply);
+    el.addEventListener('change', apply);
+  });
+  if(resetBtn){
+    resetBtn.addEventListener('click', function(){
+      searchInput.value = '';
+      stageFilter.value = '';
+      sourceFilter.value = '';
+      minScore.value = '0';
+      sortSelect.value = 'score-desc';
+      apply();
+    });
+  }
+  apply();
+})();
+"""
+
+
+def esc(value: Any) -> str:
+    return html.escape(str(value if value is not None else ""), quote=True)
+
+
+def clamp(value: Any, maximum: int = 100) -> int:
+    try:
+        number = round(float(value))
+    except (TypeError, ValueError):
+        number = 0
+    return max(0, min(maximum, number))
+
+
+def items(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    return value if isinstance(value, list) else [value]
+
+
+def safe_url(value: Any) -> str:
+    raw = str(value or "").strip()
+    parsed = urlparse(raw)
+    return esc(raw) if parsed.scheme in {"http", "https"} and parsed.netloc else "#"
+
+
+def stage_class(stage: Any) -> str:
+    value = str(stage or "").lower()
+    if "high" in value:
+        return "hot"
+    if "problem" in value or "trigger" in value:
+        return "warm"
+    return "cool"
+
+
+def render_dimensions(data: dict[str, Any]) -> str:
+    rows = []
+    for key, label in DIMENSIONS.items():
+        score = clamp(data.get(key, 0), 5)
+        rows.append(
+            f'<div class="metric"><span>{esc(label)}</span><div class="track"><i style="width:{score * 20}%"></i></div><b>{score}/5</b></div>'
+        )
+    return "".join(rows)
+
+
+def render_filter_options(prospects: list[dict[str, Any]], key: str, default: str) -> str:
+    seen: dict[str, None] = {}
+    for prospect in prospects:
+        value = str(prospect.get(key) or default).strip()
+        if value:
+            seen.setdefault(value, None)
+    return "".join(f'<option value="{esc(v)}">{esc(v)}</option>' for v in sorted(seen))
+
+
+def render_prospect(prospect: dict[str, Any], index: int) -> str:
+    score = clamp(prospect.get("score"))
+    source = safe_url(prospect.get("source_url"))
+    name = esc(prospect.get("name", f"Prospect {index}"))
+    stage = esc(prospect.get("stage", "Potential fit"))
+    source_type = esc(prospect.get("source_type", "Public source"))
+    return f"""
+    <article class="prospect reveal" data-score="{score}" data-stage="{stage}" data-source="{source_type}" data-name="{name}">
+      <header class="prospect-head">
+        <div class="rank">{index:02d}</div>
+        <div class="identity">
+          <span class="eyebrow">{esc(prospect.get('type', 'Public prospect'))}</span>
+          <h3>{name}</h3>
+          <span class="stage {stage_class(prospect.get('stage'))}">{stage}</span>
+        </div>
+        <div class="score" style="--score:{score}" aria-label="Fit score {score} out of 100"><strong>{score}</strong><small>/100</small></div>
+      </header>
+      <div class="signal"><span>Public signal</span><p>{esc(prospect.get('pain_signal', ''))}</p></div>
+      <div class="prospect-grid">
+        <div><span>Why it fits</span><p>{esc(prospect.get('why_fit', ''))}</p></div>
+        <div><span>Why now</span><p>{esc(prospect.get('why_now', ''))}</p></div>
+        <div><span>Suggested channel</span><p>{esc(prospect.get('suggested_channel', ''))}</p></div>
+        <div><span>Caution</span><p>{esc(prospect.get('caution', 'Confirm current relevance before outreach.'))}</p></div>
+      </div>
+      <blockquote><span>Suggested opener</span>{esc(prospect.get('opener', ''))}</blockquote>
+      <details>
+        <summary>Evidence and score breakdown</summary>
+        <div class="evidence"><div><span>Evidence</span><p>{esc(prospect.get('evidence', ''))}</p></div><div><span>Source</span><p>{source_type} · {esc(prospect.get('signal_date', 'Date unavailable'))}</p><a href="{source}" target="_blank" rel="noreferrer">{esc(prospect.get('source_title', 'Open original source'))} ↗</a></div></div>
+        <div class="metrics">{render_dimensions(prospect.get('dimensions') if isinstance(prospect.get('dimensions'), dict) else {})}</div>
+      </details>
+    </article>"""
+
+
+def render_pattern(pattern: dict[str, Any], index: int) -> str:
+    return f"""
+    <article class="pattern reveal"><span class="pattern-num">{index:02d}</span><div><h3>{esc(pattern.get('title', 'Repeated signal'))}</h3><p>{esc(pattern.get('insight', ''))}</p></div><strong>{clamp(pattern.get('count'), 999)}×</strong></article>"""
+
+
+def build_html(data: dict[str, Any]) -> str:
+    prospects = [x for x in items(data.get("prospects")) if isinstance(x, dict)]
+    patterns = [x for x in items(data.get("patterns")) if isinstance(x, dict)]
+    scores = [clamp(x.get("score")) for x in prospects]
+    high_intent = sum(1 for x in prospects if "high" in str(x.get("stage", "")).lower())
+    average = round(sum(scores) / len(scores)) if scores else 0
+    top = max(prospects, key=lambda x: clamp(x.get("score")), default={})
+    plan = data.get("outreach_plan") if isinstance(data.get("outreach_plan"), dict) else {}
+    limits = "".join(f"<li>{esc(x)}</li>" for x in items(data.get("limits")))
+    prospect_html = "".join(render_prospect(x, i) for i, x in enumerate(prospects, 1))
+    pattern_html = "".join(render_pattern(x, i) for i, x in enumerate(patterns, 1))
+    product_url = safe_url(data.get("product_url"))
+    stage_options = render_filter_options(prospects, "stage", "Potential fit")
+    source_options = render_filter_options(prospects, "source_type", "Public source")
+    toolbar_html = f"""
+      <div class="toolbar" role="search" aria-label="Filter and sort prospects">
+        <div class="toolbar-row">
+          <input type="search" id="searchInput" placeholder="Search name or company…" aria-label="Search prospects">
+          <select id="stageFilter" aria-label="Filter by stage"><option value="">All stages</option>{stage_options}</select>
+          <select id="sourceFilter" aria-label="Filter by source type"><option value="">All sources</option>{source_options}</select>
+          <label class="score-filter">Min score <input type="number" id="minScore" min="0" max="100" value="0" aria-label="Minimum score"></label>
+          <select id="sortSelect" aria-label="Sort by">
+            <option value="score-desc">Score: high to low</option>
+            <option value="score-asc">Score: low to high</option>
+            <option value="name-asc">Name: A-Z</option>
+          </select>
+          <button type="button" id="resetFilters">Reset</button>
+        </div>
+        <p class="toolbar-status" id="resultCount" aria-live="polite"></p>
+      </div>"""
+
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="color-scheme" content="dark">
+  <title>{esc(data.get('title', 'First Customer Finder'))}</title>
+  <style>
+    :root{{--bg:#090b0f;--panel:#12161d;--panel2:#191f28;--ink:#f5f2ea;--muted:#9ca6b5;--line:#2b3340;--acid:#d9ff63;--blue:#69b7ff;--orange:#ff8f5a;--cyan:#5ee8d0;--radius:18px;--shadow:0 24px 80px rgba(0,0,0,.38)}}
+    *{{box-sizing:border-box}}html{{scroll-behavior:smooth}}body{{margin:0;background:var(--bg);color:var(--ink);font-family:Inter,ui-sans-serif,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;line-height:1.55}}body:before{{content:"";position:fixed;inset:0;pointer-events:none;opacity:.3;background:repeating-linear-gradient(135deg,rgba(255,255,255,.018) 0 1px,transparent 1px 12px);mask-image:linear-gradient(#000,transparent 82%)}}a{{color:inherit}}.skip{{position:absolute;left:-9999px}}.skip:focus{{left:16px;top:16px;z-index:9;background:var(--acid);color:#111;padding:10px}}
+    .shell{{width:min(1180px,calc(100% - 40px));margin:auto;position:relative}}.top{{display:flex;justify-content:space-between;align-items:center;padding:22px 0;border-bottom:1px solid var(--line)}}.brand{{font-weight:850;display:flex;align-items:center;gap:10px}}.brand i{{width:12px;height:12px;border-radius:50%;background:var(--acid);box-shadow:0 0 22px var(--acid)}}.meta{{display:flex;gap:8px;align-items:center}}.chip,.stage{{border:1px solid var(--line);border-radius:999px;padding:7px 10px;color:var(--muted);font:750 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.07em}}button{{background:var(--ink);color:#111;border:0;border-radius:999px;padding:9px 14px;font:800 13px inherit;cursor:pointer}}button:focus-visible,summary:focus-visible,a:focus-visible{{outline:3px solid var(--blue);outline-offset:3px}}
+    .hero{{display:grid;grid-template-columns:1.45fr .55fr;gap:36px;align-items:end;padding:72px 0 42px}}.eyebrow{{color:var(--acid);font:750 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.11em}}h1{{font-size:clamp(48px,7vw,92px);line-height:.92;letter-spacing:-.065em;margin:13px 0 24px}}.verdict{{font-size:clamp(18px,2.1vw,25px);color:#dce1e9;max-width:820px;margin:0}}.hero-card{{background:var(--acid);color:#10120d;padding:26px;border-radius:var(--radius);box-shadow:var(--shadow);transform:rotate(1deg)}}.hero-card span{{font:800 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.08em}}.hero-card strong{{display:block;font-size:64px;line-height:1;letter-spacing:-.08em;margin:15px 0 6px}}.hero-card p{{margin:0;font-weight:700;font-size:13px}}
+    .stats{{display:grid;grid-template-columns:repeat(4,1fr);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden;margin-bottom:28px}}.stats>div{{padding:18px;background:var(--panel)}}.stats>div+div{{border-left:1px solid var(--line)}}.stats span,.prospect-grid span,.signal span,.evidence span,blockquote span{{display:block;color:var(--muted);font:700 10px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.08em;margin-bottom:6px}}.stats strong{{font-size:17px}}
+    .best{{display:grid;grid-template-columns:180px 1fr auto;gap:24px;align-items:center;padding:25px;background:var(--orange);color:#1b0f09;border-radius:var(--radius);box-shadow:var(--shadow);margin:0 0 72px}}.best-label{{font:800 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.1em}}.best h2{{font-size:clamp(28px,4vw,46px);letter-spacing:-.045em;line-height:1;margin:0 0 8px}}.best p{{margin:0}}.best strong{{font-size:44px}}
+    .section-head{{display:flex;justify-content:space-between;align-items:end;gap:24px;padding-bottom:18px;border-bottom:1px solid var(--line);margin-bottom:18px}}.section-head h2{{font-size:clamp(34px,5vw,62px);line-height:.98;letter-spacing:-.055em;margin:0}}.section-head p{{color:var(--muted);max-width:470px;margin:0}}
+    .prospects{{display:grid;gap:16px;margin-bottom:76px}}.prospect{{background:linear-gradient(135deg,var(--panel),#0f1319);border:1px solid var(--line);border-radius:var(--radius);padding:25px;box-shadow:0 12px 38px rgba(0,0,0,.18)}}.prospect-head{{display:grid;grid-template-columns:54px 1fr 92px;gap:17px;align-items:start}}.rank{{font:850 24px ui-monospace,monospace;color:var(--acid);padding-top:8px}}.identity h3{{font-size:29px;letter-spacing:-.04em;margin:6px 0 10px}}.stage{{display:inline-block}}.stage.hot{{color:var(--orange);border-color:rgba(255,143,90,.5)}}.stage.warm{{color:var(--cyan);border-color:rgba(94,232,208,.45)}}.score{{--score:0;width:88px;height:88px;border-radius:50%;display:grid;place-content:center;text-align:center;background:radial-gradient(circle,var(--panel) 58%,transparent 60%),conic-gradient(var(--acid) calc(var(--score)*1%),var(--line) 0)}}.score strong{{font-size:26px;line-height:1}}.score small{{color:var(--muted)}}
+    .signal{{margin:21px 0 12px;padding:16px;background:var(--panel2);border-left:4px solid var(--acid)}}.signal p{{font-size:17px;margin:0}}.prospect-grid{{display:grid;grid-template-columns:1fr 1fr;gap:9px}}.prospect-grid>div,.evidence>div{{border:1px solid var(--line);border-radius:12px;padding:15px;background:rgba(255,255,255,.018)}}.prospect-grid p,.evidence p{{margin:0}}blockquote{{margin:12px 0 0;padding:16px;border:1px dashed rgba(217,255,99,.55);border-radius:12px;color:#eaf6c6}}details{{margin-top:10px}}summary{{cursor:pointer;color:var(--acid);font-weight:800;padding:10px 0}}.evidence{{display:grid;grid-template-columns:1fr 1fr;gap:9px}}.evidence a{{display:inline-block;color:var(--blue);margin-top:8px;word-break:break-word}}.metrics{{display:grid;gap:8px;margin-top:14px}}.metric{{display:grid;grid-template-columns:145px 1fr 40px;gap:12px;align-items:center;font-size:13px}}.track{{height:8px;background:var(--line);border-radius:8px;overflow:hidden}}.track i{{display:block;height:100%;background:linear-gradient(90deg,var(--blue),var(--acid))}}
+    .patterns{{display:grid;grid-template-columns:repeat(2,1fr);gap:12px;margin-bottom:76px}}.pattern{{display:grid;grid-template-columns:42px 1fr auto;gap:15px;align-items:start;padding:20px;border:1px solid var(--line);border-radius:14px;background:var(--panel)}}.pattern-num{{color:var(--acid);font:800 13px ui-monospace,monospace}}.pattern h3{{margin:0 0 5px}}.pattern p{{margin:0;color:var(--muted)}}.pattern>strong{{font-size:30px;color:var(--acid)}}
+    .plan{{display:grid;grid-template-columns:.8fr 1.2fr;gap:28px;background:var(--acid);color:#111;padding:29px;border-radius:var(--radius);margin-bottom:30px}}.plan h2{{font-size:38px;line-height:1;letter-spacing:-.045em;margin:10px 0}}.plan-grid{{display:grid;grid-template-columns:1fr 1fr;gap:9px}}.plan-grid>div{{border:1px solid rgba(0,0,0,.24);border-radius:11px;padding:13px}}.plan-grid span{{display:block;font:750 10px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.07em;margin-bottom:5px}}.plan-grid p{{margin:0}}.limits{{border:1px solid var(--line);border-radius:var(--radius);padding:24px;color:var(--muted);margin-bottom:60px}}.limits h2{{color:var(--ink);margin-top:0}}footer{{display:flex;justify-content:space-between;gap:20px;border-top:1px solid var(--line);padding:22px 0 40px;color:var(--muted);font-size:12px}}.reveal{{animation:rise .4s ease both}}@keyframes rise{{from{{opacity:0;transform:translateY(12px)}}}}
+    @media(max-width:820px){{.shell{{width:min(100% - 24px,1180px)}}.hero,.plan{{grid-template-columns:1fr}}.hero{{padding-top:44px}}.hero-card{{transform:none}}.stats{{grid-template-columns:1fr 1fr}}.stats>div+div{{border-left:0;border-top:1px solid var(--line)}}.best{{grid-template-columns:1fr}}.prospect-head{{grid-template-columns:38px 1fr}}.score{{grid-column:1/-1}}.prospect-grid,.evidence,.patterns,.plan-grid{{grid-template-columns:1fr}}.meta .chip{{display:none}}}}
+    @media(prefers-reduced-motion:reduce){{*{{animation:none!important;transition:none!important;scroll-behavior:auto!important}}}}@media print{{body{{background:#fff;color:#111}}body:before,.top button,.toolbar{{display:none}}.shell{{width:100%}}.prospect,.pattern,.limits{{background:#fff;color:#111;break-inside:avoid}}.prospect-grid span,.signal span,.evidence span,blockquote span{{color:#444}}}}
+    {TOOLBAR_STYLES}
+  </style>
+</head>
+<body>
+  <a class="skip" href="#main">Skip to report</a>
+  <div class="shell">
+    <header class="top"><div class="brand"><i></i> First Customer Finder</div><div class="meta"><span class="chip">Public signals only</span><button type="button" onclick="window.print()">Print / Save PDF</button></div></header>
+    <main id="main">
+      <section class="hero"><div><span class="eyebrow">Early-customer report · {esc(data.get('generated_at', ''))}</span><h1>{esc(data.get('title', 'First Customer Finder'))}</h1><p class="verdict">{esc(data.get('verdict', 'No verdict supplied.'))}</p></div><aside class="hero-card"><span>Qualified prospects</span><strong>{len(prospects)}</strong><p>Potential customers based on public signals.</p></aside></section>
+      <section class="stats"><div><span>Product</span><strong><a href="{product_url}" target="_blank" rel="noreferrer">{esc(data.get('product', 'Not specified'))}</a></strong></div><div><span>Target customer</span><strong>{esc(data.get('target_customer', 'Not specified'))}</strong></div><div><span>High intent</span><strong>{high_intent}</strong></div><div><span>Average fit score</span><strong>{average}/100</strong></div></section>
+      <section class="best"><div class="best-label">Highest-confidence prospect</div><div><h2>{esc(top.get('name', 'No qualified prospect'))}</h2><p>{esc(top.get('why_now', top.get('pain_signal', '')))}</p></div><strong>{clamp(top.get('score'))}</strong></section>
+      <section><header class="section-head"><h2>People with a reason<br>to care now.</h2><p>Every primary prospect is tied to a public pain, demand, or timing signal. Open the evidence before considering outreach.</p></header>{toolbar_html if prospects else ''}<div class="prospects" id="prospectsList">{prospect_html or '<p>No qualified prospects supplied.</p>'}</div><p id="noResults" class="hidden" style="display:none">No prospects match these filters.</p></section>
+      <section><header class="section-head"><h2>Signals that repeat.</h2><p>Patterns across prospects reveal the strongest positioning, workflow, and outreach angles.</p></header><div class="patterns">{pattern_html or '<p>No repeated patterns supplied.</p>'}</div></section>
+      <section class="plan"><div><span class="eyebrow" style="color:#111">Seven-day manual plan</span><h2>{esc(plan.get('angle', 'Validate the pain before pitching the product.'))}</h2></div><div class="plan-grid"><div><span>First step</span><p>{esc(plan.get('first_step', ''))}</p></div><div><span>Follow-up</span><p>{esc(plan.get('follow_up', ''))}</p></div><div><span>Success signal</span><p>{esc(plan.get('success', ''))}</p></div><div><span>Research scope</span><p>{esc(data.get('search_scope', 'Not specified'))}</p></div></div></section>
+      <section class="limits"><h2>Use this shortlist responsibly</h2><ul>{limits or '<li>These are potential customers inferred from public signals, not confirmed buyers.</li>'}</ul></section>
+    </main>
+    <footer><span>Generated by $first-customer-finder</span><span>Outreach is never sent automatically.</span></footer>
+  </div>
+  <script>{TOOLBAR_SCRIPT}</script>
+</body>
+</html>"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path, help="Path to report JSON")
+    parser.add_argument("output", type=Path, help="Path to output HTML")
+    args = parser.parse_args()
+
+    with args.input.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    if not isinstance(data, dict):
+        raise SystemExit("Input JSON must contain an object at the top level.")
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(build_html(data), encoding="utf-8")
+    print(f"Created report: {args.output.resolve()}")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "first-customer-finder-skill",
+  "version": "0.1.0",
+  "description": "A Claude Code skill that finds evidence-backed potential first customers from recent public signals.",
+  "license": "MIT",
+  "author": "z0rats",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/z0rats/first-customer-finder-skill.git"
+  },
+  "homepage": "https://github.com/z0rats/first-customer-finder-skill#readme",
+  "bugs": {
+    "url": "https://github.com/z0rats/first-customer-finder-skill/issues"
+  },
+  "bin": {
+    "first-customer-finder-skill": "scripts/install.js"
+  },
+  "files": [
+    "first-customer-finder",
+    ".claude-plugin",
+    "scripts/install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skill",
+    "startup",
+    "customers",
+    "early-adopters",
+    "prospecting",
+    "customer-discovery",
+    "founders"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function usage() {
+  console.log(`
+Claude First Customer Finder Skill installer
+
+Usage:
+  npx first-customer-finder-skill
+  first-customer-finder-skill --skills-dir ~/.claude/skills
+
+Options:
+  --skills-dir PATH  Install into a custom Claude Code skills directory
+  --help             Show this help
+`);
+}
+
+function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--skills-dir") {
+      const value = argv[index + 1];
+      if (!value) throw new Error("--skills-dir requires a value");
+      options.skillsDir = expandHome(value);
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+function defaultSkillsDir() {
+  const claudeHome = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+  return path.join(claudeHome, "skills");
+}
+
+function copyDirectory(source, destination) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    if (entry.isDirectory()) copyDirectory(sourcePath, destinationPath);
+    else if (entry.isFile()) fs.copyFileSync(sourcePath, destinationPath);
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    usage();
+    return;
+  }
+
+  const source = path.resolve(__dirname, "..", "first-customer-finder");
+  const skillsDir = path.resolve(options.skillsDir || defaultSkillsDir());
+  const destination = path.join(skillsDir, "first-customer-finder");
+  if (!fs.existsSync(source)) throw new Error(`Cannot find bundled skill at ${source}`);
+
+  fs.mkdirSync(skillsDir, { recursive: true });
+  fs.rmSync(destination, { recursive: true, force: true });
+  copyDirectory(source, destination);
+
+  console.log("Installed first-customer-finder skill.");
+  console.log(`Location: ${destination}`);
+  console.log("");
+  console.log("Restart Claude Code, then run:");
+  console.log("  Find ten potential first customers for https://example.com.");
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}