@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/topical-authority/references/serp-clustering-algorithm.md

@@ -0,0 +1,325 @@
+# SERP Clustering Algorithm
+
+**Purpose**: Prevent keyword cannibalization by grouping keywords with identical search intent
+
+## The Problem: Keyword Cannibalization
+
+When multiple pages on your site target keywords with the same search intent, they compete against each other for rankings. Google will typically only rank one page from your site for a given search intent, so multiple pages dilute your authority instead of multiplying it.
+
+**Example**:
+- Page A targets "email marketing tools"
+- Page B targets "best email marketing software"
+- SERP overlap: 85% (same domains appear in top 10)
+- Result: Pages compete, both rank lower than if you had one comprehensive page
+
+## The Solution: SERP-Based Clustering
+
+Group keywords by analyzing their search results. If two keywords show the same URLs in their top 10 results, Google considers them to have the same search intent.
+
+## Algorithm
+
+### Step 1: Fetch SERP URLs
+For each keyword in your universe:
+1. Query Google (or SERP API)
+2. Extract top 10 organic results
+3. Store: `[keyword → [url1, url2, ..., url10]]`
+4. Rate limit: 2-3 seconds between requests (avoid blocking)
+5. Cache results (SERPs don't change daily)
+
+### Step 2: Calculate Jaccard Similarity
+For each pair of keywords, calculate URL overlap:
+
+```
+Jaccard Similarity = |A ∩ B| / |A ∪ B|
+
+Where:
+- A = Set of domains in keyword A's top 10
+- B = Set of domains in keyword B's top 10
+- ∩ = Intersection (domains in both sets)
+- ∪ = Union (all unique domains)
+```
+
+**Example**:
+```
+Keyword A top 10 domains: [zapier.com, buffer.com, hootsuite.com, hubspot.com, semrush.com, ahrefs.com, moz.com, ...]
+Keyword B top 10 domains: [zapier.com, buffer.com, hootsuite.com, hubspot.com, mailchimp.com, sendgrid.com, activecampaign.com, ...]
+
+Intersection: [zapier.com, buffer.com, hootsuite.com, hubspot.com] = 4 domains
+Union: 13 unique domains
+
+Jaccard Similarity = 4 / 13 = 0.31 (31% overlap)
+```
+
+### Step 3: Three-Tier Classification
+
+**Tier 1: Obvious Same Intent (≥70% overlap)**
+- Action: Group into same cluster automatically
+- Reason: High overlap = Google sees these as identical intent
+- Example: "email marketing tools" vs "best email marketing software" (85% overlap)
+- Cost: Free (no AI needed)
+
+**Tier 2: Ambiguous (30-69% overlap)**
+- Action: Use Gemini/GPT-4 to analyze intent
+- Reason: Medium overlap = unclear if intent is same or different
+- Example: "content marketing tools" vs "social media marketing tools" (45% overlap)
+- Cost: ~$0.001 per comparison
+- Optimization: Only call AI for ambiguous cases (saves 70-80% of AI costs)
+
+**Tier 3: Obvious Different Intent (<30% overlap)**
+- Action: Keep in separate clusters automatically
+- Reason: Low overlap = Google sees these as different intent
+- Example: "email marketing" vs "email marketing automation" (25% overlap)
+- Cost: Free (no AI needed)
+
+### Step 4: Gemini Intent Analysis (Tier 2 Only)
+
+**Prompt Template**:
+```
+You are an SEO search intent analyzer.
+Compare these two keywords and determine if they have the SAME search intent (should be on same page) or DIFFERENT intent (need separate pages).
+
+Keyword 1: "{keyword1}"
+Keyword 2: "{keyword2}"
+
+Return ONLY "SAME" or "DIFFERENT". No explanation.
+
+SAME = Same topic, same user goal, same type of content expected
+DIFFERENT = Different topics, different user goals, or different content types
+
+Examples:
+Q: "email marketing tools" vs "best email marketing software" → SAME
+Q: "email marketing" vs "email marketing automation" → DIFFERENT
+Q: "content calendar" vs "social media calendar" → SAME
+Q: "seo tools" vs "seo strategy" → DIFFERENT
+```
+
+**Response Parsing**:
+- If response contains "SAME" → Group into same cluster
+- If response contains "DIFFERENT" → Keep in separate clusters
+- If error/timeout → Default to DIFFERENT (conservative approach)
+
+### Step 5: Cluster Merging
+
+After pairwise comparisons, merge overlapping clusters:
+
+```javascript
+// Cluster building algorithm
+const clusters = [];
+
+for (const [kw1, kw2] of keyword_pairs) {
+  const similarity = calculateJaccardSimilarity(kw1, kw2);
+  let shouldCluster = false;
+
+  if (similarity >= 0.7) {
+    shouldCluster = true; // Obvious same
+  } else if (similarity < 0.3) {
+    shouldCluster = false; // Obvious different
+  } else {
+    shouldCluster = analyzeIntentWithGemini(kw1, kw2); // Ambiguous
+  }
+
+  if (shouldCluster) {
+    // Find existing cluster or create new one
+    let cluster = clusters.find(c => c.keywords.includes(kw1) || c.keywords.includes(kw2));
+
+    if (cluster) {
+      // Add to existing cluster
+      if (!cluster.keywords.includes(kw1)) cluster.keywords.push(kw1);
+      if (!cluster.keywords.includes(kw2)) cluster.keywords.push(kw2);
+    } else {
+      // Create new cluster
+      clusters.push({ keywords: [kw1, kw2] });
+    }
+  }
+}
+```
+
+### Step 6: Singleton Handling
+
+Keywords not clustered with any others become singleton clusters (one keyword = one page).
+
+## Cost Optimization
+
+**Traditional approach**: Call SERP API + AI for every keyword pair
+- 500 keywords = 124,750 pairs
+- Cost: $0.01 per API call = $1,247.50
+- Time: Hours to days
+
+**Our optimized approach**: Jaccard similarity + selective AI
+- Free: 70% obvious same (≥70% overlap)
+- Free: 20% obvious different (<30% overlap)
+- AI: 10% ambiguous (30-69% overlap)
+- Cost for 500 keywords: ~$2-5 (only 12,475 AI calls)
+- Time: 10-30 minutes
+
+**Savings**: 99.5% cost reduction
+
+## Implementation Details
+
+### SERP Fetching Options
+
+**Option 1: Free HTTP Requests** (Development)
+```javascript
+async function fetchGoogleSERP(keyword) {
+  const url = `https://www.google.com/search?q=${encodeURIComponent(keyword)}`;
+  // Parse HTML, extract top 10 domains
+  // Rate limit: 2-3 seconds between requests
+  // Risk: Google may block after ~100 requests
+}
+```
+
+**Option 2: SERP APIs** (Production)
+- DataForSEO: $0.002 per keyword
+- SerpAPI: $0.004 per keyword
+- ValueSERP: $0.003 per keyword
+- Benefit: Reliable, no blocking, structured data
+
+**Option 3: Browser Automation** (Alternative)
+- Puppeteer/Playwright with rotating proxies
+- Cost: Proxy fees (~$5/mo)
+- Benefit: More reliable than raw HTTP
+
+### Caching Strategy
+
+```javascript
+// Cache SERP results to avoid re-fetching
+const cache = {
+  keyword: {
+    urls: [...],
+    fetchedAt: ISO_timestamp,
+    ttl: 30_days // SERPs don't change daily
+  }
+};
+```
+
+### Checkpointing
+
+For large keyword sets (1,000+), save progress every 100 keywords:
+```javascript
+if (processedCount % 100 === 0) {
+  saveCheckpoint(clusters, processedCount);
+}
+```
+
+## Output Format
+
+```json
+{
+  "clusters": [
+    {
+      "id": "cluster-1",
+      "keywords": [
+        "email marketing tools",
+        "best email marketing software",
+        "top email marketing platforms"
+      ],
+      "size": 3,
+      "primaryKeyword": "email marketing tools",
+      "avgOverlap": 0.82
+    },
+    {
+      "id": "cluster-2",
+      "keywords": ["email marketing automation"],
+      "size": 1,
+      "primaryKeyword": "email marketing automation",
+      "avgOverlap": 0
+    }
+  ],
+  "summary": {
+    "totalKeywords": 500,
+    "totalClusters": 87,
+    "avgClusterSize": 5.7,
+    "singletons": 23,
+    "geminiCalls": 12,
+    "estimatedCost": "0.012"
+  }
+}
+```
+
+## Validation
+
+**Quality Checks**:
+1. No keyword appears in multiple clusters (mutual exclusivity)
+2. All keywords accounted for (clustered or singleton)
+3. Cluster sizes make sense (most 1-10 keywords, few outliers)
+4. Primary keyword is most generic in cluster
+
+**Manual Spot Checks**:
+- Sample 10 clusters
+- Verify keywords have same intent
+- Check if SERP overlap makes sense
+
+## Common Edge Cases
+
+### 1. Brand vs Generic Keywords
+```
+"mailchimp" vs "email marketing software"
+```
+- SERP overlap: 15% (mailchimp.com dominates first, not second)
+- Action: Separate clusters (different intent: branded vs category)
+
+### 2. How-to vs What-is
+```
+"how to do email marketing" vs "what is email marketing"
+```
+- SERP overlap: 35% (ambiguous)
+- Gemini: DIFFERENT (how-to = implementation, what-is = definition)
+- Action: Separate clusters
+
+### 3. Singular vs Plural
+```
+"email marketing tool" vs "email marketing tools"
+```
+- SERP overlap: 95% (nearly identical)
+- Action: Same cluster
+
+### 4. Year-Specific Keywords
+```
+"email marketing tools 2024" vs "email marketing tools 2025"
+```
+- SERP overlap: 60% (ambiguous)
+- Gemini: SAME (same intent, just time-specific)
+- Action: Same cluster, update content yearly
+
+## Integration with Hub Architecture
+
+After clustering:
+1. Large clusters (5+ keywords) → Pillar pages
+2. Medium clusters (2-4 keywords) → Supporting cluster pages
+3. Singletons → Decide: Create page or merge into related cluster
+
+## Performance Benchmarks
+
+**500 keywords**:
+- SERP fetching: 5-10 minutes (with rate limiting)
+- Jaccard calculation: <1 minute (local computation)
+- Gemini calls: 2-5 minutes (only 10-15% of pairs)
+- Total time: 10-20 minutes
+- Total cost: $2-5
+
+**1,000 keywords**:
+- SERP fetching: 15-30 minutes
+- Jaccard calculation: 2-3 minutes
+- Gemini calls: 5-10 minutes
+- Total time: 25-45 minutes
+- Total cost: $5-10
+
+## Troubleshooting
+
+**Issue**: Google blocking requests
+- Solution: Use SERP API or browser automation with proxies
+
+**Issue**: High Gemini costs
+- Solution: Increase ambiguous threshold (30-69% → 40-60%)
+
+**Issue**: Too many singletons
+- Solution: Lower clustering threshold (70% → 60%)
+
+**Issue**: Too few clusters
+- Solution: Raise clustering threshold (70% → 80%)
+
+## References
+
+- Jake Ward's SERP Clustering Method
+- Jaccard Similarity Algorithm
+- Implementation: `scripts/seo/gemini-serp-clustering.js`

package/skills/topical-authority/scripts/orchestrator.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+
+/**
+ * Topical Authority Orchestrator
+ *
+ * Coordinates all 12 topical authority scripts using Gemini CLI for token efficiency.
+ * Delegates script execution to Gemini CLI, tracks progress, validates outputs.
+ *
+ * Usage:
+ *   node .claude/skills/topical-authority/scripts/orchestrator.js --brand ai.withjai --phase all
+ *   node .claude/skills/topical-authority/scripts/orchestrator.js --brand ai.withjai --phase discover
+ *   node .claude/skills/topical-authority/scripts/orchestrator.js --brand ai.withjai --phase cluster
+ *   node .claude/skills/topical-authority/scripts/orchestrator.js --brand ai.withjai --phase analyze
+ *
+ * Phases:
+ *   discover - Forum discovery (scripts 1-5)
+ *   cluster  - SERP clustering (scripts 6-8)
+ *   analyze  - Gap analysis + linking (scripts 9-12)
+ *   all      - Run complete workflow
+ *
+ * Token Optimization:
+ *   All script execution delegated to Gemini CLI = 95%+ token savings
+ */
+
+const { spawnSync } = require('child_process');
+const { fs, path, fromConfig, parseArgs, ensureDir } = require('../../../../scripts/utils/_utils');
+
+const MODEL = process.env.GEMINI_MODEL || 'gemini-2.0-flash-exp';
+
+const PHASES = {
+  discover: {
+    name: 'Forum Discovery & Keyword Extraction',
+    scripts: [
+      { id: 1, file: 'scripts/seo/scrape-reddit-pain-points.js', args: '--brand {brand}' },
+      { id: 2, file: 'scripts/seo/scrape-quora-questions.js', args: '--brand {brand} --topics "{topics}"' },
+      { id: 3, file: 'scripts/seo/extract-paa-questions.js', args: '--brand {brand} --seed-keywords "{seedKeywords}"' },
+      { id: 4, file: 'scripts/seo/analyze-competitor-coverage.js', args: '--brand {brand}' },
+      { id: 5, file: 'scripts/seo/extract-keywords-from-forums.js', args: '--brand {brand} --target {target}' }
+    ],
+    outputs: [
+      'brands/{brand}/content/02-strategy/forum-data/reddit-pain-points.json',
+      'brands/{brand}/content/02-strategy/forum-data/quora-questions.json',
+      'brands/{brand}/content/02-strategy/forum-data/paa-questions.json',
+      'brands/{brand}/content/02-strategy/forum-data/competitor-coverage.json',
+      'brands/{brand}/content/02-strategy/keyword-universe.json'
+    ]
+  },
+  cluster: {
+    name: 'SERP Clustering & Hub Architecture',
+    scripts: [
+      { id: 6, file: 'scripts/seo/fetch-serp-urls.js', args: '--brand {brand} --limit {limit}' },
+      { id: 7, file: 'scripts/seo/gemini-serp-clustering.js', args: '--brand {brand} --threshold {threshold}' },
+      { id: 8, file: 'scripts/seo/build-clusters-from-serp.js', args: '--brand {brand} --min-cluster-size {minClusterSize}' }
+    ],
+    outputs: [
+      'brands/{brand}/content/02-strategy/serp-data/serp-urls.json',
+      'brands/{brand}/content/02-strategy/serp-data/keyword-clusters.json',
+      'brands/{brand}/content/02-strategy/hub-architecture.json'
+    ]
+  },
+  analyze: {
+    name: 'Gap Analysis & Internal Linking',
+    scripts: [
+      { id: 9, file: 'scripts/seo/identify-content-gaps.js', args: '--brand {brand} --min-volume {minVolume}' },
+      { id: 10, file: 'scripts/seo/identify-research-gaps.js', args: '--brand {brand} --min-priority {minPriority}' },
+      { id: 11, file: 'scripts/seo/audit-internal-links.js', args: '--brand {brand} --min-links {minLinks}' },
+      { id: 12, file: 'scripts/seo/weave-internal-links.js', args: '--brand {brand} {autoInsert}' }
+    ],
+    outputs: [
+      'brands/{brand}/content/02-strategy/content-gaps.json',
+      'brands/{brand}/content/02-strategy/research-gaps.json',
+      'brands/{brand}/content/02-strategy/internal-links-graph.json',
+      'brands/{brand}/content/02-strategy/link-suggestions.md'
+    ]
+  }
+};
+
+function main() {
+  const args = parseArgs();
+  const { brand } = fromConfig(args.brand);
+
+  if (!brand) {
+    console.error('❌ Brand not specified. Use --brand {brand}');
+    process.exit(1);
+  }
+
+  const phase = args.phase || 'all';
+  const validPhases = ['discover', 'cluster', 'analyze', 'all'];
+
+  if (!validPhases.includes(phase)) {
+    console.error(`❌ Invalid phase: ${phase}`);
+    console.error(`   Valid phases: ${validPhases.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Collect parameters
+  const params = {
+    brand,
+    topics: args.topics || getDefaultTopics(brand),
+    seedKeywords: args['seed-keywords'] || getDefaultSeedKeywords(brand),
+    target: args.target ? Number(args.target) : 1000,
+    limit: args.limit ? Number(args.limit) : 100,
+    threshold: args.threshold ? Number(args.threshold) : 0.7,
+    minClusterSize: args['min-cluster-size'] ? Number(args['min-cluster-size']) : 3,
+    minVolume: args['min-volume'] ? Number(args['min-volume']) : 100,
+    minPriority: args['min-priority'] ? Number(args['min-priority']) : 2,
+    minLinks: args['min-links'] ? Number(args['min-links']) : 3,
+    autoInsert: args['auto-insert'] ? '--auto-insert' : ''
+  };
+
+  console.log('🎯 Topical Authority Orchestrator');
+  console.log('════════════════════════════════════════════════════════════');
+  console.log(`Brand: ${brand}`);
+  console.log(`Phase: ${phase}`);
+  console.log(`Model: ${MODEL}`);
+  console.log('════════════════════════════════════════════════════════════\n');
+
+  const phasesToRun = phase === 'all'
+    ? ['discover', 'cluster', 'analyze']
+    : [phase];
+
+  const startTime = Date.now();
+  const results = {};
+
+  phasesToRun.forEach((phaseName, idx) => {
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`Phase ${idx + 1}/${phasesToRun.length}: ${PHASES[phaseName].name}`);
+    console.log('='.repeat(60));
+
+    const result = runPhaseWithGemini(phaseName, params);
+    results[phaseName] = result;
+
+    if (!result.success) {
+      console.error(`\n❌ Phase "${phaseName}" failed. Stopping workflow.`);
+      process.exit(1);
+    }
+  });
+
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  console.log('\n' + '='.repeat(60));
+  console.log('✅ Topical Authority Workflow Complete');
+  console.log('='.repeat(60));
+  console.log(`Duration: ${duration}s`);
+  console.log(`\nPhase Results:`);
+
+  Object.entries(results).forEach(([phaseName, result]) => {
+    console.log(`  • ${PHASES[phaseName].name}: ${result.success ? '✅' : '❌'}`);
+    if (result.summary) {
+      console.log(`    ${result.summary}`);
+    }
+  });
+
+  console.log(`\n📊 Outputs saved to: brands/${brand}/content/02-strategy/`);
+  console.log(`\n💡 Next steps:`);
+
+  if (phase === 'all' || phase === 'analyze') {
+    console.log(`   1. Review research gaps: brands/${brand}/content/02-strategy/research-gaps.json`);
+    console.log(`   2. Review content opportunities: brands/${brand}/content/02-strategy/content-gaps.json`);
+    console.log(`   3. Review link suggestions: brands/${brand}/content/02-strategy/link-suggestions.md`);
+    console.log(`   4. Start content creation for GOLDEN opportunities`);
+  } else if (phase === 'discover') {
+    console.log(`   Run SERP clustering: node .claude/skills/topical-authority/scripts/orchestrator.js --brand ${brand} --phase cluster`);
+  } else if (phase === 'cluster') {
+    console.log(`   Run gap analysis: node .claude/skills/topical-authority/scripts/orchestrator.js --brand ${brand} --phase analyze`);
+  }
+}
+
+function runPhaseWithGemini(phaseName, params) {
+  const phase = PHASES[phaseName];
+
+  console.log(`\n🤖 Delegating to Gemini CLI for execution...`);
+  console.log(`   Scripts to run: ${phase.scripts.length}`);
+
+  const prompt = buildGeminiPrompt(phaseName, phase, params);
+
+  const proc = spawnSync('gemini', ['-m', MODEL, '-p', prompt], {
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024, // 10MB
+    timeout: 600000 // 10 minutes
+  });
+
+  if (proc.error || proc.status !== 0) {
+    console.error(`\n❌ Gemini CLI error:`);
+    console.error(proc.stderr || proc.error?.message);
+    return { success: false, error: proc.stderr || proc.error?.message };
+  }
+
+  const output = proc.stdout;
+  console.log(`\n📋 Gemini CLI Output:`);
+  console.log(output);
+
+  // Validate outputs exist
+  const validationResult = validatePhaseOutputs(phaseName, params.brand);
+
+  if (!validationResult.success) {
+    console.error(`\n❌ Output validation failed:`);
+    console.error(`   Missing: ${validationResult.missing.join(', ')}`);
+    return { success: false, error: 'Output validation failed', ...validationResult };
+  }
+
+  console.log(`\n✅ Phase "${phaseName}" completed successfully`);
+  console.log(`   Outputs: ${validationResult.found.length}/${validationResult.expected.length}`);
+
+  return {
+    success: true,
+    outputs: validationResult.found,
+    summary: extractSummary(output)
+  };
+}
+
+function buildGeminiPrompt(phaseName, phase, params) {
+  const lines = [];
+
+  lines.push(`You are a topical authority automation assistant. Execute the following scripts sequentially and report results.`);
+  lines.push(``);
+  lines.push(`**Phase**: ${phase.name}`);
+  lines.push(`**Brand**: ${params.brand}`);
+  lines.push(``);
+  lines.push(`**Scripts to Execute**:`);
+  lines.push(``);
+
+  phase.scripts.forEach((script, idx) => {
+    const cmd = `node ${script.file} ${interpolateArgs(script.args, params)}`;
+    lines.push(`${idx + 1}. Script: ${script.file}`);
+    lines.push(`   Command: ${cmd}`);
+    lines.push(``);
+  });
+
+  lines.push(`**Instructions**:`);
+  lines.push(`1. Execute each script in order using the Node.js runtime`);
+  lines.push(`2. Wait for each script to complete before starting the next`);
+  lines.push(`3. Capture stdout and stderr from each execution`);
+  lines.push(`4. If a script fails, stop and report the error`);
+  lines.push(`5. After all scripts succeed, report:`);
+  lines.push(`   - Total execution time`);
+  lines.push(`   - Summary statistics from each script`);
+  lines.push(`   - Any warnings or errors encountered`);
+  lines.push(`   - List of output files created`);
+  lines.push(``);
+  lines.push(`**Expected Outputs**:`);
+  phase.outputs.forEach(output => {
+    lines.push(`- ${interpolateArgs(output, params)}`);
+  });
+  lines.push(``);
+  lines.push(`**Important**:`);
+  lines.push(`- Use absolute paths from project root`);
+  lines.push(`- Ensure all output directories exist (scripts create them)`);
+  lines.push(`- Report success/failure for each script`);
+  lines.push(`- Include key metrics in summary (e.g., keywords found, clusters created, etc.)`);
+  lines.push(``);
+  lines.push(`Begin execution now. Report progress as you go.`);
+
+  return lines.join('\n');
+}
+
+function interpolateArgs(template, params) {
+  let result = template;
+
+  Object.entries(params).forEach(([key, value]) => {
+    result = result.replace(new RegExp(`\\{${key}\\}`, 'g'), value);
+  });
+
+  return result;
+}
+
+function validatePhaseOutputs(phaseName, brand) {
+  const phase = PHASES[phaseName];
+  const expected = phase.outputs.map(output =>
+    output.replace('{brand}', brand)
+  );
+
+  const found = [];
+  const missing = [];
+
+  expected.forEach(filePath => {
+    const fullPath = path.join(process.cwd(), filePath);
+    if (fs.existsSync(fullPath)) {
+      found.push(filePath);
+    } else {
+      missing.push(filePath);
+    }
+  });
+
+  return {
+    success: missing.length === 0,
+    expected: expected.length,
+    found,
+    missing
+  };
+}
+
+function extractSummary(output) {
+  // Extract key metrics from Gemini output
+  const lines = output.split('\n');
+
+  // Look for summary lines (lines with numbers and metrics)
+  const summaryLines = lines.filter(line =>
+    /✅|keywords|clusters|opportunities|gaps|health score/i.test(line)
+  );
+
+  return summaryLines.slice(0, 5).join(' | ') || 'Completed';
+}
+
+function getDefaultTopics(brand) {
+  // Load from ICP profiles if available
+  const icpFile = path.join(process.cwd(), 'brands', brand, 'content', '00-assets', 'icp-profiles.md');
+
+  if (fs.existsSync(icpFile)) {
+    const content = fs.readFileSync(icpFile, 'utf8');
+
+    // Extract topics from ICP (simple heuristic)
+    const topics = [];
+    if (/automation/i.test(content)) topics.push('automation');
+    if (/marketing/i.test(content)) topics.push('marketing');
+    if (/content/i.test(content)) topics.push('content marketing');
+    if (/ai/i.test(content)) topics.push('ai');
+    if (/productivity/i.test(content)) topics.push('productivity');
+
+    if (topics.length > 0) return topics.join(',');
+  }
+
+  // Fallback defaults by brand
+  const defaults = {
+    'ai.withjai': 'ai automation,content marketing,productivity tools',
+    'enchantents': 'luxury glamping,eco-tourism,boutique hospitality',
+    'xelite-one': 'executive coaching,leadership development,business strategy',
+    'voxcoach.online': 'public speaking,voice coaching,communication skills'
+  };
+
+  return defaults[brand] || 'business,marketing,productivity';
+}
+
+function getDefaultSeedKeywords(brand) {
+  // Load from business profile if available
+  const profileFile = path.join(process.cwd(), 'brands', brand, 'content', '00-assets', 'business-profile.md');
+
+  if (fs.existsSync(profileFile)) {
+    const content = fs.readFileSync(profileFile, 'utf8');
+
+    // Extract primary offering
+    const offeringMatch = content.match(/Primary Offering[:\s]+([^\n]+)/i);
+    if (offeringMatch) return offeringMatch[1].trim();
+  }
+
+  // Fallback defaults
+  const defaults = {
+    'ai.withjai': 'ai content automation,automated newsletter,content workflow',
+    'enchantents': 'luxury glamping,glamping business,eco-luxury tourism',
+    'xelite-one': 'executive coaching,leadership coaching,business coaching',
+    'voxcoach.online': 'voice training,public speaking coaching,communication skills'
+  };
+
+  return defaults[brand] || 'business automation,productivity,marketing';
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error('❌ Orchestrator failed:', err.message);
+    console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+module.exports = { runPhaseWithGemini, validatePhaseOutputs };

package/skills/topical-authority/scripts/seo/analyze-competitor-coverage.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const path = require('path');
+require(path.join(__dirname, '..', 'orchestrator.js'));

package/skills/topical-authority/scripts/seo/audit-internal-links.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const path = require('path');
+require(path.join(__dirname, '..', 'orchestrator.js'));