mcp-scraper 0.2.12 → 0.2.14

package/dist/bin/mcp-scraper-cli.cjs

@@ -3,11 +3,12 @@
 
 // src/cli/human-cli.ts
 var import_commander = require("commander");
+var import_node_child_process2 = require("child_process");
 var import_promises3 = require("fs/promises");
 var import_node_path3 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.12";
+var PACKAGE_VERSION = "0.2.14";
 
 // src/cli/agent-config.ts
 function apiKeyValue(options) {
@@ -234,6 +235,34 @@ var AGENT_PROMPTS = {
     "",
     "Use directory_workflow when the user wants cities selected by population and Google Maps candidates per city. Keep query and location separate. Preserve result_position, source_location, review stars/count, categories, and profile URLs for downstream CSV or directory use."
   ].join("\n"),
+  "map-comparison": [
+    "# MCP Scraper Maps Comparison Prompt",
+    "",
+    "Run the map-comparison workflow when the user wants to compare local Maps competitors in a city or across selected markets. Use `maps-results.csv`, `map-comparison.csv`, and `profile-insights.csv` as source of truth.",
+    "",
+    "Ground recommendations in result_position, review_stars, review_count, category, website presence, review topics, and profile attributes. Treat review gaps and missing websites as opportunity signals, not guaranteed ranking factors."
+  ].join("\n"),
+  "serp-comparison": [
+    "# MCP Scraper SERP Comparison Prompt",
+    "",
+    "Run the serp-comparison workflow when the user wants to know why competitors outrank a page or what the SERP rewards. Use organic results, extracted page headings, PAA questions, and AI Overview citations before making recommendations.",
+    "",
+    "Tie each recommendation to `content-gaps.csv`, `page-comparison.csv`, `paa-questions.csv`, or `ai-overview-citations.csv`. Do not invent missing sections or citations."
+  ].join("\n"),
+  "paa-expansion-brief": [
+    "# MCP Scraper PAA Expansion Brief Prompt",
+    "",
+    "Run the paa-expansion-brief workflow when the user wants to figure out what to write from People Also Ask expansion. Use `section-map.csv` to structure the brief and `paa-questions.csv` for exact customer-language headings.",
+    "",
+    "Answer the highest-priority questions directly, preserve source URLs when present, and separate evidence-backed sections from assumptions."
+  ].join("\n"),
+  "ai-overview-language": [
+    "# MCP Scraper AI Overview Language Prompt",
+    "",
+    "Run the ai-overview-language workflow when the user wants to know how to phrase content for AI Overview inclusion. Use `claim-patterns.csv`, `language-guidance.csv`, `ai-overview-citations.csv`, and PAA follow-ups as evidence.",
+    "",
+    "Recommend concise answer blocks, criteria/step language, citation hooks, and follow-up sections. Do not claim the target will be cited; frame the output as evidence-based language guidance."
+  ].join("\n"),
   "ai-citation-monitor": [
     "# MCP Scraper AI Citation Monitor Prompt",
     "",
@@ -412,22 +441,25 @@ async function openWorkflowReport(id, outputDir) {
 }
 
 // src/workflows/registry.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 
 // src/workflows/http-client.ts
 var WorkflowHttpClient = class {
-  constructor(apiUrl, apiKey, fetchImpl = fetch) {
+  constructor(apiUrl, apiKey, fetchImpl = fetch, extraHeaders = {}) {
     this.apiUrl = apiUrl;
     this.apiKey = apiKey;
     this.fetchImpl = fetchImpl;
+    this.extraHeaders = extraHeaders;
   }
   apiUrl;
   apiKey;
   fetchImpl;
+  extraHeaders;
   async post(path, body, timeoutMs = 18e4) {
     const res = await this.fetchImpl(`${this.apiUrl.replace(/\/$/, "")}${path}`, {
       method: "POST",
       headers: {
+        ...this.extraHeaders,
         "Content-Type": "application/json",
         "x-api-key": this.apiKey
       },
@@ -1020,11 +1052,714 @@ ${summary}
   }
 };
 
+// src/workflows/workflows/comparison-briefs.ts
+var import_zod4 = require("zod");
+
+// src/workflows/workflows/seo-workflow-utils.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "about",
+  "after",
+  "also",
+  "because",
+  "been",
+  "best",
+  "both",
+  "from",
+  "have",
+  "into",
+  "more",
+  "most",
+  "near",
+  "only",
+  "over",
+  "than",
+  "that",
+  "their",
+  "them",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "with",
+  "your",
+  "will",
+  "would",
+  "should",
+  "could",
+  "does",
+  "were",
+  "cost",
+  "costs"
+]);
+function normalizeDomain2(value) {
+  if (!value) return null;
+  try {
+    const url = new URL(value.includes("://") ? value : `https://${value}`);
+    return url.hostname.replace(/^www\./, "").toLowerCase();
+  } catch {
+    return value.replace(/^https?:\/\//, "").replace(/^www\./, "").split("/")[0]?.toLowerCase() || null;
+  }
+}
+function domainFromUrl2(url) {
+  return normalizeDomain2(url) ?? "";
+}
+function numberFrom2(value) {
+  if (value === null || value === void 0 || value === "") return null;
+  const parsed = Number(String(value).replace(/[^\d.]/g, ""));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function median2(values) {
+  const nums = values.filter((v) => v !== null).sort((a, b) => a - b);
+  if (!nums.length) return null;
+  return nums[Math.floor(nums.length / 2)] ?? null;
+}
+function textTerms(text, limit = 12) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/)) {
+    if (token.length < 4 || STOP_WORDS.has(token)) continue;
+    counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([term, count]) => `${term} (${count})`).join("; ");
+}
+function classifyQuestion(question) {
+  const q = question.toLowerCase();
+  if (/\b(cost|price|pricing|charge|expensive|cheap)\b/.test(q)) return "cost";
+  if (/\b(best|top|recommended|reviews?|compare|versus|vs)\b/.test(q)) return "comparison";
+  if (/\b(how|steps?|process|way to)\b/.test(q)) return "process";
+  if (/\b(why|worth|important|benefit)\b/.test(q)) return "why";
+  if (/\b(near me|city|local|nearby)\b/.test(q)) return "local";
+  if (/\b(can|does|do|is|are|should|will)\b/.test(q)) return "decision";
+  return "definition";
+}
+function questionRows(paa) {
+  return (paa?.flat ?? []).filter((row) => row.question).map((row, index) => {
+    const url = row.source_cite ?? "";
+    const domain = normalizeDomain2(row.source_site ?? "") ?? domainFromUrl2(url);
+    return {
+      position: index + 1,
+      intent: classifyQuestion(row.question ?? ""),
+      question: row.question ?? "",
+      answer_excerpt: (row.answer ?? "").slice(0, 320),
+      source_title: row.source_title ?? "",
+      source_domain: domain,
+      source_url: url
+    };
+  });
+}
+function sourceDomainRows(rows) {
+  const byDomain = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const domain = String(row.source_domain ?? row.domain ?? "");
+    if (!domain) continue;
+    const entry = byDomain.get(domain) ?? { questions: 0, urls: /* @__PURE__ */ new Set(), intents: /* @__PURE__ */ new Map() };
+    entry.questions += row.question ? 1 : 0;
+    if (row.source_url || row.url) entry.urls.add(String(row.source_url ?? row.url));
+    if (row.intent) entry.intents.set(String(row.intent), (entry.intents.get(String(row.intent)) ?? 0) + 1);
+    byDomain.set(domain, entry);
+  }
+  return [...byDomain.entries()].map(([domain, entry]) => ({
+    domain,
+    question_mentions: entry.questions,
+    source_url_count: entry.urls.size,
+    top_intents: [...entry.intents.entries()].sort((a, b) => b[1] - a[1]).map(([intent, count]) => `${intent} (${count})`).join("; ")
+  })).sort((a, b) => Number(b.question_mentions) - Number(a.question_mentions) || String(a.domain).localeCompare(String(b.domain)));
+}
+function splitSentences(text) {
+  return (text ?? "").replace(/\s+/g, " ").split(/(?<=[.!?])\s+/).map((sentence) => sentence.trim()).filter((sentence) => sentence.length > 20).slice(0, 20);
+}
+function classifySentence(sentence) {
+  const s = sentence.toLowerCase();
+  if (/\bis\b|\bare\b|\bmeans\b|\brefers to\b/.test(s)) return "definition";
+  if (/\binclude\b|\bconsider\b|\bfactors?\b|\bcriteria\b/.test(s)) return "criteria";
+  if (/\bfirst\b|\bthen\b|\bsteps?\b|\bprocess\b/.test(s)) return "process";
+  if (/\bvs\b|\bthan\b|\bcompare\b|\bdifference\b/.test(s)) return "comparison";
+  if (/\bcost\b|\bprice\b|\baverage\b|\brange\b/.test(s)) return "cost";
+  return "claim";
+}
+function pageSummaryRow(page, source) {
+  return {
+    position: source.position ?? "",
+    domain: source.domain,
+    url: source.url,
+    serp_title: source.title ?? "",
+    page_title: page.title ?? "",
+    h1: page.h1 ?? "",
+    meta_description: page.metaDescription ?? "",
+    word_count: page.wordCount ?? "",
+    heading_count: page.headings?.length ?? 0,
+    schema_types: (page.schemaTypes ?? []).join("; ")
+  };
+}
+async function mapLimit2(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      out[index] = await fn(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, () => worker()));
+  return out;
+}
+
+// src/workflows/workflows/comparison-briefs.ts
+var ProxyModeSchema = import_zod4.z.enum(["location", "configured", "none"]);
+var MapComparisonInputSchema = import_zod4.z.object({
+  query: import_zod4.z.string().min(1),
+  location: import_zod4.z.string().optional(),
+  state: import_zod4.z.string().optional(),
+  minPopulation: import_zod4.z.number().int().min(0).default(1e5),
+  maxCities: import_zod4.z.number().int().min(1).max(100).default(5),
+  maxResultsPerCity: import_zod4.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod4.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod4.z.number().int().min(0).max(500).default(25),
+  concurrency: import_zod4.z.number().int().min(1).max(5).default(5),
+  proxyMode: ProxyModeSchema.default("location"),
+  returnPartial: import_zod4.z.boolean().default(true)
+}).refine((input) => input.location || input.state, {
+  message: "Either location or state is required for map-comparison"
+});
+var SerpComparisonInputSchema = import_zod4.z.object({
+  keyword: import_zod4.z.string().min(1),
+  domain: import_zod4.z.string().optional(),
+  url: import_zod4.z.string().url().optional(),
+  location: import_zod4.z.string().optional(),
+  maxResults: import_zod4.z.number().int().min(1).max(20).default(10),
+  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod4.z.number().int().min(0).max(10).default(5),
+  includePaa: import_zod4.z.boolean().default(true),
+  includeAiOverview: import_zod4.z.boolean().default(true),
+  returnPartial: import_zod4.z.boolean().default(true)
+});
+var PaaExpansionBriefInputSchema = import_zod4.z.object({
+  keyword: import_zod4.z.string().min(1),
+  location: import_zod4.z.string().optional(),
+  maxQuestions: import_zod4.z.number().int().min(1).max(300).default(80),
+  depth: import_zod4.z.number().int().min(1).max(6).default(3),
+  returnPartial: import_zod4.z.boolean().default(true)
+});
+var AiOverviewLanguageInputSchema = import_zod4.z.object({
+  keyword: import_zod4.z.string().min(1),
+  domain: import_zod4.z.string().optional(),
+  url: import_zod4.z.string().url().optional(),
+  location: import_zod4.z.string().optional(),
+  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod4.z.number().int().min(0).max(8).default(3),
+  returnPartial: import_zod4.z.boolean().default(true)
+});
+function businessRowsFromMaps(location, query, results) {
+  return results.map((result) => ({
+    source_query: query,
+    source_location: location,
+    city: location.split(",")[0]?.trim() ?? location,
+    state: location.split(",")[1]?.trim() ?? "",
+    population: "",
+    result_position: result.position,
+    business_name: result.name,
+    review_stars: result.rating ?? "",
+    review_count: result.reviewCount ?? "",
+    category: result.category ?? "",
+    address: result.address ?? "",
+    phone: result.phone ?? "",
+    website_url: result.websiteUrl ?? "",
+    place_url: result.placeUrl ?? "",
+    cid: result.cid ?? "",
+    cid_decimal: result.cidDecimal ?? "",
+    result_status: "ok",
+    error: ""
+  }));
+}
+function marketRows(rows) {
+  const byLocation = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = String(row.source_location ?? row.location ?? "");
+    if (!key) continue;
+    const list = byLocation.get(key) ?? [];
+    list.push(row);
+    byLocation.set(key, list);
+  }
+  return [...byLocation.entries()].map(([location, list]) => {
+    const counts = list.map((row) => numberFrom2(row.review_count));
+    const ratings = list.map((row) => numberFrom2(row.review_stars));
+    const topThree = list.slice(0, 3).map((row) => numberFrom2(row.review_count)).filter((v) => v !== null);
+    const categories = /* @__PURE__ */ new Map();
+    for (const row of list) {
+      const category = String(row.category ?? "");
+      if (category) categories.set(category, (categories.get(category) ?? 0) + 1);
+    }
+    return {
+      source_location: location,
+      result_count: list.filter((row) => row.business_name).length,
+      median_review_count: median2(counts) ?? "",
+      median_rating: median2(ratings) ?? "",
+      top_three_average_review_count: topThree.length ? Math.round(topThree.reduce((a, b) => a + b, 0) / topThree.length) : "",
+      top_categories: [...categories.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([cat, count]) => `${cat} (${count})`).join("; "),
+      websites_present: list.filter((row) => row.website_url).length
+    };
+  });
+}
+function comparisonRows(rows) {
+  const benchmarkByLocation = /* @__PURE__ */ new Map();
+  for (const market of marketRows(rows)) {
+    benchmarkByLocation.set(String(market.source_location), numberFrom2(market.top_three_average_review_count) ?? 0);
+  }
+  return rows.filter((row) => row.business_name).map((row) => {
+    const reviews = numberFrom2(row.review_count) ?? 0;
+    const benchmark = benchmarkByLocation.get(String(row.source_location)) ?? 0;
+    const websiteMissing = !row.website_url;
+    const rank = numberFrom2(row.result_position) ?? 999;
+    return {
+      source_location: row.source_location,
+      result_position: row.result_position,
+      business_name: row.business_name,
+      category: row.category,
+      review_stars: row.review_stars,
+      review_count: row.review_count,
+      review_gap_to_top3_average: benchmark ? Math.max(0, benchmark - reviews) : "",
+      website_url: row.website_url,
+      place_url: row.place_url,
+      comparison_note: rank <= 3 ? "visible leader" : websiteMissing ? "ranking without website" : reviews < benchmark ? "review-light competitor" : "visible competitor"
+    };
+  });
+}
+function organicRows(serp, targetDomain) {
+  return (serp?.organicResults ?? []).map((result) => {
+    const url = result.url ?? "";
+    const domain = normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(url);
+    return {
+      position: result.position ?? "",
+      title: result.title ?? "",
+      url,
+      domain,
+      snippet: result.snippet ?? "",
+      is_target: targetDomain ? domain === targetDomain : false
+    };
+  });
+}
+function pageGapRows(targetPage, competitorPages) {
+  const targetHeadingText = new Set((targetPage?.headings ?? []).map((h) => h.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim()));
+  const targetTerms = new Set((targetPage?.headings ?? []).flatMap((h) => h.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(Boolean)));
+  const rows = [];
+  for (const { source, page } of competitorPages) {
+    for (const heading of page.headings ?? []) {
+      if (heading.level > 3 || !heading.text) continue;
+      const normalized = heading.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim();
+      const terms = normalized.split(/\s+/).filter((term) => term.length > 3);
+      const overlap = terms.filter((term) => targetTerms.has(term)).length;
+      const covered = targetHeadingText.has(normalized) || overlap >= Math.max(2, Math.ceil(terms.length / 2));
+      if (covered && targetPage) continue;
+      rows.push({
+        source_position: source.position ?? "",
+        source_domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url),
+        source_url: source.url ?? "",
+        heading_level: heading.level,
+        competitor_heading: heading.text,
+        target_coverage: targetPage ? "not found in target headings" : "no target page extracted",
+        terms: textTerms(heading.text, 6)
+      });
+    }
+  }
+  return rows.slice(0, 150);
+}
+async function extractPages(ctx, sources, warnings, labelPrefix) {
+  return mapLimit2(sources.filter((source) => source.url), 2, async (source, index) => {
+    try {
+      const page = await ctx.client.post("/extract-url", { url: source.url }, 18e4);
+      await ctx.artifacts.writeJson(`${labelPrefix} ${index + 1}`, `raw/extract-url/${labelPrefix.toLowerCase()}-${index + 1}.json`, page);
+      return { source, page };
+    } catch (err) {
+      warnings.push(`Page extraction failed for ${source.url}: ${err instanceof Error ? err.message : String(err)}`);
+      return null;
+    }
+  }).then((items) => items.filter((item) => item !== null));
+}
+var mapComparisonWorkflowDefinition = {
+  id: "map-comparison",
+  title: "Maps Comparison",
+  description: "Compare Google Maps competitors by rank, reviews, stars, categories, websites, and profile/review signals.",
+  inputSchema: MapComparisonInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    let rows;
+    let directory = null;
+    let mapsSearch = null;
+    if (input.location) {
+      mapsSearch = await ctx.client.post("/maps/search", {
+        query: input.query,
+        location: input.location,
+        maxResults: input.maxResultsPerCity,
+        proxyMode: input.proxyMode
+      }, 24e4);
+      rows = businessRowsFromMaps(input.location, input.query, mapsSearch.results);
+      await ctx.artifacts.writeJson("Maps search raw JSON", "raw/maps-search.json", mapsSearch);
+    } else {
+      directory = await ctx.client.post("/directory/run", {
+        query: input.query,
+        state: input.state,
+        minPopulation: input.minPopulation,
+        maxCities: input.maxCities,
+        maxResultsPerCity: input.maxResultsPerCity,
+        concurrency: input.concurrency,
+        proxyMode: input.proxyMode,
+        saveCsv: true
+      }, 9e5);
+      rows = directoryRows(directory);
+      await ctx.artifacts.writeJson("Directory raw JSON", "raw/directory-workflow.json", directory);
+      await ctx.artifacts.writeCsv("Directory CSV", "exports/directory.csv", DIRECTORY_CSV_HEADERS, rows);
+      warnings.push(...directory.warnings);
+    }
+    const compareRows = comparisonRows(rows);
+    const selected = compareRows.slice(0, input.hydrateTop * Math.max(1, input.location ? 1 : input.maxCities));
+    const hydrated = await mapLimit2(selected, 3, async (row, index) => {
+      try {
+        const detail = await ctx.client.post("/maps/place", {
+          businessName: row.business_name,
+          location: row.source_location,
+          includeReviews: input.maxReviews > 0,
+          maxReviews: Math.max(1, input.maxReviews)
+        }, 18e4);
+        await ctx.artifacts.writeJson(`${row.business_name} profile`, `raw/maps-place-intel/${index + 1}-${String(row.business_name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.json`, detail);
+        return { row, detail, error: "" };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(`Profile hydration failed for ${row.business_name}: ${message}`);
+        return { row, detail: null, error: message };
+      }
+    });
+    const profileRows = hydrated.map(({ row, detail, error }) => ({
+      source_location: row.source_location,
+      result_position: row.result_position,
+      business_name: row.business_name,
+      category: detail?.category ?? row.category,
+      review_stars: detail?.rating ?? row.review_stars,
+      review_count: detail?.reviewCount ?? row.review_count,
+      website_url: detail?.website ?? row.website_url,
+      review_topics: (detail?.reviewTopics ?? []).map((t) => `${t.label} (${t.count})`).join("; "),
+      about_attributes: (detail?.aboutAttributes ?? []).map((a) => `${a.section}: ${a.attribute}`).join("; "),
+      reviews_status: detail?.reviewsStatus ?? "",
+      error
+    }));
+    const markets = marketRows(rows);
+    await ctx.artifacts.writeCsv("Maps results CSV", "maps-results.csv", ["source_query", "source_location", "city", "state", "population", "result_position", "business_name", "review_stars", "review_count", "category", "address", "phone", "website_url", "place_url", "cid", "cid_decimal", "result_status", "error"], rows);
+    await ctx.artifacts.writeCsv("Comparison CSV", "map-comparison.csv", ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "review_gap_to_top3_average", "website_url", "place_url", "comparison_note"], compareRows);
+    await ctx.artifacts.writeCsv("Profile insights CSV", "profile-insights.csv", ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "website_url", "review_topics", "about_attributes", "reviews_status", "error"], profileRows);
+    await ctx.artifacts.writeJson("Maps comparison evidence", "evidence.json", { input, directory, mapsSearch, rows, compareRows, profileRows, markets, warnings });
+    await ctx.artifacts.writeText("Brief", "brief.md", [
+      `# Maps Comparison: ${input.query}`,
+      "",
+      `Markets: ${markets.map((row) => row.source_location).join(", ")}`,
+      "",
+      "## How to Use",
+      "- Compare rank position against review count and category patterns.",
+      "- Treat review gaps and missing websites as opportunity signals, not guarantees.",
+      "- Use profile topics and attributes as evidence for local content and GBP improvements."
+    ].join("\n"));
+    const summary = `${compareRows.length} Maps competitors compared across ${markets.length} market(s); ${profileRows.filter((row) => !row.error).length} profiles hydrated.`;
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "Maps Comparison",
+      subtitle: `${input.query}${input.location ? ` \xB7 ${input.location}` : input.state ? ` \xB7 ${input.state}` : ""}`,
+      summary,
+      warnings,
+      tables: [
+        { title: "Market Benchmarks", columns: ["source_location", "result_count", "median_review_count", "median_rating", "top_three_average_review_count", "top_categories", "websites_present"], rows: markets },
+        { title: "Competitor Comparison", columns: ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "review_gap_to_top3_average", "comparison_note"], rows: compareRows.slice(0, 120) },
+        { title: "Profile Insights", columns: ["source_location", "business_name", "review_topics", "about_attributes", "error"], rows: profileRows }
+      ]
+    }));
+    const status2 = warnings.length ? "partial" : "succeeded";
+    const counts = { markets: markets.length, competitors: compareRows.length, hydratedProfiles: profileRows.filter((row) => !row.error).length };
+    await ctx.artifacts.writeManifest(status2, counts, warnings, []);
+    return { title: "Maps Comparison", summary, status: status2, counts, warnings, errors: [], reportPath };
+  }
+};
+var serpComparisonWorkflowDefinition = {
+  id: "serp-comparison",
+  title: "SERP Comparison",
+  description: "Compare ranking pages, SERP features, PAA evidence, AI Overview citations, and page-level content gaps.",
+  inputSchema: SerpComparisonInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    const targetDomain = normalizeDomain2(input.domain ?? input.url ?? null);
+    const serp = await ctx.client.post("/harvest/sync", {
+      query: input.keyword,
+      location: input.location,
+      serpOnly: true,
+      maxQuestions: 1,
+      format: "json"
+    }, 18e4);
+    await ctx.artifacts.writeJson("SERP raw JSON", "raw/serp.json", serp);
+    let paa = null;
+    if (input.includePaa) {
+      try {
+        paa = await ctx.client.post("/harvest/sync", {
+          query: input.keyword,
+          location: input.location,
+          maxQuestions: input.maxQuestions,
+          format: "json"
+        }, 28e4);
+        await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+      } catch (err) {
+        warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    const organic = organicRows(serp, targetDomain).slice(0, input.maxResults);
+    const organicSources = (serp.organicResults ?? []).slice(0, input.maxResults);
+    const targetSource = input.url ? { position: 0, title: "Target page", url: input.url, domain: domainFromUrl2(input.url) } : organicSources.find((result) => targetDomain && (normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(result.url)) === targetDomain);
+    const competitorSources = organicSources.filter((result) => result.url && result.url !== targetSource?.url).filter((result) => !targetDomain || (normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(result.url)) !== targetDomain).slice(0, input.extractTop);
+    const targetPages = targetSource ? await extractPages(ctx, [targetSource], warnings, "Target") : [];
+    const competitorPages = input.extractTop > 0 ? await extractPages(ctx, competitorSources, warnings, "Competitor") : [];
+    const targetPage = targetPages[0]?.page ?? null;
+    const pageRows = [
+      ...targetPages.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title })),
+      ...competitorPages.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title }))
+    ];
+    const gaps = pageGapRows(targetPage, competitorPages);
+    const questions = questionRows(paa);
+    const aiRows = (serp.aiOverview?.citations ?? []).map((citation, index) => ({
+      citation_position: index + 1,
+      citation_text: citation.text ?? "",
+      url: citation.href ?? "",
+      domain: domainFromUrl2(citation.href ?? ""),
+      is_target: targetDomain ? domainFromUrl2(citation.href ?? "") === targetDomain : false
+    }));
+    await ctx.artifacts.writeCsv("Organic results CSV", "organic-results.csv", ["position", "title", "url", "domain", "snippet", "is_target"], organic);
+    await ctx.artifacts.writeCsv("Page comparison CSV", "page-comparison.csv", ["position", "domain", "url", "serp_title", "page_title", "h1", "meta_description", "word_count", "heading_count", "schema_types"], pageRows);
+    await ctx.artifacts.writeCsv("Content gaps CSV", "content-gaps.csv", ["source_position", "source_domain", "source_url", "heading_level", "competitor_heading", "target_coverage", "terms"], gaps);
+    await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+    await ctx.artifacts.writeCsv("AI Overview citations CSV", "ai-overview-citations.csv", ["citation_position", "citation_text", "url", "domain", "is_target"], aiRows);
+    await ctx.artifacts.writeJson("SERP comparison evidence", "evidence.json", { input, serp, paa, organic, pageRows, gaps, questions, aiRows, warnings });
+    await ctx.artifacts.writeText("Writer brief", "brief.md", [
+      `# SERP Comparison Brief: ${input.keyword}`,
+      "",
+      `Target: ${targetDomain ?? input.url ?? "not specified"}`,
+      `Location: ${input.location ?? "not specified"}`,
+      "",
+      "## Recommended Actions",
+      "- Use `content-gaps.csv` to decide which missing sections deserve coverage.",
+      "- Use `paa-questions.csv` for FAQ and answer-block candidates.",
+      "- Use `ai-overview-citations.csv` to see whether the target is cited in AI Overview evidence.",
+      "- Treat extracted page headings as evidence, not a complete semantic analysis."
+    ].join("\n"));
+    const summary = `${organic.length} organic results, ${pageRows.length} extracted pages, ${gaps.length} heading gaps, ${questions.length} PAA questions.`;
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "SERP Comparison",
+      subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+      summary,
+      warnings,
+      tables: [
+        { title: "Organic Results", columns: ["position", "title", "domain", "is_target"], rows: organic },
+        { title: "Page Comparison", columns: ["position", "domain", "h1", "word_count", "heading_count", "schema_types"], rows: pageRows },
+        { title: "Content Gaps", columns: ["source_position", "source_domain", "competitor_heading", "target_coverage", "terms"], rows: gaps.slice(0, 80) },
+        { title: "PAA Questions", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 80) }
+      ]
+    }));
+    const status2 = warnings.length ? "partial" : "succeeded";
+    const counts = { organic: organic.length, pages: pageRows.length, gaps: gaps.length, questions: questions.length, aiCitations: aiRows.length };
+    await ctx.artifacts.writeManifest(status2, counts, warnings, []);
+    return { title: "SERP Comparison", summary, status: status2, counts, warnings, errors: [], reportPath };
+  }
+};
+var paaExpansionBriefWorkflowDefinition = {
+  id: "paa-expansion-brief",
+  title: "PAA Expansion Brief",
+  description: "Expand People Also Ask questions into an evidence-backed writer brief, section map, and source table.",
+  inputSchema: PaaExpansionBriefInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    const paa = await ctx.client.post("/harvest/sync", {
+      query: input.keyword,
+      location: input.location,
+      maxQuestions: input.maxQuestions,
+      depth: input.depth,
+      format: "json"
+    }, 3e5);
+    await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+    const questions = questionRows(paa);
+    const sourceRows2 = sourceDomainRows(questions);
+    const byIntent = /* @__PURE__ */ new Map();
+    for (const row of questions) {
+      const list = byIntent.get(String(row.intent)) ?? [];
+      list.push(row);
+      byIntent.set(String(row.intent), list);
+    }
+    const sectionRows = [...byIntent.entries()].map(([intent, rows]) => ({
+      recommended_section: intent,
+      question_count: rows.length,
+      sample_questions: rows.slice(0, 5).map((row) => row.question).join(" | "),
+      source_domains: [...new Set(rows.map((row) => row.source_domain).filter(Boolean))].slice(0, 5).join("; "),
+      terms: textTerms(rows.map((row) => `${row.question} ${row.answer_excerpt}`).join(" "), 10)
+    })).sort((a, b) => Number(b.question_count) - Number(a.question_count));
+    await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+    await ctx.artifacts.writeCsv("Source domains CSV", "source-domains.csv", ["domain", "question_mentions", "source_url_count", "top_intents"], sourceRows2);
+    await ctx.artifacts.writeCsv("Section map CSV", "section-map.csv", ["recommended_section", "question_count", "sample_questions", "source_domains", "terms"], sectionRows);
+    await ctx.artifacts.writeJson("PAA brief evidence", "evidence.json", { input, paa, questions, sourceRows: sourceRows2, sectionRows });
+    await ctx.artifacts.writeText("Writer brief", "writer-brief.md", [
+      `# PAA Expansion Brief: ${input.keyword}`,
+      "",
+      `Location: ${input.location ?? "not specified"}`,
+      "",
+      "## Suggested Page Structure",
+      ...sectionRows.map((row) => `- ${row.recommended_section}: answer ${row.question_count} related question(s). Sample: ${row.sample_questions}`),
+      "",
+      "## Writing Rules",
+      "- Answer the highest-frequency question in the first 60 words of each section.",
+      "- Use exact customer question language from `paa-questions.csv` for H2/H3 candidates.",
+      "- Use `source-domains.csv` to identify which source types Google is already rewarding.",
+      "- Do not invent citations; cite only rows that have a source URL."
+    ].join("\n"));
+    const summary = `${questions.length} PAA questions grouped into ${sectionRows.length} writing sections.`;
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "PAA Expansion Brief",
+      subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+      summary,
+      warnings,
+      tables: [
+        { title: "Section Map", columns: ["recommended_section", "question_count", "sample_questions", "source_domains", "terms"], rows: sectionRows },
+        { title: "Questions", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 120) },
+        { title: "Source Domains", columns: ["domain", "question_mentions", "source_url_count", "top_intents"], rows: sourceRows2 }
+      ]
+    }));
+    const counts = { questions: questions.length, sections: sectionRows.length, sourceDomains: sourceRows2.length };
+    await ctx.artifacts.writeManifest("succeeded", counts, warnings, []);
+    return { title: "PAA Expansion Brief", summary, status: "succeeded", counts, warnings, errors: [], reportPath };
+  }
+};
+var aiOverviewLanguageWorkflowDefinition = {
+  id: "ai-overview-language",
+  title: "AI Overview Language Brief",
+  description: "Turn AI Overview, citation, PAA, and ranking-page evidence into answer-block and citation-hook guidance.",
+  inputSchema: AiOverviewLanguageInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    const targetDomain = normalizeDomain2(input.domain ?? input.url ?? null);
+    const serp = await ctx.client.post("/harvest/sync", {
+      query: input.keyword,
+      location: input.location,
+      serpOnly: true,
+      maxQuestions: 1,
+      format: "json"
+    }, 18e4);
+    await ctx.artifacts.writeJson("SERP raw JSON", "raw/serp.json", serp);
+    let paa = null;
+    try {
+      paa = await ctx.client.post("/harvest/sync", {
+        query: input.keyword,
+        location: input.location,
+        maxQuestions: input.maxQuestions,
+        format: "json"
+      }, 28e4);
+      await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+    } catch (err) {
+      warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const citations = (serp.aiOverview?.citations ?? []).map((citation, index) => {
+      const domain = domainFromUrl2(citation.href ?? "");
+      return {
+        citation_position: index + 1,
+        citation_text: citation.text ?? "",
+        url: citation.href ?? "",
+        domain,
+        is_target: targetDomain ? domain === targetDomain : false
+      };
+    });
+    const aioSentences = splitSentences(serp.aiOverview?.text);
+    const claimRows = aioSentences.map((sentence, index) => ({
+      position: index + 1,
+      claim_type: classifySentence(sentence),
+      sentence,
+      reusable_pattern: sentence.length > 140 ? `${sentence.slice(0, 140)}...` : sentence
+    }));
+    const questions = questionRows(paa);
+    const citationSources = (serp.aiOverview?.citations ?? []).filter((citation) => citation.href).map((citation, index) => ({ position: index + 1, title: citation.text, url: citation.href, domain: domainFromUrl2(citation.href) })).slice(0, input.extractTop);
+    const extractedCitations = input.extractTop > 0 ? await extractPages(ctx, citationSources, warnings, "Citation") : [];
+    const extractedRows = extractedCitations.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title }));
+    const languageRows = [
+      {
+        block: "direct_answer",
+        guidance: "Open with a 40-70 word answer that directly resolves the query before adding context.",
+        evidence_basis: questions[0]?.question ?? input.keyword
+      },
+      {
+        block: "criteria_or_steps",
+        guidance: "List the criteria, steps, or decision factors Google is already compressing into AI Overview language.",
+        evidence_basis: claimRows.filter((row) => ["criteria", "process"].includes(String(row.claim_type))).map((row) => row.sentence).slice(0, 3).join(" | ")
+      },
+      {
+        block: "citation_hook",
+        guidance: "Add source-worthy details competitors can cite: definitions, numbers, examples, process details, and named entity relationships.",
+        evidence_basis: citations.map((row) => `${row.domain}: ${row.citation_text}`).slice(0, 5).join(" | ")
+      },
+      {
+        block: "faq_followups",
+        guidance: "Use PAA phrasing for follow-up sections so the page answers adjacent questions in Google language.",
+        evidence_basis: questions.slice(0, 5).map((row) => row.question).join(" | ")
+      }
+    ];
+    await ctx.artifacts.writeCsv("AI Overview citations CSV", "ai-overview-citations.csv", ["citation_position", "citation_text", "url", "domain", "is_target"], citations);
+    await ctx.artifacts.writeCsv("AI Overview claim patterns CSV", "claim-patterns.csv", ["position", "claim_type", "sentence", "reusable_pattern"], claimRows);
+    await ctx.artifacts.writeCsv("Language guidance CSV", "language-guidance.csv", ["block", "guidance", "evidence_basis"], languageRows);
+    await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+    await ctx.artifacts.writeCsv("Extracted citation pages CSV", "citation-pages.csv", ["position", "domain", "url", "serp_title", "page_title", "h1", "meta_description", "word_count", "heading_count", "schema_types"], extractedRows);
+    await ctx.artifacts.writeJson("AI Overview language evidence", "evidence.json", { input, serp, paa, citations, claimRows, languageRows, extractedRows, warnings });
+    await ctx.artifacts.writeText("Answer block template", "answer-block-template.md", [
+      `# AI Overview Language Brief: ${input.keyword}`,
+      "",
+      `AI Overview detected: ${serp.aiOverview?.detected ? "yes" : "no"}`,
+      `Target cited: ${targetDomain ? citations.some((row) => row.is_target) ? "yes" : "no" : "target not specified"}`,
+      "",
+      "## Direct Answer Block",
+      "Write one compact answer block that starts with the answer, not background. Keep it clear enough that Google could lift it as a standalone summary.",
+      "",
+      "## Suggested Follow-Up Blocks",
+      ...languageRows.map((row) => `- ${row.block}: ${row.guidance}`),
+      "",
+      "## Evidence to Mirror",
+      ...claimRows.slice(0, 8).map((row) => `- ${row.claim_type}: ${row.sentence}`),
+      "",
+      "## Citation Hooks",
+      ...citations.slice(0, 8).map((row) => `- ${row.domain}: ${row.citation_text}`)
+    ].join("\n"));
+    const summary = `${citations.length} AI Overview citations, ${claimRows.length} claim patterns, ${questions.length} PAA questions, ${extractedRows.length} citation pages extracted.`;
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "AI Overview Language Brief",
+      subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+      summary,
+      warnings,
+      tables: [
+        { title: "Language Guidance", columns: ["block", "guidance", "evidence_basis"], rows: languageRows },
+        { title: "AI Overview Citations", columns: ["citation_position", "citation_text", "domain", "is_target"], rows: citations },
+        { title: "Claim Patterns", columns: ["position", "claim_type", "sentence"], rows: claimRows },
+        { title: "PAA Follow-Ups", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 60) }
+      ]
+    }));
+    const status2 = warnings.length || !serp.aiOverview?.detected ? "partial" : "succeeded";
+    const counts = { citations: citations.length, claimPatterns: claimRows.length, questions: questions.length, extractedCitationPages: extractedRows.length };
+    await ctx.artifacts.writeManifest(status2, counts, warnings, []);
+    return { title: "AI Overview Language Brief", summary, status: status2, counts, warnings, errors: [], reportPath };
+  }
+};
+
 // src/workflows/registry.ts
 var DEFINITIONS = [
   directoryWorkflowDefinition,
   agentPacketWorkflowDefinition,
-  localCompetitiveAuditWorkflowDefinition
+  localCompetitiveAuditWorkflowDefinition,
+  mapComparisonWorkflowDefinition,
+  serpComparisonWorkflowDefinition,
+  paaExpansionBriefWorkflowDefinition,
+  aiOverviewLanguageWorkflowDefinition
 ];
 function listWorkflowDefinitions() {
   return DEFINITIONS.map(({ id, title, description }) => ({ id, title, description }));
@@ -1041,7 +1776,7 @@ async function runWorkflow(id, rawInput, options = {}) {
   if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required for workflow runs. Pass --api-key or set the environment variable.");
   const apiUrl = options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
   const artifacts = await ArtifactWriter.create(definition.id, definition.title, input, options.outputDir, options.runId);
-  const client = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl);
+  const client = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
   try {
     return await definition.run(input, {
       runId: artifacts.runId,
@@ -1078,29 +1813,42 @@ function compactInput(input) {
   return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
 }
 function workflowInput(id, opts) {
-  if (id === "agent-packet") {
+  if (id === "agent-packet" || id === "serp-comparison" || id === "ai-overview-language") {
     return compactInput({
       keyword: opts.keyword,
       domain: opts.domain,
+      url: opts.url,
       location: opts.location,
+      maxResults: numberOpt(opts.maxResults),
       maxQuestions: numberOpt(opts.maxQuestions),
+      extractTop: numberOpt(opts.extractTop),
       includeSerp: opts.serp === false ? false : void 0,
       includePaa: opts.paa === false ? false : void 0,
       includeAiOverview: booleanOpt(opts.includeAiOverview),
       returnPartial: opts.returnPartial === false ? false : void 0
     });
   }
-  if (id === "directory" || id === "local-competitive-audit") {
+  if (id === "paa-expansion-brief") {
+    return compactInput({
+      keyword: opts.keyword,
+      location: opts.location,
+      maxQuestions: numberOpt(opts.maxQuestions),
+      depth: numberOpt(opts.depth),
+      returnPartial: opts.returnPartial === false ? false : void 0
+    });
+  }
+  if (id === "directory" || id === "local-competitive-audit" || id === "map-comparison") {
     return compactInput({
       query: opts.query,
+      location: opts.location,
       state: opts.state,
       minPopulation: numberOpt(opts.minPop ?? opts.minPopulation),
       maxCities: numberOpt(opts.maxCities),
-      maxResultsPerCity: numberOpt(opts.perCity ?? opts.maxResultsPerCity),
+      maxResultsPerCity: numberOpt(opts.perCity ?? opts.maxResultsPerCity ?? opts.maxResults),
       concurrency: numberOpt(opts.concurrency),
       proxyMode: opts.proxyMode,
-      hydrateTop: id === "local-competitive-audit" ? numberOpt(opts.hydrateTop) : void 0,
-      maxReviews: id === "local-competitive-audit" ? numberOpt(opts.reviews ?? opts.maxReviews) : void 0,
+      hydrateTop: id === "local-competitive-audit" || id === "map-comparison" ? numberOpt(opts.hydrateTop) : void 0,
+      maxReviews: id === "local-competitive-audit" || id === "map-comparison" ? numberOpt(opts.reviews ?? opts.maxReviews) : void 0,
       returnPartial: opts.returnPartial === false ? false : void 0
     });
   }
@@ -1131,6 +1879,17 @@ function apiOptions(opts) {
     apiKey
   };
 }
+function openExternalUrl(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = (0, import_node_child_process2.spawn)(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function apiRequest(path, method, opts, body) {
   const { apiUrl, apiKey } = apiOptions(opts);
   const res = await fetch(`${apiUrl}${path}`, {
@@ -1149,7 +1908,7 @@ async function apiRequest(path, method, opts, body) {
   return data;
 }
 function addWorkflowInputOptions(command) {
-  return command.option("--keyword <keyword>", "Agent packet keyword").option("--domain <domain>", "Target domain").option("--location <location>", "Target location").option("--max-questions <n>", "Maximum PAA questions").option("--no-serp", "Skip SERP evidence for agent packet").option("--no-paa", "Skip PAA evidence for agent packet").option("--query <query>", "Business category or workflow query").option("--state <state>", "US state").option("--min-pop <n>", "Minimum city population").option("--max-cities <n>", "Maximum selected cities").option("--per-city <n>", "Maps results per city").option("--concurrency <n>", "City search concurrency").option("--proxy-mode <mode>", "Proxy mode: location, configured, or none").option("--hydrate-top <n>", "Profiles to hydrate per city for competitive audits").option("--reviews <n>", "Review cards to collect per hydrated profile").option("--no-return-partial", "Fail instead of writing partial artifacts");
+  return command.option("--keyword <keyword>", "Agent packet keyword").option("--domain <domain>", "Target domain").option("--url <url>", "Target page URL").option("--location <location>", "Target location").option("--max-results <n>", "Maximum SERP or Maps results").option("--max-questions <n>", "Maximum PAA questions").option("--extract-top <n>", "Top result pages or citation pages to extract").option("--depth <n>", "PAA expansion depth").option("--no-serp", "Skip SERP evidence for agent packet").option("--no-paa", "Skip PAA evidence for agent packet").option("--query <query>", "Business category or workflow query").option("--state <state>", "US state").option("--min-pop <n>", "Minimum city population").option("--max-cities <n>", "Maximum selected cities").option("--per-city <n>", "Maps results per city").option("--concurrency <n>", "City search concurrency").option("--proxy-mode <mode>", "Proxy mode: location, configured, or none").option("--hydrate-top <n>", "Profiles to hydrate per city for competitive audits").option("--reviews <n>", "Review cards to collect per hydrated profile").option("--no-return-partial", "Fail instead of writing partial artifacts");
 }
 function buildHumanCli() {
   const program = new import_commander.Command();
@@ -1159,6 +1918,34 @@ function buildHumanCli() {
     writeOutput(opts.json ? output : renderDoctor(output), opts.json);
     if (!output.ok) process.exitCode = 1;
   });
+  const billing = program.command("billing").description("Inspect billing and start checkout flows.");
+  const billingConcurrency = billing.command("concurrency").description("Manage MCP Scraper concurrency slots.");
+  billingConcurrency.command("info").description("Show current concurrency limit and extra-slot price.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--json", "Print machine-readable JSON").action(async (opts) => {
+    const result = await apiRequest("/billing/credits", "POST", opts, {});
+    if (opts.json) writeOutput(result.concurrency, true);
+    else {
+      const upgrade = result.concurrency?.upgrade;
+      writeOutput([
+        `Current limit: ${result.concurrency?.current_limit ?? "unknown"} concurrent operations`,
+        `Extra slots: ${result.concurrency?.current_extra_slots ?? "unknown"}`,
+        `Extra concurrency slot: ${upgrade?.price_label ?? "$5/month"}`,
+        `Upgrade command: ${upgrade?.terminal_command ?? "mcp-scraper-cli billing concurrency checkout"}`
+      ].join("\n"), false);
+    }
+  });
+  billingConcurrency.command("checkout").description("Create a hosted Stripe checkout for one extra concurrency slot.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--json", "Print machine-readable JSON").option("--no-open", "Print the checkout URL without opening a browser").action(async (opts) => {
+    const result = await apiRequest("/billing/concurrency/terminal-checkout", "POST", opts, {});
+    if (opts.json) {
+      writeOutput(result, true);
+      return;
+    }
+    const opened = opts.open !== false && openExternalUrl(result.checkout_url);
+    writeOutput([
+      `Extra concurrency slot: ${result.price?.price_label ?? "$5/month"}`,
+      opened ? `Opened checkout: ${result.checkout_url}` : `Checkout URL: ${result.checkout_url}`,
+      result.next_step ?? "Complete checkout, then retry the MCP request."
+    ].join("\n"), false);
+  });
   const agent = program.command("agent").description("Generate AI-agent install configs and workflow prompts.");
   agent.command("install <host>").description("Print install/config instructions for codex, claude, or claude-desktop.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--json", "Print machine-readable JSON").action((host, opts) => {
     const valid = ["codex", "claude", "claude-desktop"];
@@ -1181,7 +1968,7 @@ function buildHumanCli() {
     else writeOutput(rows.map((row) => `${row.id}	${row.title}
   ${row.description}`).join("\n"), false);
   });
-  workflow.command("run <id>").description("Run a workflow and save local artifacts.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--output-dir <path>", "Workflow output directory").option("--json", "Print machine-readable JSON").option("--keyword <keyword>", "Agent packet keyword").option("--domain <domain>", "Target domain").option("--location <location>", "Target location").option("--max-questions <n>", "Maximum PAA questions").option("--no-serp", "Skip SERP evidence for agent packet").option("--no-paa", "Skip PAA evidence for agent packet").option("--query <query>", "Business category or workflow query").option("--state <state>", "US state").option("--min-pop <n>", "Minimum city population").option("--max-cities <n>", "Maximum selected cities").option("--per-city <n>", "Maps results per city").option("--concurrency <n>", "City search concurrency").option("--proxy-mode <mode>", "Proxy mode: location, configured, or none").option("--hydrate-top <n>", "Profiles to hydrate per city for competitive audits").option("--reviews <n>", "Review cards to collect per hydrated profile").option("--no-return-partial", "Fail instead of writing partial artifacts").action(async (id, opts) => {
+  workflow.command("run <id>").description("Run a workflow and save local artifacts.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--output-dir <path>", "Workflow output directory").option("--json", "Print machine-readable JSON").option("--keyword <keyword>", "Agent packet keyword").option("--domain <domain>", "Target domain").option("--url <url>", "Target page URL").option("--location <location>", "Target location").option("--max-results <n>", "Maximum SERP or Maps results").option("--max-questions <n>", "Maximum PAA questions").option("--extract-top <n>", "Top result pages or citation pages to extract").option("--depth <n>", "PAA expansion depth").option("--no-serp", "Skip SERP evidence for agent packet").option("--no-paa", "Skip PAA evidence for agent packet").option("--query <query>", "Business category or workflow query").option("--state <state>", "US state").option("--min-pop <n>", "Minimum city population").option("--max-cities <n>", "Maximum selected cities").option("--per-city <n>", "Maps results per city").option("--concurrency <n>", "City search concurrency").option("--proxy-mode <mode>", "Proxy mode: location, configured, or none").option("--hydrate-top <n>", "Profiles to hydrate per city for competitive audits").option("--reviews <n>", "Review cards to collect per hydrated profile").option("--no-return-partial", "Fail instead of writing partial artifacts").action(async (id, opts) => {
     const summary = await runWorkflow(id, workflowInput(id, opts), {
       apiKey: opts.apiKey,
       apiUrl: opts.apiUrl,