mover-os 4.7.6 → 4.7.8

package/src/dashboard/lib/skill-recommender.js

@@ -0,0 +1,689 @@
+"use strict";
+
+/**
+ * skill-recommender.js — D4 of the Mover OS onboarding engine.
+ *
+ * Given a user profile extracted from setup answers, returns a ranked
+ * recommendation of skills + connectors to install.  Pure keyword/domain
+ * matching — no ML, no external calls, zero maintenance.
+ *
+ * API:
+ *   recommend(profile) → { recommended: [{skill, label, reason, confidence}],
+ *                           connectors:  [{skill, label, reason, confidence}],
+ *                           installAll:  bool }
+ *
+ *   profile shape: { work?: string, domain?: string[], tools?: string[], goals?: string[] }
+ *   All fields optional — degrades gracefully to a sensible default set.
+ *
+ * Skill catalogue reflects src/skills/ on disk as of 2026-06-18.
+ * Always-apply skills (friction-enforcer, mover-os-context, etc.) are ambient —
+ * they auto-load regardless and are NOT surfaced here (they're not additive).
+ *
+ * onboarding-engine-SPEC.md §5 D4.
+ */
+
+// ─── catalogue ────────────────────────────────────────────────────────────────
+// Each entry:
+//   skill    — slug matching src/skills/<slug>/ on disk
+//   label    — human-readable display name
+//   category — internal bucket for grouping in the UI
+//   keywords — lowercase tokens; profile text is matched against these
+//   domains  — abstract domain tags (indie-saas, engineer, marketer, …)
+//   reason   — template for the recommendation card ("because you …").
+//              %WORK% is substituted with profile.work when present.
+//   tier     — 1 (core domain skill) | 2 (supporting) | 3 (niche)
+
+const CATALOGUE = [
+  // ── Engineering / Building ──────────────────────────────────────────────────
+  {
+    skill: "systematic-debugging",
+    label: "Systematic Debugging",
+    category: "engineering",
+    keywords: ["code", "debug", "bug", "error", "fix", "crash", "logs", "test", "developer", "engineer", "build", "backend", "api", "typescript", "javascript", "python"],
+    domains: ["engineer", "indie-saas"],
+    reason: "surfaces evidence-first debugging, no more guessing, straight to root cause",
+    tier: 1,
+  },
+  {
+    skill: "tdd-enforcer",
+    label: "TDD Enforcer",
+    category: "engineering",
+    keywords: ["test", "tdd", "backend", "money", "auth", "payment", "stripe", "database", "reliability", "production"],
+    domains: ["engineer", "indie-saas"],
+    reason: "locks in test-first discipline on the code paths that can't break",
+    tier: 1,
+  },
+  {
+    skill: "error-handling-patterns",
+    label: "Error Handling Patterns",
+    category: "engineering",
+    keywords: ["api", "service", "backend", "production", "resilient", "retry", "circuit", "fallback", "outage"],
+    domains: ["engineer", "indie-saas"],
+    reason: "circuit-breaker and graceful-degradation patterns for production code",
+    tier: 2,
+  },
+  {
+    skill: "webhook-handler-patterns",
+    label: "Webhook Patterns",
+    category: "engineering",
+    keywords: ["webhook", "stripe", "event", "idempotent", "payment", "integration", "livemode"],
+    domains: ["engineer", "indie-saas"],
+    reason: "verify-first, idempotent webhook handlers that don't double-charge users",
+    tier: 2,
+  },
+  {
+    skill: "anti-slop-frontend",
+    label: "Anti-Slop Frontend",
+    category: "engineering",
+    keywords: ["frontend", "ui", "design", "react", "component", "dashboard", "interface", "css", "tailwind"],
+    domains: ["engineer", "indie-saas"],
+    reason: "prevents the AI-generated look that tanks credibility on first impression",
+    tier: 1,
+  },
+  {
+    skill: "frontend-design",
+    label: "Frontend Design",
+    category: "engineering",
+    keywords: ["frontend", "design", "ui", "component", "dashboard", "landing", "page", "interface"],
+    domains: ["engineer", "indie-saas"],
+    reason: "production-grade UI that earns trust before a word is read",
+    tier: 2,
+  },
+  {
+    skill: "ui-ux-pro-max",
+    label: "UI/UX Pro Max",
+    category: "engineering",
+    keywords: ["design", "ux", "ui", "figma", "layout", "component", "mobile", "web", "app", "react", "tailwind", "shadcn", "swiftui"],
+    domains: ["engineer", "indie-saas"],
+    reason: "layout, component, and design-review intelligence across React, Tailwind, shadcn",
+    tier: 2,
+  },
+  {
+    skill: "refactoring",
+    label: "Refactoring",
+    category: "engineering",
+    keywords: ["refactor", "clean", "technical debt", "legacy", "rewrite", "simplify", "code quality"],
+    domains: ["engineer"],
+    reason: "structured refactor assessment once the tests are green",
+    tier: 2,
+  },
+  {
+    skill: "find-bugs",
+    label: "Find Bugs",
+    category: "engineering",
+    keywords: ["security", "vulnerability", "audit", "review", "bug", "pen test", "safety"],
+    domains: ["engineer", "indie-saas"],
+    reason: "branch-level security and quality scan before you ship",
+    tier: 2,
+  },
+  {
+    skill: "code-review-lifecycle",
+    label: "Code Review Lifecycle",
+    category: "engineering",
+    keywords: ["review", "pr", "pull request", "team", "feedback", "merge"],
+    domains: ["engineer"],
+    reason: "PR lifecycle from request to merge, no dropped threads",
+    tier: 3,
+  },
+  {
+    skill: "agent-code-reviewer",
+    label: "Code Reviewer Agent",
+    category: "engineering",
+    keywords: ["architecture", "deep review", "multi-file", "complex", "codebase"],
+    domains: ["engineer"],
+    reason: "spawns a focused code/architecture review agent in a clean context",
+    tier: 3,
+  },
+
+  // ── Strategy / Business ─────────────────────────────────────────────────────
+  {
+    skill: "agent-strategy-analyst",
+    label: "Strategy Analyst Agent",
+    category: "strategy",
+    keywords: ["strategy", "hypothesis", "pivot", "pre-mortem", "investor", "decision", "bet", "direction"],
+    domains: ["founder-operator", "indie-saas"],
+    reason: "stress-tests your strategy assumptions before you commit resources",
+    tier: 1,
+  },
+  {
+    skill: "self-transcendence",
+    label: "Self-Transcendence",
+    category: "strategy",
+    keywords: ["resistance", "stuck", "motivation", "identity", "psychology", "block", "avoidance", "procrastination", "purpose"],
+    domains: ["founder-operator"],
+    reason: "identity and resistance frameworks for the /debug-resistance workflow",
+    tier: 2,
+  },
+  {
+    skill: "experiment-loop",
+    label: "Experiment Loop",
+    category: "strategy",
+    keywords: ["test", "experiment", "ab test", "optimize", "iterate", "hypothesis", "measure", "improve", "convert"],
+    domains: ["founder-operator", "marketer", "indie-saas"],
+    reason: "Darwinian test-measure-iterate cycle, for decisions that need data, not opinion",
+    tier: 1,
+  },
+
+  // ── Marketing / Growth ──────────────────────────────────────────────────────
+  {
+    skill: "copywriting",
+    label: "Copywriting",
+    category: "marketing",
+    keywords: ["copy", "headline", "cta", "landing page", "homepage", "messaging", "convert", "sales", "persuade"],
+    domains: ["marketer", "indie-saas", "freelancer", "content-creator"],
+    reason: "headlines, CTAs, and page copy that convert without sounding like a template",
+    tier: 1,
+  },
+  {
+    skill: "launch-strategy",
+    label: "Launch Strategy",
+    category: "marketing",
+    keywords: ["launch", "product hunt", "release", "go-to-market", "gtm", "beta", "announce", "ship"],
+    domains: ["indie-saas", "founder-operator"],
+    reason: "launch sequencing and momentum, from beta to Product Hunt",
+    tier: 1,
+  },
+  {
+    skill: "marketing-psychology",
+    label: "Marketing Psychology",
+    category: "marketing",
+    keywords: ["psychology", "persuasion", "behavior", "bias", "social proof", "scarcity", "urgency", "trust"],
+    domains: ["marketer", "indie-saas", "content-creator"],
+    reason: "70+ behavioral science models applied to copy, pricing, and UX",
+    tier: 1,
+  },
+  {
+    skill: "onboarding-cro",
+    label: "Onboarding CRO",
+    category: "marketing",
+    keywords: ["onboarding", "activation", "first run", "aha moment", "time to value", "new user", "churn"],
+    domains: ["indie-saas", "marketer"],
+    reason: "turns signups into activated users, the leaky bucket under every SaaS",
+    tier: 1,
+  },
+  {
+    skill: "signup-flow-cro",
+    label: "Signup Flow CRO",
+    category: "marketing",
+    keywords: ["signup", "registration", "form", "friction", "convert", "trial", "account"],
+    domains: ["indie-saas", "marketer"],
+    reason: "removes the friction that kills signups before the product gets a chance",
+    tier: 2,
+  },
+  {
+    skill: "page-cro",
+    label: "Page CRO",
+    category: "marketing",
+    keywords: ["landing page", "homepage", "pricing", "conversion", "cro", "optimize", "above fold"],
+    domains: ["marketer", "indie-saas"],
+    reason: "conversion-rate optimization for any marketing page",
+    tier: 2,
+  },
+  {
+    skill: "pricing-strategy",
+    label: "Pricing Strategy",
+    category: "marketing",
+    keywords: ["pricing", "price", "tier", "freemium", "subscription", "charge", "monetize", "revenue", "willingness to pay"],
+    domains: ["indie-saas", "founder-operator", "freelancer"],
+    reason: "packaging and pricing that doesn't leave money on the table",
+    tier: 1,
+  },
+  {
+    skill: "email-sequence",
+    label: "Email Sequences",
+    category: "marketing",
+    keywords: ["email", "drip", "nurture", "welcome", "newsletter", "sequence", "lifecycle", "list"],
+    domains: ["marketer", "indie-saas", "content-creator"],
+    reason: "welcome, nurture, and re-engagement sequences that compound over time",
+    tier: 2,
+  },
+  {
+    skill: "social-content",
+    label: "Social Content",
+    category: "marketing",
+    keywords: ["twitter", "linkedin", "instagram", "tiktok", "post", "content", "social", "thread", "tweet", "audience", "grow"],
+    domains: ["content-creator", "marketer"],
+    reason: "platform-specific content that builds an audience before you need one",
+    tier: 1,
+  },
+  {
+    skill: "paid-ads",
+    label: "Paid Ads",
+    category: "marketing",
+    keywords: ["ads", "google ads", "meta", "facebook", "paid", "roas", "campaign", "targeting", "spend"],
+    domains: ["marketer", "indie-saas"],
+    reason: "campaign strategy and ad copy that pays back more than it costs",
+    tier: 2,
+  },
+  {
+    skill: "ab-test-setup",
+    label: "A/B Test Setup",
+    category: "marketing",
+    keywords: ["ab test", "split test", "experiment", "statistical", "multivariate", "hypothesis", "test"],
+    domains: ["marketer", "indie-saas"],
+    reason: "statistically sound A/B tests, no more hunches dressed as data",
+    tier: 2,
+  },
+  {
+    skill: "analytics-tracking",
+    label: "Analytics Tracking",
+    category: "marketing",
+    keywords: ["analytics", "ga4", "google analytics", "posthog", "tracking", "utm", "gtm", "event", "funnel", "conversion"],
+    domains: ["marketer", "indie-saas"],
+    reason: "GA4/GTM/PostHog setup so decisions are based on what actually happened",
+    tier: 2,
+  },
+  {
+    skill: "referral-program",
+    label: "Referral Program",
+    category: "marketing",
+    keywords: ["referral", "affiliate", "viral", "word of mouth", "invite", "refer"],
+    domains: ["indie-saas", "marketer"],
+    reason: "referral and affiliate loops that make customers your best salespeople",
+    tier: 3,
+  },
+  {
+    skill: "seo-audit",
+    label: "SEO Audit",
+    category: "marketing",
+    keywords: ["seo", "search", "organic", "rank", "google", "traffic", "technical seo"],
+    domains: ["marketer", "indie-saas"],
+    reason: "technical and on-page SEO audit, find and fix what's killing your rank",
+    tier: 2,
+  },
+  {
+    skill: "programmatic-seo",
+    label: "Programmatic SEO",
+    category: "marketing",
+    keywords: ["programmatic seo", "directory", "location pages", "integration pages", "scale", "template"],
+    domains: ["marketer", "indie-saas"],
+    reason: "SEO at scale with templates and data, for products with natural keyword surfaces",
+    tier: 3,
+  },
+  {
+    skill: "seo-content-writer",
+    label: "SEO Content Writer",
+    category: "marketing",
+    keywords: ["seo content", "blog", "article", "keyword", "content marketing", "organic traffic"],
+    domains: ["marketer", "content-creator"],
+    reason: "keyword-targeted content that earns rankings and trust simultaneously",
+    tier: 2,
+  },
+  {
+    skill: "marketing-ideas",
+    label: "Marketing Ideas",
+    category: "marketing",
+    keywords: ["marketing", "growth", "ideas", "channel", "traction", "acquisition", "strategy"],
+    domains: ["marketer", "indie-saas", "founder-operator"],
+    reason: "140 proven growth approaches organised by stage and budget",
+    tier: 2,
+  },
+  {
+    skill: "free-tool-strategy",
+    label: "Free Tool Strategy",
+    category: "marketing",
+    keywords: ["free tool", "calculator", "generator", "widget", "acquisition", "lead magnet"],
+    domains: ["marketer", "indie-saas"],
+    reason: "free tools as compounding acquisition levers, done right they generate leads on autopilot",
+    tier: 3,
+  },
+
+  // ── Research / Intelligence ─────────────────────────────────────────────────
+  {
+    skill: "agent-research-analyst",
+    label: "Research Analyst Agent",
+    category: "research",
+    keywords: ["research", "market", "competitive", "competitor", "analysis", "intelligence", "landscape"],
+    domains: ["marketer", "founder-operator", "indie-saas"],
+    reason: "deep market + competitive research in a focused subagent context",
+    tier: 2,
+  },
+  {
+    skill: "agent-data-analyst",
+    label: "Data Analyst Agent",
+    category: "research",
+    keywords: ["data", "analytics", "metrics", "quantitative", "numbers", "analysis", "sql", "spreadsheet"],
+    domains: ["marketer", "indie-saas", "engineer"],
+    reason: "quantitative analysis subagent, surfaces the story in your numbers",
+    tier: 3,
+  },
+
+  // ── Writing / Content ───────────────────────────────────────────────────────
+  {
+    skill: "human-writer",
+    label: "Human Writer",
+    category: "writing",
+    keywords: ["write", "article", "post", "tweet", "thread", "newsletter", "email", "content", "publish", "copy", "reddit", "linkedin"],
+    domains: ["content-creator", "marketer", "freelancer"],
+    reason: "anti-AI detection, voice calibration, natural writing, for anything published under your name",
+    tier: 1,
+  },
+  {
+    skill: "agent-prompt-engineer",
+    label: "Prompt Engineer Agent",
+    category: "writing",
+    keywords: ["prompt", "ai", "llm", "gpt", "claude", "system prompt", "instruction", "context"],
+    domains: ["engineer", "indie-saas"],
+    reason: "prompt design and optimization subagent for LLM-powered features",
+    tier: 3,
+  },
+
+  // ── Obsidian / Knowledge ────────────────────────────────────────────────────
+  {
+    skill: "obsidian-markdown",
+    label: "Obsidian Markdown",
+    category: "obsidian",
+    keywords: ["obsidian", "note", "markdown", "vault", "wikilink", "callout", "frontmatter", "pkm", "knowledge"],
+    domains: ["knowledge-worker"],
+    reason: "wikilinks, callouts, and Obsidian-specific syntax, so your vault is machine-readable",
+    tier: 1,
+  },
+  {
+    skill: "obsidian-cli",
+    label: "Obsidian CLI",
+    category: "obsidian",
+    keywords: ["obsidian", "vault", "note", "search", "plugin", "theme", "cli"],
+    domains: ["knowledge-worker"],
+    reason: "read, create, and search vault notes directly from the terminal",
+    tier: 2,
+  },
+  {
+    skill: "obsidian-bases",
+    label: "Obsidian Bases",
+    category: "obsidian",
+    keywords: ["obsidian bases", "database", "table view", "filter", "formula", "card view"],
+    domains: ["knowledge-worker"],
+    reason: "database-like views over your notes, turns the vault into a queryable system",
+    tier: 2,
+  },
+  {
+    skill: "defuddle",
+    label: "Defuddle",
+    category: "obsidian",
+    keywords: ["web", "url", "article", "page", "read", "extract", "research", "browser"],
+    domains: ["knowledge-worker", "research"],
+    reason: "clean markdown from any web page, saves tokens and removes navigation clutter",
+    tier: 2,
+  },
+
+  // ── System / Tooling ────────────────────────────────────────────────────────
+  {
+    skill: "parallel-agents",
+    label: "Parallel Agents",
+    category: "system",
+    keywords: ["parallel", "agent", "concurrent", "speed", "batch", "multiple tasks"],
+    domains: ["engineer", "founder-operator"],
+    reason: "dispatch independent tasks to parallel subagents, halves wall-clock time",
+    tier: 2,
+  },
+  {
+    skill: "mover-skill-creator",
+    label: "Skill Creator",
+    category: "system",
+    keywords: ["skill", "create", "extend", "custom", "build", "new capability"],
+    domains: ["engineer", "founder-operator"],
+    reason: "create and evaluate new skills, extend the system to your exact domain",
+    tier: 3,
+  },
+];
+
+// ─── domain detector ──────────────────────────────────────────────────────────
+// Maps free-text profile fields to abstract domain buckets.
+// Returns { [domain]: score } where score = overlap count (not normalised).
+
+const DOMAIN_SIGNALS = {
+  "indie-saas":       ["saas", "product", "app", "startup", "launch", "indie", "subscription", "stripe", "software", "build", "ship", "solo"],
+  "content-creator":  ["content", "youtube", "twitter", "tiktok", "newsletter", "audience", "grow", "creator", "post", "publish", "followers", "views"],
+  "freelancer":       ["freelance", "client", "agency", "consulting", "proposal", "retainer", "contract", "invoice", "services"],
+  "engineer":         ["code", "developer", "engineer", "build", "backend", "frontend", "api", "typescript", "javascript", "python", "rust", "swift"],
+  "marketer":         ["marketing", "seo", "ads", "funnel", "conversion", "cro", "traffic", "growth", "campaign", "leads"],
+  "knowledge-worker": ["note", "obsidian", "pkm", "research", "writing", "vault", "library", "knowledge", "second brain"],
+  "founder-operator": ["founder", "ceo", "strategy", "hire", "team", "investor", "pitch", "ops", "operations", "decision"],
+};
+
+function detectDomains(profile) {
+  const text = [
+    profile.work || "",
+    (profile.domain || []).join(" "),
+    (profile.tools || []).join(" "),
+    (profile.goals || []).join(" "),
+  ].join(" ").toLowerCase();
+
+  const tokens = text.split(/[\s,;.!?]+/).filter(Boolean);
+  const scores = {};
+
+  for (const [domain, signals] of Object.entries(DOMAIN_SIGNALS)) {
+    let score = 0;
+    for (const sig of signals) {
+      // multi-word signals: substring match; single-word: exact token match
+      if (sig.includes(" ")) {
+        if (text.includes(sig)) score += 2;  // phrase match = stronger signal
+      } else {
+        if (tokens.includes(sig)) score += 1;
+      }
+    }
+    if (score > 0) scores[domain] = score;
+  }
+
+  return scores;
+}
+
+// ─── keyword scorer ───────────────────────────────────────────────────────────
+// Returns a 0–1 confidence for a single catalogue entry against the profile.
+
+function scoreEntry(entry, profileText, domainScores) {
+  const tokens = profileText.toLowerCase().split(/[\s,;.!?]+/).filter(Boolean);
+  let hits = 0;
+
+  for (const kw of entry.keywords) {
+    if (kw.includes(" ")) {
+      if (profileText.toLowerCase().includes(kw)) hits += 2;
+    } else {
+      if (tokens.includes(kw)) hits += 1;
+    }
+  }
+
+  // Domain bonus: each matching domain for this entry adds to the score
+  let domainBonus = 0;
+  for (const d of entry.domains) {
+    if (domainScores[d]) domainBonus += Math.min(domainScores[d], 3); // cap per-domain
+  }
+
+  const rawScore = hits + domainBonus;
+  const maxPossible = entry.keywords.length + entry.domains.length * 3;
+  const normalised = Math.min(rawScore / Math.max(maxPossible, 1), 1);
+
+  // Tier penalty: tier-3 skills need a higher raw score to surface
+  const tierPenalty = entry.tier === 3 ? 0.15 : entry.tier === 2 ? 0.05 : 0;
+  return Math.max(0, normalised - tierPenalty);
+}
+
+// ─── public API ───────────────────────────────────────────────────────────────
+
+/**
+ * recommend(profile) — the main entrypoint.
+ *
+ * @param {object} profile
+ *   work?   {string} — free-text "what do you work on?" answer
+ *   domain? {string[]} — optional domain tags from structured Q (e.g. ["saas","marketing"])
+ *   tools?  {string[]} — tools/stack the user mentioned
+ *   goals?  {string[]} — goals/outcomes mentioned
+ *
+ * @returns {{
+ *   recommended: Array<{skill:string, label:string, reason:string, confidence:number}>,
+ *   connectors:  Array<{skill:string, label:string, reason:string, confidence:number}>,
+ *   installAll:  boolean
+ * }}
+ */
+function recommend(profile = {}) {
+  // Robust to string OR array for the tag fields: a real setup interview yields
+  // free text, not pre-tagged arrays. Coerce each to an array before use.
+  const toArr = (v) => Array.isArray(v) ? v : (v == null ? [] : [String(v)]);
+  profile = {
+    work: String(profile.work || ""),
+    domain: toArr(profile.domain),
+    tools: toArr(profile.tools),
+    goals: toArr(profile.goals),
+  };
+  const profileText = [
+    profile.work,
+    profile.domain.join(" "),
+    profile.tools.join(" "),
+    profile.goals.join(" "),
+  ].join(" ");
+
+  const isEmpty = profileText.trim().length < 3;
+
+  // Empty profile → suggest install-all (better a full system than a partial one)
+  if (isEmpty) {
+    return {
+      recommended: [],
+      connectors:  [],
+      installAll:  true,
+    };
+  }
+
+  const domainScores = detectDomains(profile);
+  const dominantDomains = Object.entries(domainScores)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([d]) => d);
+
+  // Very broad profile (all 4 top domains score ≥ 2) → install-all is cleaner
+  const highDomains = Object.values(domainScores).filter((s) => s >= 2).length;
+  const installAll = highDomains >= 4 && Object.keys(domainScores).length >= 4;
+
+  if (installAll) {
+    return { recommended: [], connectors: [], installAll: true };
+  }
+
+  // Score every catalogue entry
+  const scored = CATALOGUE.map((entry) => ({
+    ...entry,
+    confidence: scoreEntry(entry, profileText, domainScores),
+  })).filter((e) => e.confidence > 0.05); // drop noise-floor entries
+
+  // Sort: confidence desc, then tier asc (tier 1 first when tied)
+  scored.sort((a, b) => {
+    const dc = b.confidence - a.confidence;
+    if (Math.abs(dc) > 0.01) return dc;
+    return a.tier - b.tier;
+  });
+
+  // Substitute %WORK% in reason templates
+  const work = (profile.work || "").split(/\s+/).slice(0, 5).join(" ") || "your work";
+  const withReasons = scored.map((e) => ({
+    skill: e.skill,
+    label: e.label,
+    reason: e.reason.replace(/%WORK%/g, work),
+    confidence: Math.round(e.confidence * 100) / 100,
+    category: e.category,
+  }));
+
+  // Split: connectors (marketing sub-packs) vs core domain skills
+  const MARKETING_SKILLS = new Set([
+    "copywriting", "launch-strategy", "marketing-psychology", "onboarding-cro",
+    "signup-flow-cro", "page-cro", "pricing-strategy", "email-sequence",
+    "social-content", "paid-ads", "ab-test-setup", "analytics-tracking",
+    "referral-program", "seo-audit", "programmatic-seo", "seo-content-writer",
+    "marketing-ideas", "free-tool-strategy", "schema-markup", "competitor-alternatives",
+    "form-cro", "popup-cro", "paywall-upgrade-cro",
+  ]);
+
+  const recommended = withReasons
+    .filter((e) => !MARKETING_SKILLS.has(e.skill))
+    .slice(0, 5); // cap at 5 — overwhelm is the enemy (SPEC §0 North Star)
+
+  const connectors = withReasons
+    .filter((e) => MARKETING_SKILLS.has(e.skill))
+    .slice(0, 5); // same cap for marketing connectors
+
+  return { recommended, connectors, installAll: false };
+}
+
+// ─── exports ──────────────────────────────────────────────────────────────────
+module.exports = { recommend, detectDomains, CATALOGUE };
+
+// ─── self-test (node skill-recommender.js) ────────────────────────────────────
+if (require.main === module) {
+  const assert = (condition, msg) => {
+    if (!condition) { console.error("FAIL:", msg); process.exit(1); }
+    console.log("PASS:", msg);
+  };
+
+  // ── Profile 1: Indie SaaS founder, building a product, needs to launch ──────
+  const p1 = {
+    work: "I'm building a SaaS product for freelancers, subscription billing, stripe, backend api",
+    domain: ["saas", "indie"],
+    tools: ["typescript", "react", "stripe"],
+    goals: ["launch on Product Hunt", "get first 100 paying customers", "pricing strategy"],
+  };
+  const r1 = recommend(p1);
+  assert(!r1.installAll, "p1: should NOT be install-all");
+  assert(r1.recommended.length > 0, "p1: should have recommended skills");
+  assert(r1.recommended.some((s) => ["systematic-debugging","tdd-enforcer","anti-slop-frontend"].includes(s.skill)),
+    "p1: engineering skill in recommended");
+  assert(r1.connectors.some((s) => ["launch-strategy","pricing-strategy","onboarding-cro"].includes(s.skill)),
+    "p1: launch/pricing connector present");
+  assert(r1.recommended.every((s) => s.confidence > 0.05), "p1: all recommended above noise floor");
+  console.log("  p1 recommended:", r1.recommended.map((s) => `${s.skill}(${s.confidence})`).join(", "));
+  console.log("  p1 connectors:", r1.connectors.map((s) => s.skill).join(", "));
+
+  // ── Profile 2: Content creator building an audience on Twitter/LinkedIn ──────
+  const p2 = {
+    work: "I write a newsletter and post threads on Twitter and LinkedIn. Growing my audience.",
+    domain: ["content"],
+    tools: ["twitter", "linkedin", "substack"],
+    goals: ["grow audience", "publish consistently", "monetize newsletter"],
+  };
+  const r2 = recommend(p2);
+  assert(!r2.installAll, "p2: should NOT be install-all");
+  assert(r2.recommended.some((s) => s.skill === "human-writer"), "p2: human-writer in recommended");
+  assert(r2.connectors.some((s) => ["social-content","email-sequence"].includes(s.skill)),
+    "p2: social/email connector present");
+  console.log("  p2 recommended:", r2.recommended.map((s) => s.skill).join(", "));
+  console.log("  p2 connectors:", r2.connectors.map((s) => s.skill).join(", "));
+
+  // ── Profile 3: Empty / vague profile → install-all ───────────────────────────
+  const r3 = recommend({});
+  assert(r3.installAll === true, "p3: empty profile → installAll");
+  assert(r3.recommended.length === 0, "p3: no recommended on install-all");
+  console.log("  p3 installAll:", r3.installAll);
+
+  // ── Profile 4: Obsidian/PKM knowledge worker ─────────────────────────────────
+  const p4 = {
+    work: "I use Obsidian for knowledge management, research, and writing. Second brain setup.",
+    domain: ["knowledge", "pkm"],
+    tools: ["obsidian"],
+    goals: ["better note system", "extract knowledge from research"],
+  };
+  const r4 = recommend(p4);
+  assert(!r4.installAll, "p4: knowledge worker not install-all");
+  assert(r4.recommended.some((s) => s.skill === "obsidian-markdown"), "p4: obsidian-markdown surfaced");
+  console.log("  p4 recommended:", r4.recommended.map((s) => s.skill).join(", "));
+
+  // ── Profile 5: confidence ordering — when confidence is tied, tier 1 before tier 3 ──
+  // (higher confidence always wins across tiers; tier is a tiebreaker only)
+  const p5 = {
+    work: "I build frontend apps in react and need to ship clean ui without it looking ai-generated",
+    domain: ["engineer", "frontend"],
+    tools: ["react", "tailwind", "typescript"],
+    goals: ["ship clean ui", "improve code quality"],
+  };
+  const r5 = recommend(p5);
+  assert(!r5.installAll, "p5: not install-all");
+  assert(r5.recommended.length > 0, "p5: has recommended skills");
+  // When two skills have the same confidence (within 0.01), lower tier number comes first
+  for (let i = 0; i < r5.recommended.length - 1; i++) {
+    const a = r5.recommended[i];
+    const b = r5.recommended[i + 1];
+    const ea = CATALOGUE.find((c) => c.skill === a.skill) || { tier: 2 };
+    const eb = CATALOGUE.find((c) => c.skill === b.skill) || { tier: 2 };
+    if (Math.abs(a.confidence - b.confidence) <= 0.01) {
+      assert(ea.tier <= eb.tier, `p5: tied-confidence pair ${a.skill}(t${ea.tier}) before ${b.skill}(t${eb.tier})`);
+    }
+  }
+  console.log("  p5 recommended:", r5.recommended.map((s) => `${s.skill}(t${(CATALOGUE.find(c=>c.skill===s.skill)||{tier:0}).tier},${s.confidence})`).join(", "));
+
+  console.log("\nAll self-tests passed.");
+}