godpowers 0.15.0

package/lib/artifact-diff.js

@@ -0,0 +1,168 @@
+/**
+ * Artifact Diff
+ *
+ * Regression detection between two versions of an artifact. Finds:
+ *   - Removed sections (regression)
+ *   - DECISION downgraded to HYPOTHESIS (regression)
+ *   - Reduced acceptance criteria (regression)
+ *   - New open questions without resolution (info)
+ *   - Added sections (info)
+ *
+ * Public API:
+ *   diffArtifacts(oldContent, newContent) -> { changes, regression }
+ */
+
+/**
+ * Extract markdown sections (## headings) into a map: { heading: body }.
+ */
+function extractSections(content) {
+  const sections = {};
+  const lines = content.split('\n');
+  let currentHeading = null;
+  let buffer = [];
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (currentHeading) {
+        sections[currentHeading] = buffer.join('\n').trim();
+      }
+      currentHeading = m[1].trim();
+      buffer = [];
+    } else if (currentHeading) {
+      buffer.push(line);
+    }
+  }
+  if (currentHeading) {
+    sections[currentHeading] = buffer.join('\n').trim();
+  }
+  return sections;
+}
+
+/**
+ * Count occurrences of label tags ([DECISION], [HYPOTHESIS], etc.) in content.
+ */
+function countLabels(content) {
+  const counts = {
+    DECISION: (content.match(/\[DECISION\]/g) || []).length,
+    HYPOTHESIS: (content.match(/\[HYPOTHESIS\]/g) || []).length,
+    'OPEN QUESTION': (content.match(/\[OPEN QUESTION\]/g) || []).length
+  };
+  return counts;
+}
+
+/**
+ * Count list items (bullets) in content.
+ */
+function countListItems(content) {
+  return (content.match(/^[\s]*[-*]\s+/gm) || []).length;
+}
+
+/**
+ * Diff two artifact versions and detect regressions.
+ *
+ * Returns:
+ *   {
+ *     regression: bool,
+ *     changes: [{ kind, severity, section, message }]
+ *   }
+ */
+function diffArtifacts(oldContent, newContent) {
+  const changes = [];
+  const oldSections = extractSections(oldContent);
+  const newSections = extractSections(newContent);
+
+  // Check for removed sections
+  for (const heading of Object.keys(oldSections)) {
+    if (!(heading in newSections)) {
+      changes.push({
+        kind: 'section-removed',
+        severity: 'error',
+        section: heading,
+        message: `Section "${heading}" was removed.`
+      });
+    }
+  }
+
+  // Check for added sections (informational)
+  for (const heading of Object.keys(newSections)) {
+    if (!(heading in oldSections)) {
+      changes.push({
+        kind: 'section-added',
+        severity: 'info',
+        section: heading,
+        message: `Section "${heading}" was added.`
+      });
+    }
+  }
+
+  // Check for label downgrades (DECISION -> HYPOTHESIS) per section
+  for (const heading of Object.keys(newSections)) {
+    if (!(heading in oldSections)) continue;
+    const oldCounts = countLabels(oldSections[heading]);
+    const newCounts = countLabels(newSections[heading]);
+
+    if (newCounts.DECISION < oldCounts.DECISION) {
+      const dropped = oldCounts.DECISION - newCounts.DECISION;
+      changes.push({
+        kind: 'decision-downgraded',
+        severity: 'warning',
+        section: heading,
+        message: `${dropped} [DECISION] tag(s) lost in section "${heading}" (was ${oldCounts.DECISION}, now ${newCounts.DECISION}).`
+      });
+    }
+
+    // Reduced acceptance criteria: if list item count drops in MUST/SHOULD requirements
+    if (heading.match(/Functional Requirements|Requirements/i)) {
+      const oldItems = countListItems(oldSections[heading]);
+      const newItems = countListItems(newSections[heading]);
+      if (newItems < oldItems) {
+        changes.push({
+          kind: 'acceptance-reduced',
+          severity: 'warning',
+          section: heading,
+          message: `Acceptance criteria reduced in "${heading}" (${oldItems} -> ${newItems} items).`
+        });
+      }
+    }
+
+    // New open questions without resolution
+    if (heading.match(/Open Questions/i)) {
+      const oldOQ = oldCounts['OPEN QUESTION'];
+      const newOQ = newCounts['OPEN QUESTION'];
+      if (newOQ > oldOQ) {
+        changes.push({
+          kind: 'open-question-added',
+          severity: 'info',
+          section: heading,
+          message: `${newOQ - oldOQ} new open question(s) added.`
+        });
+      }
+    }
+  }
+
+  // Determine regression: any error or warning is a regression
+  const regression = changes.some(c => c.severity === 'error' || c.severity === 'warning');
+
+  return { regression, changes };
+}
+
+/**
+ * Format diff as human-readable report.
+ */
+function formatDiff(diff) {
+  const lines = [];
+  lines.push(`Regression: ${diff.regression ? 'YES' : 'no'}`);
+  lines.push(`Changes: ${diff.changes.length}`);
+  for (const c of diff.changes) {
+    lines.push(`  [${c.kind}] ${c.severity.toUpperCase()} (${c.section}): ${c.message}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  diffArtifacts,
+  extractSections,
+  countLabels,
+  countListItems,
+  formatDiff
+};

package/lib/artifact-linter.js

@@ -0,0 +1,142 @@
+/**
+ * Artifact Linter
+ *
+ * Orchestrator for per-artifact lint runs. Detects artifact type from path,
+ * loads the file, runs the right have-nots checks, returns structured
+ * findings.
+ *
+ * Public API:
+ *   detectType(filePath) -> 'prd'|'arch'|'roadmap'|'stack'|'design'|'product'|null
+ *   lintFile(filePath, opts) -> { type, findings, summary }
+ *   lintAll(projectRoot, opts) -> [{ path, type, findings, summary }, ...]
+ *
+ * Findings structure:
+ *   { code, severity, line, column, message, suggestion }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const validator = require('./have-nots-validator');
+
+/**
+ * Detect artifact type from path. Returns null for unknown.
+ */
+function detectType(filePath) {
+  const lower = filePath.toLowerCase();
+  const basename = path.basename(lower);
+  if (lower.includes('/prd/') || basename === 'prd.md') return 'prd';
+  if (lower.includes('/arch/') || basename === 'arch.md') return 'arch';
+  if (lower.includes('/roadmap/') || basename === 'roadmap.md') return 'roadmap';
+  if (lower.includes('/stack/') || basename === 'stack-decision.md' || basename === 'decision.md') return 'stack';
+  if (basename === 'design.md') return 'design';
+  if (basename === 'product.md') return 'product';
+  if (basename === 'postmortem.md') return 'postmortem';
+  if (basename === 'spike.md') return 'spike';
+  if (basename === 'migration.md') return 'migration';
+  return null;
+}
+
+/**
+ * Lint a single file. Returns { type, findings, summary }.
+ */
+function lintFile(filePath, opts = {}) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  const type = detectType(filePath);
+  const ctx = {
+    projectRoot: opts.projectRoot || process.cwd(),
+    docDir: path.dirname(filePath),
+    today: opts.today,
+    prdContent: opts.prdContent,
+    ...opts
+  };
+
+  // For ARCH, auto-load PRD if not provided
+  if (type === 'arch' && !ctx.prdContent) {
+    const prdPath = path.join(ctx.projectRoot, '.godpowers', 'prd', 'PRD.md');
+    if (fs.existsSync(prdPath)) {
+      ctx.prdContent = fs.readFileSync(prdPath, 'utf8');
+    }
+  }
+
+  const findings = validator.runChecks(content, type, ctx);
+  const summary = validator.summarize(findings);
+
+  return {
+    path: filePath,
+    type: type || 'unknown',
+    findings,
+    summary
+  };
+}
+
+/**
+ * Lint all known artifacts in a project.
+ */
+function lintAll(projectRoot, opts = {}) {
+  const root = projectRoot || process.cwd();
+  const candidates = [
+    '.godpowers/prd/PRD.md',
+    '.godpowers/arch/ARCH.md',
+    '.godpowers/roadmap/ROADMAP.md',
+    '.godpowers/stack/DECISION.md',
+    '.godpowers/design/DESIGN.md',
+    'DESIGN.md',
+    'PRODUCT.md'
+  ];
+  const results = [];
+  for (const rel of candidates) {
+    const full = path.join(root, rel);
+    if (fs.existsSync(full)) {
+      results.push(lintFile(full, { projectRoot: root, ...opts }));
+    }
+  }
+  return results;
+}
+
+/**
+ * Format findings as a human-readable report string.
+ */
+function formatReport(result) {
+  const lines = [];
+  lines.push(`\n${result.path}`);
+  lines.push(`  Type: ${result.type}`);
+  lines.push(`  Errors: ${result.summary.errors}, Warnings: ${result.summary.warnings}, Info: ${result.summary.infos}`);
+  if (result.findings.length === 0) {
+    lines.push('  Clean: no findings.');
+    return lines.join('\n');
+  }
+  for (const f of result.findings) {
+    lines.push(`  [${f.code}] ${f.severity.toUpperCase()} line ${f.line}: ${f.message}`);
+    if (f.suggestion) {
+      lines.push(`         -> ${f.suggestion}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Aggregate summary across multiple lint results.
+ */
+function aggregate(results) {
+  const totals = { errors: 0, warnings: 0, infos: 0, byCode: {}, files: results.length };
+  for (const r of results) {
+    totals.errors += r.summary.errors;
+    totals.warnings += r.summary.warnings;
+    totals.infos += r.summary.infos;
+    for (const code of Object.keys(r.summary.byCode)) {
+      totals.byCode[code] = (totals.byCode[code] || 0) + r.summary.byCode[code];
+    }
+  }
+  return totals;
+}
+
+module.exports = {
+  detectType,
+  lintFile,
+  lintAll,
+  formatReport,
+  aggregate
+};

package/lib/awesome-design.js

@@ -0,0 +1,312 @@
+/**
+ * Awesome DESIGN.md catalog integration
+ *
+ * Detect when a user's PRD / PRODUCT.md / free-text intent mentions a
+ * known site, then offer the corresponding curated DESIGN.md from
+ * VoltAgent's awesome-design-md collection
+ * (https://github.com/VoltAgent/awesome-design-md, MIT license).
+ *
+ * Strategy:
+ *   - Fixed catalog of 71 slugs (matches the repo as of 2026-05-10)
+ *   - Per-project cache at .godpowers/cache/awesome-design/<slug>.md
+ *   - Fetch lazily (no upfront vendoring)
+ *   - Identify mentions via case-insensitive name + display-name match
+ *
+ * Public API:
+ *   list() -> [{ slug, displayName, category, url }, ...]
+ *   lookupSite(name) -> entry or null
+ *   extractSiteReferences(text) -> [...entries]
+ *   cachePath(projectRoot, slug) -> string
+ *   isCached(projectRoot, slug) -> bool
+ *   fetchDesign(projectRoot, slug, opts) -> { content, cached, error }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const RAW_BASE = 'https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md';
+const PREVIEW_BASE = 'https://getdesign.md';
+
+/**
+ * Catalog. Each entry has:
+ *   slug         - the URL slug used in the repo (e.g., 'linear.app')
+ *   displayName  - the human-readable name shown in README
+ *   category     - one of: ai-llm, dev-tools, backend-data, productivity,
+ *                  design-tools, fintech, ecommerce, media-consumer, automotive
+ *   aliases      - array of common forms (lowercased, no spaces)
+ */
+const CATALOG = [
+  // AI & LLM Platforms
+  { slug: 'claude', displayName: 'Claude', category: 'ai-llm', aliases: ['claude', 'anthropic'] },
+  { slug: 'cohere', displayName: 'Cohere', category: 'ai-llm', aliases: ['cohere'] },
+  { slug: 'elevenlabs', displayName: 'ElevenLabs', category: 'ai-llm', aliases: ['elevenlabs', '11labs'] },
+  { slug: 'minimax', displayName: 'Minimax', category: 'ai-llm', aliases: ['minimax'] },
+  { slug: 'mistral.ai', displayName: 'Mistral AI', category: 'ai-llm', aliases: ['mistral', 'mistralai', 'mistral-ai'] },
+  { slug: 'ollama', displayName: 'Ollama', category: 'ai-llm', aliases: ['ollama'] },
+  { slug: 'opencode.ai', displayName: 'OpenCode AI', category: 'ai-llm', aliases: ['opencode', 'opencodeai'] },
+  { slug: 'replicate', displayName: 'Replicate', category: 'ai-llm', aliases: ['replicate'] },
+  { slug: 'runwayml', displayName: 'Runway', category: 'ai-llm', aliases: ['runway', 'runwayml'] },
+  { slug: 'together.ai', displayName: 'Together AI', category: 'ai-llm', aliases: ['together', 'togetherai', 'together-ai'] },
+  { slug: 'voltagent', displayName: 'VoltAgent', category: 'ai-llm', aliases: ['voltagent'] },
+  { slug: 'x.ai', displayName: 'xAI', category: 'ai-llm', aliases: ['xai', 'x-ai', 'x.ai', 'grok'] },
+
+  // Developer Tools & IDEs
+  { slug: 'cursor', displayName: 'Cursor', category: 'dev-tools', aliases: ['cursor'] },
+  { slug: 'expo', displayName: 'Expo', category: 'dev-tools', aliases: ['expo'] },
+  { slug: 'lovable', displayName: 'Lovable', category: 'dev-tools', aliases: ['lovable'] },
+  { slug: 'raycast', displayName: 'Raycast', category: 'dev-tools', aliases: ['raycast'] },
+  { slug: 'superhuman', displayName: 'Superhuman', category: 'dev-tools', aliases: ['superhuman'] },
+  { slug: 'vercel', displayName: 'Vercel', category: 'dev-tools', aliases: ['vercel'] },
+  { slug: 'warp', displayName: 'Warp', category: 'dev-tools', aliases: ['warp'] },
+
+  // Backend, Database & DevOps
+  { slug: 'clickhouse', displayName: 'ClickHouse', category: 'backend-data', aliases: ['clickhouse'] },
+  { slug: 'composio', displayName: 'Composio', category: 'backend-data', aliases: ['composio'] },
+  { slug: 'hashicorp', displayName: 'HashiCorp', category: 'backend-data', aliases: ['hashicorp'] },
+  { slug: 'mongodb', displayName: 'MongoDB', category: 'backend-data', aliases: ['mongodb', 'mongo'] },
+  { slug: 'posthog', displayName: 'PostHog', category: 'backend-data', aliases: ['posthog'] },
+  { slug: 'sanity', displayName: 'Sanity', category: 'backend-data', aliases: ['sanity'] },
+  { slug: 'sentry', displayName: 'Sentry', category: 'backend-data', aliases: ['sentry'] },
+  { slug: 'supabase', displayName: 'Supabase', category: 'backend-data', aliases: ['supabase'] },
+
+  // Productivity & SaaS
+  { slug: 'cal', displayName: 'Cal.com', category: 'productivity', aliases: ['cal', 'calcom', 'cal.com'] },
+  { slug: 'intercom', displayName: 'Intercom', category: 'productivity', aliases: ['intercom'] },
+  { slug: 'linear.app', displayName: 'Linear', category: 'productivity', aliases: ['linear', 'linear.app', 'linearapp'] },
+  { slug: 'mintlify', displayName: 'Mintlify', category: 'productivity', aliases: ['mintlify'] },
+  { slug: 'notion', displayName: 'Notion', category: 'productivity', aliases: ['notion'] },
+  { slug: 'resend', displayName: 'Resend', category: 'productivity', aliases: ['resend'] },
+  { slug: 'slack', displayName: 'Slack', category: 'productivity', aliases: ['slack'] },
+  { slug: 'zapier', displayName: 'Zapier', category: 'productivity', aliases: ['zapier'] },
+
+  // Design & Creative Tools
+  { slug: 'airtable', displayName: 'Airtable', category: 'design-tools', aliases: ['airtable'] },
+  { slug: 'clay', displayName: 'Clay', category: 'design-tools', aliases: ['clay'] },
+  { slug: 'figma', displayName: 'Figma', category: 'design-tools', aliases: ['figma'] },
+  { slug: 'framer', displayName: 'Framer', category: 'design-tools', aliases: ['framer'] },
+  { slug: 'miro', displayName: 'Miro', category: 'design-tools', aliases: ['miro'] },
+  { slug: 'webflow', displayName: 'Webflow', category: 'design-tools', aliases: ['webflow'] },
+
+  // Fintech & Crypto
+  { slug: 'binance', displayName: 'Binance', category: 'fintech', aliases: ['binance'] },
+  { slug: 'coinbase', displayName: 'Coinbase', category: 'fintech', aliases: ['coinbase'] },
+  { slug: 'kraken', displayName: 'Kraken', category: 'fintech', aliases: ['kraken'] },
+  { slug: 'mastercard', displayName: 'Mastercard', category: 'fintech', aliases: ['mastercard'] },
+  { slug: 'revolut', displayName: 'Revolut', category: 'fintech', aliases: ['revolut'] },
+  { slug: 'stripe', displayName: 'Stripe', category: 'fintech', aliases: ['stripe'] },
+  { slug: 'wise', displayName: 'Wise', category: 'fintech', aliases: ['wise'] },
+
+  // E-commerce & Retail
+  { slug: 'airbnb', displayName: 'Airbnb', category: 'ecommerce', aliases: ['airbnb'] },
+  { slug: 'meta', displayName: 'Meta', category: 'ecommerce', aliases: ['meta'] },
+  { slug: 'nike', displayName: 'Nike', category: 'ecommerce', aliases: ['nike'] },
+  { slug: 'shopify', displayName: 'Shopify', category: 'ecommerce', aliases: ['shopify'] },
+  { slug: 'starbucks', displayName: 'Starbucks', category: 'ecommerce', aliases: ['starbucks'] },
+
+  // Media & Consumer Tech
+  { slug: 'apple', displayName: 'Apple', category: 'media-consumer', aliases: ['apple'] },
+  { slug: 'ibm', displayName: 'IBM', category: 'media-consumer', aliases: ['ibm'] },
+  { slug: 'nvidia', displayName: 'NVIDIA', category: 'media-consumer', aliases: ['nvidia'] },
+  { slug: 'pinterest', displayName: 'Pinterest', category: 'media-consumer', aliases: ['pinterest'] },
+  { slug: 'playstation', displayName: 'PlayStation', category: 'media-consumer', aliases: ['playstation', 'ps5', 'sony'] },
+  { slug: 'spacex', displayName: 'SpaceX', category: 'media-consumer', aliases: ['spacex'] },
+  { slug: 'spotify', displayName: 'Spotify', category: 'media-consumer', aliases: ['spotify'] },
+  { slug: 'theverge', displayName: 'The Verge', category: 'media-consumer', aliases: ['theverge', 'verge', 'the verge', 'the-verge'] },
+  { slug: 'uber', displayName: 'Uber', category: 'media-consumer', aliases: ['uber'] },
+  { slug: 'vodafone', displayName: 'Vodafone', category: 'media-consumer', aliases: ['vodafone'] },
+  { slug: 'wired', displayName: 'WIRED', category: 'media-consumer', aliases: ['wired'] },
+
+  // Automotive
+  { slug: 'bmw', displayName: 'BMW', category: 'automotive', aliases: ['bmw'] },
+  { slug: 'bmw-m', displayName: 'BMW M', category: 'automotive', aliases: ['bmw m', 'bmwm', 'bmw-m'] },
+  { slug: 'bugatti', displayName: 'Bugatti', category: 'automotive', aliases: ['bugatti'] },
+  { slug: 'ferrari', displayName: 'Ferrari', category: 'automotive', aliases: ['ferrari'] },
+  { slug: 'lamborghini', displayName: 'Lamborghini', category: 'automotive', aliases: ['lamborghini', 'lambo'] },
+  { slug: 'renault', displayName: 'Renault', category: 'automotive', aliases: ['renault'] },
+  { slug: 'tesla', displayName: 'Tesla', category: 'automotive', aliases: ['tesla'] }
+];
+
+/**
+ * Return the full list with URLs.
+ */
+function list() {
+  return CATALOG.map(entry => ({
+    ...entry,
+    rawUrl: `${RAW_BASE}/${entry.slug}/DESIGN.md`,
+    previewUrl: `${PREVIEW_BASE}/${entry.slug}/design-md`
+  }));
+}
+
+/**
+ * Normalize a name for matching: lowercase, strip whitespace and punctuation.
+ */
+function normalize(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[\s.\-_]+/g, '')
+    .trim();
+}
+
+/**
+ * Look up a site by name. Matches against displayName + aliases (case
+ * insensitive, punctuation-insensitive).
+ */
+function lookupSite(name) {
+  const norm = normalize(name);
+  if (!norm) return null;
+  for (const entry of CATALOG) {
+    if (normalize(entry.displayName) === norm) {
+      return { ...entry, matchedOn: 'displayName' };
+    }
+    if (normalize(entry.slug) === norm) {
+      return { ...entry, matchedOn: 'slug' };
+    }
+    for (const alias of entry.aliases) {
+      if (normalize(alias) === norm) {
+        return { ...entry, matchedOn: 'alias' };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan free text for mentions of known sites. Returns deduplicated entries.
+ *
+ * Looks for:
+ *   - Direct mentions of displayName / slug / aliases (word-boundary)
+ *   - Phrases like "feel like X", "similar to X", "looks like X"
+ */
+function extractSiteReferences(text) {
+  if (!text) return [];
+  const found = new Map();
+  const lower = String(text).toLowerCase();
+
+  for (const entry of CATALOG) {
+    const candidates = [entry.displayName, entry.slug, ...entry.aliases];
+    for (const candidate of candidates) {
+      const normCand = candidate.toLowerCase();
+      if (normCand.length < 3) continue; // skip too-short tokens
+      // Word-boundary regex (escape special chars)
+      const escaped = candidate.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').toLowerCase();
+      const regex = new RegExp(`\\b${escaped}\\b`, 'i');
+      if (regex.test(lower)) {
+        if (!found.has(entry.slug)) {
+          found.set(entry.slug, {
+            ...entry,
+            matchedTerm: candidate,
+            rawUrl: `${RAW_BASE}/${entry.slug}/DESIGN.md`,
+            previewUrl: `${PREVIEW_BASE}/${entry.slug}/design-md`
+          });
+        }
+        break; // first match per entry is enough
+      }
+    }
+  }
+  return [...found.values()];
+}
+
+/**
+ * Cache file path for a given slug in a project.
+ */
+function cachePath(projectRoot, slug) {
+  return path.join(projectRoot, '.godpowers', 'cache', 'awesome-design', `${slug}.md`);
+}
+
+function isCached(projectRoot, slug) {
+  return fs.existsSync(cachePath(projectRoot, slug));
+}
+
+/**
+ * Fetch a DESIGN.md by slug. Synchronous-style API using callbacks
+ * because Node's https is callback-based and we don't want to require
+ * Promise wrappers for tests. Returns a Promise for runtime use.
+ */
+function fetchDesign(projectRoot, slug, opts = {}) {
+  return new Promise((resolve) => {
+    const cached = cachePath(projectRoot, slug);
+    if (!opts.refresh && fs.existsSync(cached)) {
+      try {
+        return resolve({
+          content: fs.readFileSync(cached, 'utf8'),
+          cached: true,
+          error: null
+        });
+      } catch (e) {
+        return resolve({ content: '', cached: false, error: e.message });
+      }
+    }
+    const url = `${RAW_BASE}/${slug}/DESIGN.md`;
+    https.get(url, (res) => {
+      if (res.statusCode !== 200) {
+        return resolve({ content: '', cached: false, error: `HTTP ${res.statusCode}` });
+      }
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        try {
+          fs.mkdirSync(path.dirname(cached), { recursive: true });
+          fs.writeFileSync(cached, data);
+        } catch (e) {
+          // Cache failure non-fatal; still return content
+        }
+        resolve({ content: data, cached: false, error: null });
+      });
+    }).on('error', (err) => {
+      resolve({ content: '', cached: false, error: err.message });
+    });
+  });
+}
+
+/**
+ * Suggest sites that might fit a brand description (heuristic).
+ * E.g., "minimal dark dev tool" -> Linear, Vercel, Cursor.
+ */
+function suggestByBrandHints(text) {
+  if (!text) return [];
+  const lower = String(text).toLowerCase();
+  const suggestions = [];
+
+  const rules = [
+    { keywords: ['minimal', 'minimalist', 'dark dev'], slugs: ['linear.app', 'vercel', 'cursor'] },
+    { keywords: ['warm', 'editorial', 'serif'], slugs: ['notion', 'wired', 'theverge'] },
+    { keywords: ['fintech', 'payment', 'banking'], slugs: ['stripe', 'wise', 'revolut'] },
+    { keywords: ['ai assistant', 'llm', 'chat'], slugs: ['claude', 'cohere', 'mistral.ai'] },
+    { keywords: ['e-commerce', 'shop', 'retail'], slugs: ['shopify', 'airbnb'] },
+    { keywords: ['developer tools', 'devops'], slugs: ['vercel', 'supabase', 'sentry'] },
+    { keywords: ['terminal', 'code editor'], slugs: ['warp', 'cursor', 'raycast'] },
+    { keywords: ['premium', 'luxury'], slugs: ['apple', 'tesla', 'ferrari'] }
+  ];
+
+  for (const rule of rules) {
+    if (rule.keywords.some(k => lower.includes(k))) {
+      for (const slug of rule.slugs) {
+        const entry = CATALOG.find(e => e.slug === slug);
+        if (entry && !suggestions.find(s => s.slug === slug)) {
+          suggestions.push({
+            ...entry,
+            rawUrl: `${RAW_BASE}/${entry.slug}/DESIGN.md`,
+            previewUrl: `${PREVIEW_BASE}/${entry.slug}/design-md`,
+            reason: `matched keyword "${rule.keywords.find(k => lower.includes(k))}"`
+          });
+        }
+      }
+    }
+  }
+  return suggestions;
+}
+
+module.exports = {
+  CATALOG,
+  RAW_BASE,
+  PREVIEW_BASE,
+  list,
+  lookupSite,
+  extractSiteReferences,
+  suggestByBrandHints,
+  cachePath,
+  isCached,
+  fetchDesign,
+  normalize
+};