@veyralabs/skills 0.4.1 → 0.5.0

package/skills/venture-suite/venture-analyst/references/lean-startup.md

@@ -0,0 +1,123 @@
+# Lean Startup Reference
+
+Core methodology for venture-analyst. Eric Ries, 2011. Still the most cited startup framework.
+
+## Build-Measure-Learn loop
+
+Not a sequential process — a loop. Start from Learn and work backwards:
+
+1. **Learn** - What do we need to know? (Define the riskiest assumption)
+2. **Build** - Build the minimum thing to test that assumption
+3. **Measure** - Collect data on whether assumption is true
+
+Speed through the loop beats quality of any single cycle.
+
+**Key insight:** Most startups fail not because they can't build, but because they build something nobody wants. The loop's purpose is to surface that failure cheaply and early.
+
+## Validated learning
+
+Not all learning is equal. Vanity metrics (page views, registered users) feel good and mean nothing.
+
+**Vanity metric examples:**
+- Total signups (meaningless without activation rate)
+- Page views (meaningless without behavior)
+- Press mentions (zero correlation with revenue)
+- Lines of code shipped
+
+**Actionable metrics (validated learning):**
+- Activation rate: % of signups who complete key action
+- Retention cohorts: do users come back week 2, week 4?
+- Willingness to pay: who actually pays vs who says they would
+- NPS with follow-up: would you be disappointed if gone?
+
+**Test:** "If this metric doubled, would we change what we build next?" If no - it's vanity.
+
+## Minimum Viable Product (MVP) types
+
+### Concierge MVP
+Do the service manually for 3-5 users. No automation.
+- When: early problem validation, B2B, high-value customers
+- Cost: time only
+- What you learn: is the outcome valuable? What parts matter?
+- Example: Airbnb founders photographed first listings themselves
+
+### Wizard of Oz MVP
+System looks automated but humans do the work behind the scenes.
+- When: you want to simulate the product without building it
+- Cost: time + some frontend work
+- What you learn: do users engage with the interface? Is the outcome valuable?
+- Example: Zappos CEO manually bought shoes from stores to test demand
+
+### Landing Page / Fake Door
+Page describes product, collects signups or clicks before product exists.
+- When: demand signal, product not built
+- Cost: hours (Carrd.co is free)
+- What you learn: does the message resonate? Will people take action?
+- Caution: doesn't test willingness to pay - only interest
+
+### Piecemeal MVP
+Assemble from existing tools. Don't build infrastructure.
+- When: proving the workflow works before custom tech
+- Cost: subscription fees for tools used
+- Example: use Airtable + Zapier + Stripe before building SaaS
+
+### Single-Feature MVP
+Ship one core feature only. Cut everything else.
+- When: you know the problem, testing one solution
+- Risk: might ship the wrong feature
+- Rule: what is the single thing that makes this valuable? Ship only that.
+
+## Pivot types
+
+When data says current direction is wrong, pivot — don't persevere blindly.
+
+| Pivot type | What changes | Example |
+|-----------|--------------|---------|
+| Zoom-in | Narrow one feature into whole product | Instagram pivoted from Burbn |
+| Zoom-out | Widen — current product becomes one feature | - |
+| Customer segment | Same product, different customer | B2C → B2B |
+| Customer need | Same customer, different problem | - |
+| Platform | App → platform or vice versa | - |
+| Business architecture | High margin/low volume ↔ low margin/high volume | - |
+| Value capture | How you charge (not what you sell) | Per seat → flat rate |
+| Engine of growth | Viral → sticky → paid acquisition | - |
+| Channel | Direct → partner → marketplace | - |
+| Technology | Same problem, completely different tech | - |
+
+**When to pivot vs persevere:**
+- Experiments consistently failing over multiple cycles = pivot signal
+- One experiment failing = not enough data
+- Team excited about pivot because it's easier = wrong reason, investigate
+
+## Innovation accounting
+
+3 milestones before declaring pivot/persevere:
+
+1. Establish baseline (where are we now? honest numbers)
+2. Tune the engine (optimize toward ideal, eliminate waste)
+3. Decide pivot or persevere (did tuning move numbers? if no, pivot)
+
+## Engines of growth
+
+**Sticky engine:** Retention is the driver. Churn rate < growth rate.
+- Metric: customer lifetime value vs churn rate
+- Strategy: improve activation and retention before acquisition
+
+**Viral engine:** Users recruit users.
+- Metric: viral coefficient (K-factor). K > 1 = exponential growth
+- K = (invites sent per user) × (conversion rate of invites)
+- Strategy: build referral loop into core product
+
+**Paid engine:** Buy customers profitably.
+- Metric: LTV > CAC (lifetime value > customer acquisition cost)
+- Rule of thumb: LTV should be 3x CAC minimum
+- Strategy: find one channel that scales before optimizing others
+
+## Signals this framework applies
+
+Use lean startup when:
+- Building a new product in uncertain market
+- Validating a problem before heavy investment
+- Deciding between multiple possible solutions
+
+Don't use it to justify shipping forever-incomplete products. "Lean" = eliminate waste, not "don't finish things."

package/skills/venture-suite/venture-analyst/references/mom-test.md

@@ -0,0 +1,146 @@
+# Mom Test Reference
+
+Rob Fitzpatrick, "The Mom Test" (2013).
+Core rule: your mom loves you and will lie to make you feel good. Most customers will too.
+The test: would your mom give you honest answers to these questions? If yes, they're good questions.
+
+## The problem with bad interviews
+
+Founders ask questions that make customers feel good but reveal nothing:
+
+- "Do you think this is a good idea?" — Everyone says yes. Means nothing.
+- "Would you use a product that does X?" — Hypothetical. People overestimate future behavior.
+- "How much would you pay for this?" — Hypothetical. Actual payments are the only data.
+
+**The lie:** "That's a great idea, you should build that." Customers say this to be kind. It's not validation.
+
+**Real validation:** someone pays, or gives up time, or says something unprompted that matches your hypothesis.
+
+## The three rules
+
+### Rule 1 — Talk about their life, not your idea
+
+Ask about what they already do. Not what they would do.
+
+Good: "How do you currently handle invoicing?"
+Bad: "Would you use an AI invoicing tool?"
+
+### Rule 2 — Ask about specifics in the past, not generics or opinions
+
+Past behavior predicts future behavior. Opinions don't.
+
+Good: "Walk me through the last time you dealt with that."
+Bad: "Do you often have trouble with that?"
+
+### Rule 3 — Listen, don't pitch
+
+If you're explaining your idea, you're not learning. You're convincing.
+The moment you pitch, all their answers become validation attempts, not honest signals.
+
+## Good vs bad questions
+
+### Good questions
+
+- "How do you currently handle [problem]? Walk me through your last time."
+- "What's the most frustrating part of that process?"
+- "How long does that take you per week?"
+- "Have you tried other solutions? What happened?"
+- "How much are you currently spending on this? Time + money."
+- "What would you do if this problem disappeared tomorrow?"
+- "Who else in your team deals with this?"
+- "How do you find out about tools like this?"
+- "What would make you switch away from your current solution?"
+
+### Bad questions
+
+- "Would you use X if it existed?"
+- "Do you think this is a good idea?"
+- "What features would you want?"
+- "How much would you pay for this?"
+- "Would you pay $X/month for this?"
+- "Don't you think [problem] is really bad?"
+- "If we built X, would that solve your problem?"
+
+## Detecting false positives
+
+Customers say things that sound like validation but aren't.
+
+**Compliments (ignore these):**
+- "That's really interesting."
+- "I could see that being useful."
+- "You should definitely build that."
+- "I know people who would use that."
+
+**Weak signals (not enough alone):**
+- "I would use it if it had X feature."
+- "I might sign up when it's live."
+- "Send me info when you launch."
+
+**Strong signals (real validation):**
+- They ask when it will be available and push for a date
+- They offer to pay now, even before it's built
+- They ask for a demo with their boss on the call
+- They describe a specific workflow where they'd use it
+- They give you a referral without being asked
+
+**The commitment test:**
+"Would you be willing to [try the beta / join a pilot / pay a deposit / introduce me to your VP]?"
+
+Their reaction tells you more than anything they said before.
+
+## Extracting signal from praise
+
+When they say "I love it" — push:
+
+- "What specifically would you use it for?"
+- "How often would that come up?"
+- "How much time/money is that costing you now?"
+- "What would you stop doing if you had this?"
+
+Turn abstract enthusiasm into concrete use cases and quantified pain.
+
+## Signs you found a real customer
+
+1. They describe the problem in detail without being asked
+2. They have a workaround they're not happy with
+3. They ask questions about your solution (not just compliment it)
+4. They connect you to other people with the same problem
+5. They put time/money on the line (small commitment = real interest)
+
+## Signs this is the wrong customer
+
+1. They can't remember a specific recent example of the problem
+2. Their "solution" is to just not deal with it
+3. They're enthusiastic but can't make a buying decision
+4. Every answer is "it depends" without specifics
+5. The problem you're describing is news to them
+
+## Interview format that works
+
+**Setup (2 min):** "I'm researching how [people like you] handle [domain]. Not selling anything. Want honest feedback."
+
+**Warm-up (3 min):** Ask about their role, day-to-day. Build context.
+
+**Core (15 min):** Story-based questions about past behavior.
+- "Tell me about the last time..."
+- "Walk me through what you did..."
+- "What happened after that?"
+
+**Quantify (5 min):** Pin down real numbers.
+- "How often does this happen?"
+- "How long does it take?"
+- "What does it cost you?"
+
+**Wrap-up (3 min):** "Who else would you suggest I talk to about this?"
+
+Total: 25-30 minutes. Don't go over — respect their time.
+
+## Pattern recognition across interviews
+
+After 10+ interviews:
+- Which problems do they all mention? (signal)
+- Which problems do only 1-2 mention? (noise or niche)
+- Which solutions do they all currently use? (incumbent to beat)
+- What do they all want but nobody builds? (gap)
+
+Don't average opinions. Look for patterns in specific behaviors.

package/skills/venture-suite/venture-analyst/references/traction.md

@@ -0,0 +1,154 @@
+# Traction Reference
+
+Gabriel Weinberg & Justin Mares, "Traction" (2014).
+Framework for finding customer acquisition channels that actually work.
+
+## Core insight
+
+Most startups fail not because of product problems but traction problems. Building product and finding traction should happen in parallel, not sequentially.
+
+Half your time should be spent on traction, not product — even pre-launch.
+
+## The 19 traction channels
+
+1. **Viral marketing** - product spreads through existing users (Dropbox, Slack)
+2. **PR** - traditional press coverage
+3. **Unconventional PR** - stunts, giveaways, memorable campaigns
+4. **Search engine marketing (SEM)** - paid search (Google Ads)
+5. **Social and display ads** - Meta, LinkedIn, programmatic
+6. **Offline ads** - billboards, radio, TV, print
+7. **Search engine optimization (SEO)** - organic search
+8. **Content marketing** - blog, YouTube, podcast as acquisition
+9. **Email marketing** - list building and outbound sequences
+10. **Engineering as marketing** - free tools, calculators, embeds that drive signups
+11. **Targeting blogs** - get covered by influential niche blogs
+12. **Business development** - partnerships with complementary products
+13. **Sales** - direct outbound sales, inside sales teams
+14. **Affiliate programs** - revenue share for referrals
+15. **Existing platforms** - App Store, Shopify App Store, Chrome extensions, marketplace distribution
+16. **Trade shows** - industry events, conferences
+17. **Offline events** - meetups, workshops, demos
+18. **Speaking engagements** - conferences, podcasts, webinars
+19. **Community building** - Slack groups, forums, ambassador programs
+
+## Bullseye Framework
+
+Don't try all 19 channels. Use the Bullseye to find the one that works.
+
+### Step 1 — Brainstorm (outer ring)
+For each of the 19 channels, answer:
+- How could we use this channel?
+- What would success look like?
+- How could we test it cheaply?
+
+Produces 19 rough hypotheses.
+
+### Step 2 — Rank (middle ring)
+Score each channel on 3 criteria (1-3):
+- Probability of working
+- Volume potential (enough customers to matter)
+- Cost per acquisition (time + money)
+
+Pick the top 6 channels. These are your "promising" channels.
+
+### Step 3 — Test (inner ring — the bullseye)
+Pick the 3 channels with highest combined score. Run cheap, fast tests on each simultaneously.
+
+Each test:
+- Fixed budget (~€200-500)
+- Fixed time (2-4 weeks)
+- One metric: cost per lead, or signups, or revenue
+
+### Step 4 — Focus
+One test will outperform the others. Focus 100% on that channel. Optimize it until it no longer scales.
+
+When the channel plateaus, go back to Step 2.
+
+## Channel selection by stage
+
+Different channels dominate at different stages:
+
+| Stage | Best channels |
+|-------|--------------|
+| Pre-PMF | Direct sales, outreach, niche blogs, communities |
+| Early growth | Content, SEO, partnerships, email |
+| Scaling | Paid acquisition (once LTV:CAC proven), viral, affiliates |
+| Dominant | Brand, PR, events |
+
+**Pre-PMF rule:** channels that require scale to work (SEO, paid ads, viral) are wrong for early stage. You don't have enough data to optimize them. Use channels where you control the targeting.
+
+## Channel-market fit
+
+Some channels only work for specific markets:
+
+| Channel | Works for |
+|---------|-----------|
+| Cold outbound | B2B with clear ICP, high LTV |
+| Content/SEO | Markets that Google actively |
+| Product-led viral | Consumer, collaboration tools |
+| Community | Niche markets with strong identity |
+| Paid social | B2C with wide audience |
+| Trade shows | B2B with offline buying decisions |
+| Partnerships | Products with complementary distribution |
+
+Picking the wrong channel for your market wastes 6 months.
+
+## Cost benchmarks (rough, 2024)
+
+| Channel | Metric | B2C benchmark | B2B benchmark |
+|---------|--------|--------------|--------------|
+| Facebook/Instagram ads | CPL | €3-8 | €15-30 |
+| Google Search | CPL | €5-15 | €20-60 |
+| LinkedIn ads | CPL | - | €40-100 |
+| Cold email | CPL | - | €20-80 (time cost) |
+| Content/SEO | CPL | €5-20 (long term) | €15-50 (long term) |
+| Referral/viral | CPL | €1-5 | €5-20 |
+
+LTV must be at least 3x CAC for paid channels to be viable.
+
+## Traction metrics by channel
+
+**Viral / product-led:**
+- K-factor = (invites per user) × (invite conversion rate). Target K > 0.5 for meaningful viral effect
+- Time to viral loop: how fast does one user create another?
+
+**Content / SEO:**
+- Organic sessions per month
+- Keyword rankings for high-intent terms
+- Time to rank: SEO takes 3-6 months minimum to show results
+
+**Email:**
+- List growth rate per week
+- Open rate: >30% is good for cold; >50% for warm
+- Click-through: >5% is strong
+
+**Paid acquisition:**
+- CPL and CAC (cost per acquired customer)
+- Payback period: how many months to recoup CAC?
+- ROAS (return on ad spend)
+
+**Sales:**
+- Leads per week
+- Conversion rate (leads to paying)
+- Sales cycle length
+- Average contract value
+
+## Applying to venture analysis
+
+In Phase 3 (validation), recommend channels based on:
+
+1. Market type (B2B vs B2C)
+2. LTV estimate (high LTV = more channels viable)
+3. Available budget
+4. Target customer location (online? offline? specific communities?)
+
+For zero-budget startups, the viable channels are:
+- Direct outreach (cold email/DM) — time only
+- Niche community posting (Reddit, specific Slack/Discord groups) — time only
+- Engineering as marketing — build a free tool that attracts ICPs
+- Content on a specific topic ICP searches for
+
+For startups with €100-500/month budget:
+- Fake door test (landing page + small paid traffic)
+- LinkedIn outreach with Sales Navigator trial
+- Sponsored newsletter in a niche (often €100-300 per send)

package/skills/venture-suite/venture-analyst/scripts/enhance_detect.py

@@ -0,0 +1,172 @@
+"""
+Level 2 auto-detection.
+Silently detects available enhancements. Never asks the user for config.
+"""
+import os
+import subprocess
+import time
+import requests
+
+
+def detect_level() -> dict:
+    """
+    Detect what's available. Returns a capability map.
+    Called once at session start — results cached for the session.
+    """
+    return {
+        "docker":          _has_docker(),
+        "searxng":         _has_searxng(),
+        "veyrascrape_mcp": _has_env("VEYRASCRAPE_API_KEY"),
+        "github_token":    _has_env("GITHUB_TOKEN"),
+        "exa_key":         _has_env("EXA_API_KEY"),
+        "tavily_key":      _has_env("TAVILY_API_KEY"),
+        "groq_key":        _has_env("GROQ_API_KEY"),
+    }
+
+
+def _has_env(key: str) -> bool:
+    val = os.environ.get(key, "").strip()
+    return bool(val)
+
+
+def _has_docker() -> bool:
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=4,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def _has_searxng(ports: list[int] = None) -> bool:
+    if ports is None:
+        ports = [8080, 8888, 4000]
+    for port in ports:
+        try:
+            r = requests.get(
+                f"http://localhost:{port}/search",
+                params={"q": "test", "format": "json"},
+                timeout=2,
+            )
+            if r.status_code == 200:
+                return True
+        except Exception:
+            pass
+    return False
+
+
+def ensure_searxng() -> dict:
+    """
+    Launch SearXNG via Docker if available and not already running.
+    Returns status dict.
+    """
+    if _has_searxng():
+        return {"available": True, "url": "http://localhost:8080", "launched": False}
+
+    if not _has_docker():
+        return {"available": False, "reason": "docker_not_found"}
+
+    try:
+        subprocess.run(
+            [
+                "docker", "run", "-d",
+                "--name", "venture-searxng",
+                "-p", "8080:8080",
+                "searxng/searxng",
+            ],
+            capture_output=True,
+            timeout=45,
+        )
+        # give it time to start
+        for _ in range(6):
+            time.sleep(2)
+            if _has_searxng():
+                return {"available": True, "url": "http://localhost:8080", "launched": True}
+        return {"available": False, "reason": "searxng_start_timeout"}
+    except Exception as e:
+        return {"available": False, "reason": str(e)}
+
+
+def search_searxng(query: str, url: str = "http://localhost:8080", limit: int = 10) -> list[dict]:
+    """Search via local SearXNG instance."""
+    try:
+        r = requests.get(
+            f"{url}/search",
+            params={"q": query, "format": "json", "pageno": 1},
+            timeout=10,
+        )
+        results = r.json().get("results", [])[:limit]
+        return [
+            {
+                "source": "searxng",
+                "title": res.get("title", ""),
+                "url": res.get("url", ""),
+                "text": res.get("content", ""),
+                "engine": res.get("engine", ""),
+            }
+            for res in results
+        ]
+    except Exception:
+        return []
+
+
+def search_with_exa(query: str, api_key: str, limit: int = 10) -> list[dict]:
+    """Semantic search via Exa API (optional Level 3 enhancement)."""
+    try:
+        import exa_py
+        exa = exa_py.Exa(api_key=api_key)
+        results = exa.search(query, num_results=limit, use_autoprompt=True)
+        return [
+            {
+                "source": "exa",
+                "title": r.title or "",
+                "url": r.url,
+                "text": r.text or "",
+            }
+            for r in results.results
+        ]
+    except Exception:
+        return []
+
+
+def best_search(query: str, env: dict, limit: int = 10) -> list[dict]:
+    """
+    Use the best available search method based on detected environment.
+    Priority: Exa > SearXNG > Tavily > ddgs
+    """
+    # Level 3: Exa
+    if env.get("exa_key"):
+        results = search_with_exa(query, os.environ["EXA_API_KEY"], limit)
+        if results:
+            return results
+
+    # Level 2: SearXNG
+    if env.get("searxng"):
+        results = search_searxng(query, limit=limit)
+        if results:
+            return results
+
+    # Level 2: Tavily
+    if env.get("tavily_key"):
+        try:
+            from tavily import TavilyClient
+            client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
+            response = client.search(query, max_results=limit)
+            return [
+                {
+                    "source": "tavily",
+                    "title": r.get("title", ""),
+                    "url": r.get("url", ""),
+                    "text": r.get("content", ""),
+                }
+                for r in response.get("results", [])
+            ]
+        except Exception:
+            pass
+
+    # Level 1: ddgs (always available)
+    from scripts.sources import search_web
+    return search_web(query, limit)