docs: formalize the Product-Market Fit Engine architecture and GTM workflows

docs/PRODUCT_MARKET_FIT_ENGINE.md

@@ -0,0 +1,40 @@
+# Product-Market Fit (PMF) Engine
+
+> **Vision:** Vibn is not just a code generator; it is a "Business in a Box" platform. The PMF Engine bridges the gap between "Main Street" businesses (SMBs) and "Silicon Valley" SaaS by automating market research, lead generation, and Go-To-Market (GTM) strategy.
+
+## The Objective
+When a user wants to build a product (e.g., "Software for Dentists"), the Vibn AI autonomously scopes the market opportunity, designs the product architecture, and generates the initial customer list.
+
+## 1. Market Sizing & Lead Generation
+**Goal:** Prove the market exists and give the founder their first 100 cold-outreach targets.
+* **Mechanism:** The AI maps the software idea to a specific Google Business Profile category (e.g., `gcid:dentist`).
+* **Tooling:** Uses the **DataForSEO Business Listings API** to scrape Google Maps in a defined geographic area.
+* **Output:** A structured CSV/JSON of real-world businesses, including their names, addresses, ratings, and scraped email addresses.
+* **Data Co-op Model:** Searches are charged via credits/micro-transactions. Results are cached in Vibn's Postgres database (`market_leads`). Over time, Vibn builds a proprietary, zero-cost database of every SMB in North America.
+
+## 2. Competitor Identification & Website Teardown
+**Goal:** Understand what the market leaders are doing and how to beat them.
+* **Mechanism:** The AI identifies the top 3 proprietary SaaS competitors.
+* **Tooling:** Natively uses `http_fetch` and `browser_navigate` (headless browser) to scrape competitor URLs.
+* **Output:** Extracts their pricing model (or lack thereof), value propositions, feature sets, and website page hierarchy to inform the user's build plan.
+
+## 3. SEO, Keywords & Ad Spend Analysis
+**Goal:** Find the cheapest acquisition channels and keyword gaps.
+* **Mechanism:** The AI analyzes the competitors' domains.
+* **Tooling:** Uses **DataForSEO Competitive Analysis / Keyword APIs** (via the `market_seo_analyze` MCP tool).
+* **Output:** Estimated monthly Google Ads spend, top-performing paid keywords, and low-difficulty organic keyword gaps (e.g., "open source dental booking widget").
+
+## 4. Open Source Baselining
+**Goal:** Never start from scratch if a foundation already exists.
+* **Mechanism:** The AI searches GitHub for actively maintained, permissively licensed (MIT/Apache 2.0) starter kits.
+* **Tooling:** Uses the `github_search` MCP tool.
+* **Output:** A list of repositories the AI can immediately clone and modify for the user.
+
+## 5. Automated Plan Generation
+**Goal:** Turn all of this research into actionable engineering and marketing tasks.
+* **Mechanism:** The AI acts as the user's product manager, writing the business plan directly into the Vibn platform's **Plan Tab**.
+* **Tooling:** Uses `plan_vision_set`, `plan_decision_log`, and `plan_task_add`.
+* **Example Output:** 
+  * *Vision:* "A $99/mo transparently priced patient engagement widget for dental clinics."
+  * *Decision:* "Targeting 'booking widget' SEO gap instead of 'practice management'."
+  * *Tasks:* Generated tickets for the AI to start scaffolding the Next.js landing page and database schema.