mcp-scraper 0.40.1 → 0.40.2

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

@@ -0,0 +1,2671 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/human-cli.ts
+var import_commander = require("commander");
+var import_node_child_process2 = require("child_process");
+var import_promises4 = require("fs/promises");
+var import_node_path3 = require("path");
+
+// src/version.ts
+var PACKAGE_VERSION = "0.40.2";
+
+// src/cli/agent-config.ts
+function apiKeyValue(options) {
+  return options.apiKey?.trim() || "sk_live_your_key";
+}
+function packageSpec(options) {
+  return options.packageSpec?.trim() || "mcp-scraper@latest";
+}
+function combinedNpxArgs(options = {}) {
+  return ["-y", "--package", packageSpec(options), "mcp-scraper"];
+}
+function envConfig(options) {
+  const env = { MCP_SCRAPER_API_KEY: apiKeyValue(options) };
+  const profileName = options.browserProfileName?.trim();
+  if (profileName) env.BROWSER_AGENT_PROFILE_NAME = profileName;
+  if (options.browserProfileSaveChanges === true) env.BROWSER_AGENT_PROFILE_SAVE_CHANGES = "true";
+  return env;
+}
+function tomlInlineTable(value) {
+  const entries = Object.entries(value).map(([key, item]) => `${key} = ${JSON.stringify(item)}`);
+  return `{ ${entries.join(", ")} }`;
+}
+function renderCodexConfig(options = {}) {
+  return [
+    "[mcp_servers.mcp-scraper]",
+    'command = "npx"',
+    `args = ${JSON.stringify(combinedNpxArgs(options))}`,
+    `env = ${tomlInlineTable(envConfig(options))}`
+  ].join("\n");
+}
+function renderClaudeCommand(options = {}) {
+  const env = Object.entries(envConfig(options)).map(([key, value]) => `  --env ${key}=${value}`);
+  return [
+    "claude mcp add mcp-scraper --scope user",
+    ...env,
+    `  -- npx ${combinedNpxArgs(options).join(" ")}`
+  ].join(" \\\n");
+}
+function claudeMcpRemoveArgs() {
+  return ["mcp", "remove", "mcp-scraper", "-s", "user"];
+}
+function claudeMcpGetArgs() {
+  return ["mcp", "get", "mcp-scraper"];
+}
+function parseClaudeMcpGet(stdout) {
+  const command = stdout.match(/^\s*Command:\s*(.+?)\s*$/m)?.[1];
+  if (!command) return null;
+  const argLine = stdout.match(/^\s*Args:\s*(.*?)\s*$/m)?.[1] ?? "";
+  const args = argLine.length ? argLine.split(/\s+/) : [];
+  const env = {};
+  const envBlock = stdout.split(/^\s*Environment:\s*$/m)[1];
+  if (envBlock) {
+    for (const line of envBlock.split("\n")) {
+      const pair = line.match(/^\s{2,}([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!pair) {
+        if (line.trim().length && !/^\s{2,}/.test(line)) break;
+        continue;
+      }
+      env[pair[1]] = pair[2];
+    }
+  }
+  return { command, args, env };
+}
+function claudeMcpRestoreArgs(snapshot) {
+  const args = ["mcp", "add", "mcp-scraper", "--scope", "user"];
+  for (const [key, value] of Object.entries(snapshot.env)) {
+    args.push("--env", `${key}=${value}`);
+  }
+  args.push("--", snapshot.command, ...snapshot.args);
+  return args;
+}
+function claudeMcpAddArgs(options = {}) {
+  const args = ["mcp", "add", "mcp-scraper", "--scope", "user"];
+  for (const [key, value] of Object.entries(envConfig(options))) {
+    args.push("--env", `${key}=${value}`);
+  }
+  args.push("--", "npx", ...combinedNpxArgs(options));
+  return args;
+}
+function normalizeAgentHost(host) {
+  if (host === "claude-code") return "claude";
+  if (host === "claude" || host === "codex" || host === "claude-desktop") return host;
+  throw new Error('Unknown host "' + host + '". Use: codex, claude, claude-code, or claude-desktop');
+}
+function renderClaudeDesktopConfig(options = {}) {
+  return JSON.stringify({
+    mcpServers: {
+      "mcp-scraper": {
+        command: "npx",
+        args: combinedNpxArgs(options),
+        env: envConfig(options)
+      }
+    }
+  }, null, 2);
+}
+function renderAgentInstall(host, options = {}) {
+  const normalizedHost = normalizeAgentHost(host);
+  const restart = "Restart the MCP client so it starts a fresh npx process.";
+  const applyCommand = `MCP_SCRAPER_API_KEY=${apiKeyValue(options)} npx -y -p mcp-scraper@latest mcp-scraper-cli agent install claude --apply`;
+  if (normalizedHost === "codex") {
+    return [
+      "# Codex MCP config",
+      renderCodexConfig(options),
+      "",
+      restart
+    ].join("\n");
+  }
+  if (normalizedHost === "claude") {
+    return [
+      "# Claude Code command",
+      renderClaudeCommand(options),
+      "",
+      "# One-command Claude Code setup",
+      applyCommand,
+      "",
+      restart
+    ].join("\n");
+  }
+  return [
+    "# Claude Desktop config",
+    renderClaudeDesktopConfig(options),
+    "",
+    "Desktop Extension: https://mcpscraper.dev/downloads/mcp-scraper.mcpb",
+    restart
+  ].join("\n");
+}
+
+// src/cli/doctor.ts
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+function status(ok, warn = false) {
+  if (ok) return "pass";
+  return warn ? "warn" : "fail";
+}
+function parseMajor(version) {
+  return Number(version.replace(/^v/, "").split(".")[0] ?? 0);
+}
+async function readKeyFile() {
+  const path = process.env.MCP_SCRAPER_KEY_PATH?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), ".mcp-scraper-key");
+  try {
+    const value = (await (0, import_promises.readFile)(path, "utf8")).trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+async function npmLatest(fetchImpl) {
+  try {
+    const res = await fetchImpl("https://registry.npmjs.org/mcp-scraper/latest", {
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+async function runDoctor(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const apiUrl = (options.apiUrl ?? process.env.MCP_SCRAPER_API_URL ?? "https://mcpscraper.dev").replace(/\/$/, "");
+  const outputDir = options.outputDir ?? process.env.MCP_SCRAPER_OUTPUT_DIR ?? (0, import_node_path.join)((0, import_node_os.homedir)(), "Downloads", "mcp-scraper");
+  const configuredKey = options.apiKey?.trim() || process.env.MCP_SCRAPER_API_KEY?.trim() || await readKeyFile();
+  const latest = await npmLatest(fetchImpl);
+  const checks = [];
+  const nodeMajor = parseMajor(process.version);
+  checks.push({
+    id: "node",
+    label: "Node.js",
+    status: status(nodeMajor >= 20),
+    detail: process.version,
+    fix: nodeMajor >= 20 ? void 0 : "Install Node.js 20 or newer."
+  });
+  checks.push({
+    id: "package_version",
+    label: "Local package",
+    status: latest && latest !== PACKAGE_VERSION ? "warn" : "pass",
+    detail: latest ? `local ${PACKAGE_VERSION}, npm latest ${latest}` : `local ${PACKAGE_VERSION}, npm latest unavailable`,
+    fix: latest && latest !== PACKAGE_VERSION ? "Use mcp-scraper@latest and restart the MCP client." : void 0
+  });
+  checks.push({
+    id: "api_key",
+    label: "API key",
+    status: configuredKey ? "pass" : "warn",
+    detail: configuredKey ? "configured" : "not configured",
+    fix: configuredKey ? void 0 : "Set MCP_SCRAPER_API_KEY or pass --api-key."
+  });
+  try {
+    await (0, import_promises.mkdir)(outputDir, { recursive: true });
+    await (0, import_promises.access)(outputDir);
+    checks.push({ id: "output_dir", label: "Output directory", status: "pass", detail: outputDir });
+  } catch (err) {
+    checks.push({
+      id: "output_dir",
+      label: "Output directory",
+      status: "fail",
+      detail: outputDir,
+      fix: err instanceof Error ? err.message : "Create a writable output directory."
+    });
+  }
+  if (configuredKey) {
+    try {
+      const res = await fetchImpl(`${apiUrl}/me`, {
+        headers: { "x-api-key": configuredKey },
+        signal: AbortSignal.timeout(8e3)
+      });
+      checks.push({
+        id: "api_reachability",
+        label: "Hosted API",
+        status: res.ok ? "pass" : "fail",
+        detail: `${apiUrl}/me returned ${res.status}`,
+        fix: res.ok ? void 0 : "Verify the API key and account status."
+      });
+    } catch (err) {
+      checks.push({
+        id: "api_reachability",
+        label: "Hosted API",
+        status: "fail",
+        detail: err instanceof Error ? err.message : String(err),
+        fix: "Check network access and MCP_SCRAPER_API_URL."
+      });
+    }
+  } else {
+    checks.push({
+      id: "api_reachability",
+      label: "Hosted API",
+      status: "skip",
+      detail: "skipped because no API key is configured"
+    });
+  }
+  checks.push({
+    id: "mcp_config",
+    label: "MCP command",
+    status: "pass",
+    detail: `npx ${combinedNpxArgs().join(" ")}`,
+    fix: "Restart the MCP client after package updates."
+  });
+  return {
+    ok: checks.every((check) => check.status === "pass" || check.status === "skip"),
+    version: PACKAGE_VERSION,
+    npmLatest: latest,
+    checks,
+    recommendedConfig: {
+      command: "npx",
+      args: combinedNpxArgs(),
+      env: { MCP_SCRAPER_API_KEY: configuredKey ? "$MCP_SCRAPER_API_KEY" : "sk_live_your_key" }
+    }
+  };
+}
+function renderDoctor(output) {
+  const icon = { pass: "PASS", warn: "WARN", fail: "FAIL", skip: "SKIP" };
+  const lines = [
+    `mcp-scraper doctor v${output.version}`,
+    "",
+    ...output.checks.map((check) => {
+      const fix = check.fix ? `
+    Fix: ${check.fix}` : "";
+      return `[${icon[check.status]}] ${check.label}: ${check.detail}${fix}`;
+    }),
+    "",
+    `Recommended MCP command: npx ${output.recommendedConfig.args.join(" ")}`
+  ];
+  return lines.join("\n");
+}
+
+// src/cli/prompts.ts
+var AGENT_PROMPTS = {
+  "agent-packet": [
+    "# MCP Scraper Agent Packet Prompt",
+    "",
+    "Use MCP Scraper as the evidence layer. Run the agent-packet workflow for the target keyword/domain, then treat `evidence.json`, `sources.csv`, and `competitors.csv` as source of truth.",
+    "",
+    "Do not invent citations. If a recommendation is not supported by the packet, mark it as an assumption. Turn the evidence into a concise SEO brief, an implementation task list, and content recommendations tied to source rows."
+  ].join("\n"),
+  "local-competitive-audit": [
+    "# MCP Scraper Local Competitive Audit Prompt",
+    "",
+    "Run the local-competitive-audit workflow for the niche and markets. Use the city summary, competitor CSV, and review-insight CSV to identify market difficulty, review themes, GBP category patterns, and weak competitors.",
+    "",
+    "Ground recommendations in Maps rank position, review count, star rating, categories, profile details, and review topics. Do not overstate heuristic opportunity scores."
+  ].join("\n"),
+  "directory-workflow": [
+    "# MCP Scraper Directory Workflow Prompt",
+    "",
+    "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",
+    "",
+    "Use search_serp and harvest_paa to check whether the target brand/domain appears in AI Overview citations, organic results, People Also Ask sources, local pack, forums, and videos. Save evidence before summarizing trends or gaps."
+  ].join("\n"),
+  "serp-brief": [
+    "# MCP Scraper SERP Brief Prompt",
+    "",
+    "Use live SERP, PAA, AI Overview, forum, video, and source evidence to create a writer brief. Tie each recommended section to evidence rows and identify missing proof, entities, comparisons, and customer questions."
+  ].join("\n")
+};
+function listPrompts() {
+  return Object.keys(AGENT_PROMPTS).sort();
+}
+function renderPrompt(name) {
+  const prompt = AGENT_PROMPTS[name];
+  if (!prompt) throw new Error(`Unknown prompt "${name}". Available: ${listPrompts().join(", ")}`);
+  return prompt;
+}
+
+// src/workflows/artifact-writer.ts
+var import_promises2 = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var import_node_child_process = require("child_process");
+
+// src/directory/csv.ts
+function csvCell(value) {
+  if (value === null || value === void 0) return "";
+  const text = String(value);
+  return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+function rowsToCsv(headers, rows) {
+  return [
+    headers.join(","),
+    ...rows.map((row) => headers.map((header) => csvCell(row[header])).join(","))
+  ].join("\n") + "\n";
+}
+
+// src/lib/slugify.ts
+function slugify(s) {
+  return s.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+}
+
+// src/output/memory-library-sink.ts
+async function postToMemoryLibrary(args) {
+  const url = process.env.MCP_MEMORY_INGEST_URL;
+  const key = process.env.MCP_MEMORY_KEY;
+  if (!url || !key) return;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ data: { apiKey: key, title: args.title, content: args.content, source: args.source } })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || body?.result?.error) {
+      console.warn("[memory-library-sink] ingest not accepted:", res.status, body?.result?.message ?? "");
+    }
+  } catch (err) {
+    console.warn("[memory-library-sink] ingest failed:", err?.message);
+  }
+}
+
+// src/workflows/artifact-writer.ts
+function workflowOutputBaseDir(outputDir) {
+  return outputDir?.trim() || process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
+}
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function safeSlug(value) {
+  return slugify(value).replace(/^-+|-+$/g, "").slice(0, 80) || "run";
+}
+var ArtifactWriter = class _ArtifactWriter {
+  constructor(workflowId, title, runId, baseDir, runDir, startedAt, input) {
+    this.workflowId = workflowId;
+    this.title = title;
+    this.runId = runId;
+    this.baseDir = baseDir;
+    this.runDir = runDir;
+    this.startedAt = startedAt;
+    this.input = input;
+  }
+  workflowId;
+  title;
+  runId;
+  baseDir;
+  runDir;
+  startedAt;
+  input;
+  artifacts = [];
+  static async create(workflowId, title, input, outputDir, forcedRunId) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const runId = forcedRunId?.trim() || `${timestamp()}-${safeSlug(workflowId)}-${Math.random().toString(36).slice(2, 8)}`;
+    const nameSource = String(input.keyword ?? input.query ?? input.domain ?? input.state ?? workflowId);
+    const baseDir = workflowOutputBaseDir(outputDir);
+    const runDir = (0, import_node_path2.join)(baseDir, "workflows", workflowId, `${timestamp()}-${safeSlug(nameSource)}-${safeSlug(runId).slice(0, 20)}`);
+    await (0, import_promises2.mkdir)(runDir, { recursive: true });
+    return new _ArtifactWriter(workflowId, title, runId, baseDir, runDir, startedAt, input);
+  }
+  async remember(kind, label, path, rows) {
+    const size = await (0, import_promises2.stat)(path).then((s) => s.size).catch(() => void 0);
+    this.artifacts.push({ kind, label, path, bytes: size, rows });
+    await postToMemoryLibrary({ title: `${this.title} ${label}`, content: `artifact: ${path}`, source: `mcp-scraper-workflow:${this.workflowId}:${this.runId}` });
+    return path;
+  }
+  async writeJson(label, relativePath, data) {
+    const path = (0, import_node_path2.join)(this.runDir, relativePath);
+    await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+    await (0, import_promises2.writeFile)(path, JSON.stringify(data, null, 2), "utf8");
+    return this.remember("json", label, path);
+  }
+  async writeText(label, relativePath, text, kind = "markdown") {
+    const path = (0, import_node_path2.join)(this.runDir, relativePath);
+    await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+    await (0, import_promises2.writeFile)(path, text, "utf8");
+    return this.remember(kind, label, path);
+  }
+  async writeCsv(label, relativePath, headers, rows) {
+    const path = (0, import_node_path2.join)(this.runDir, relativePath);
+    await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+    await (0, import_promises2.writeFile)(path, rowsToCsv(headers, rows), "utf8");
+    return this.remember("csv", label, path, rows.length);
+  }
+  async writeHtml(label, relativePath, html) {
+    return this.writeText(label, relativePath, html, "html_report");
+  }
+  async writeManifest(status2, counts, warnings, errors) {
+    const manifest = {
+      workflow: this.workflowId,
+      title: this.title,
+      runId: this.runId,
+      status: status2,
+      startedAt: this.startedAt,
+      completedAt: status2 === "running" ? null : (/* @__PURE__ */ new Date()).toISOString(),
+      input: this.input,
+      artifacts: this.artifacts,
+      warnings,
+      errors,
+      counts
+    };
+    const path = (0, import_node_path2.join)(this.runDir, "manifest.json");
+    await (0, import_promises2.writeFile)(path, JSON.stringify(manifest, null, 2), "utf8");
+    await updateWorkflowIndex(manifest, path, this.baseDir);
+    return path;
+  }
+};
+function indexPath(baseDir = workflowOutputBaseDir()) {
+  return (0, import_node_path2.join)(baseDir, "workflows", "index.json");
+}
+async function readIndex(baseDir) {
+  const path = indexPath(baseDir);
+  if (!(0, import_node_fs.existsSync)(path)) return { runs: [] };
+  try {
+    return JSON.parse(await (0, import_promises2.readFile)(path, "utf8"));
+  } catch {
+    return { runs: [] };
+  }
+}
+async function updateWorkflowIndex(manifest, manifestPath, baseDir) {
+  if (manifest.status === "running") return;
+  const path = indexPath(baseDir);
+  const index = await readIndex(baseDir);
+  const report = manifest.artifacts.find((a) => a.kind === "html_report")?.path ?? null;
+  const entry = {
+    workflow: manifest.workflow,
+    runId: manifest.runId,
+    status: manifest.status,
+    startedAt: manifest.startedAt,
+    reportPath: report,
+    manifestPath,
+    summary: `${manifest.title} (${manifest.status})`
+  };
+  index.runs = [entry, ...index.runs.filter((r) => r.runId !== manifest.runId)].slice(0, 200);
+  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+  await (0, import_promises2.writeFile)(path, JSON.stringify(index, null, 2), "utf8");
+}
+async function listWorkflowReports(outputDir) {
+  return (await readIndex(workflowOutputBaseDir(outputDir))).runs;
+}
+async function findWorkflowReport(id, outputDir) {
+  const runs = await listWorkflowReports(outputDir);
+  if (id === "last") return runs[0] ?? null;
+  return runs.find((run) => run.runId === id) ?? null;
+}
+async function openWorkflowReport(id, outputDir) {
+  const run = await findWorkflowReport(id, outputDir);
+  if (!run?.reportPath) throw new Error(`No report found for "${id}"`);
+  if ((0, import_node_os2.platform)() === "darwin") {
+    await new Promise((resolve, reject) => {
+      (0, import_node_child_process.execFile)("open", [run.reportPath], (err) => err ? reject(err) : resolve());
+    });
+  }
+  return run.reportPath;
+}
+
+// src/workflows/registry.ts
+var import_promises3 = require("fs/promises");
+var import_zod7 = require("zod");
+
+// src/workflows/http-client.ts
+var WorkflowHttpClient = class {
+  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
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      const message = typeof data.error === "string" ? data.error : `Workflow API ${path} failed with ${res.status}`;
+      throw new Error(message);
+    }
+    return data;
+  }
+};
+
+// src/workflows/workflows/agent-packet.ts
+var import_zod = require("zod");
+
+// src/workflows/report-renderer.ts
+function escapeHtml(value) {
+  return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function renderTable(table) {
+  const rows = table.rows.map((row) => `<tr>${table.columns.map((col) => `<td>${escapeHtml(row[col])}</td>`).join("")}</tr>`).join("\n");
+  return [
+    `<section>`,
+    `<h2>${escapeHtml(table.title)}</h2>`,
+    `<div class="table-wrap"><table>`,
+    `<thead><tr>${table.columns.map((col) => `<th>${escapeHtml(col)}</th>`).join("")}</tr></thead>`,
+    `<tbody>${rows || `<tr><td colspan="${table.columns.length}">No rows</td></tr>`}</tbody>`,
+    `</table></div>`,
+    `</section>`
+  ].join("\n");
+}
+function renderWorkflowReport(input) {
+  const warnings = input.warnings?.length ? `<section class="warnings"><h2>Warnings</h2><ul>${input.warnings.map((w) => `<li>${escapeHtml(w)}</li>`).join("")}</ul></section>` : "";
+  const sections = (input.sections ?? []).map((section) => `<section><h2>${escapeHtml(section.title)}</h2><p>${escapeHtml(section.body)}</p></section>`).join("\n");
+  const tables = (input.tables ?? []).map(renderTable).join("\n");
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(input.title)}</title>`,
+    "<style>",
+    ':root{font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#172026;background:#f6f7f8}',
+    "body{margin:0;padding:32px}main{max-width:1180px;margin:0 auto;background:#fff;border:1px solid #d9dee3;border-radius:8px;padding:28px}",
+    "h1{font-size:30px;line-height:1.15;margin:0 0 8px}h2{font-size:18px;margin:28px 0 12px}p{line-height:1.55;color:#3d4952}.sub{color:#66737f;margin:0 0 20px}",
+    ".summary{background:#eef6f8;border-left:4px solid #12829a;padding:14px 16px;margin:20px 0}.warnings{background:#fff7e8;border-left:4px solid #c87b00;padding:12px 16px}",
+    ".table-wrap{overflow:auto;border:1px solid #dfe5ea;border-radius:8px}table{border-collapse:collapse;width:100%;font-size:13px}th,td{border-bottom:1px solid #edf0f2;padding:9px 10px;text-align:left;vertical-align:top}th{background:#f3f5f7;color:#31404c;position:sticky;top:0}tr:last-child td{border-bottom:0}",
+    "</style>",
+    "</head>",
+    "<body><main>",
+    `<h1>${escapeHtml(input.title)}</h1>`,
+    input.subtitle ? `<p class="sub">${escapeHtml(input.subtitle)}</p>` : "",
+    `<div class="summary">${escapeHtml(input.summary)}</div>`,
+    warnings,
+    sections,
+    tables,
+    "</main></body></html>"
+  ].join("\n");
+}
+
+// src/workflows/workflows/agent-packet.ts
+var AgentPacketInputSchema = import_zod.z.object({
+  keyword: import_zod.z.string().min(1),
+  domain: import_zod.z.string().optional(),
+  location: import_zod.z.string().optional(),
+  maxQuestions: import_zod.z.number().int().min(1).max(200).default(40),
+  includeSerp: import_zod.z.boolean().default(true),
+  includePaa: import_zod.z.boolean().default(true),
+  includeAiOverview: import_zod.z.boolean().default(true),
+  returnPartial: import_zod.z.boolean().default(true)
+});
+function normalizeDomain(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 domainFromUrl(url) {
+  return normalizeDomain(url) ?? "";
+}
+function sourceRows(input, serp, paa) {
+  const target = normalizeDomain(input.domain);
+  const rows = [];
+  for (const result of serp?.organicResults ?? []) {
+    const domain = normalizeDomain(result.domain) ?? domainFromUrl(result.url);
+    rows.push({
+      surface: "organic",
+      position: result.position,
+      title: result.title,
+      url: result.url,
+      domain,
+      question: "",
+      answer_excerpt: result.snippet ?? "",
+      is_target: target ? domain === target : false,
+      is_competitor: target ? domain !== target : true
+    });
+  }
+  for (const row of paa?.flat ?? []) {
+    const url = row.source_cite ?? "";
+    const domain = normalizeDomain(row.source_site ?? "") ?? (url ? domainFromUrl(url) : "");
+    rows.push({
+      surface: "paa",
+      position: "",
+      title: row.source_title ?? row.source_site ?? "",
+      url,
+      domain,
+      question: row.question,
+      answer_excerpt: (row.answer ?? "").slice(0, 240),
+      is_target: target ? domain === target : false,
+      is_competitor: target ? Boolean(domain && domain !== target) : Boolean(domain)
+    });
+  }
+  for (const [i, cite] of (serp?.aiOverview?.citations ?? []).entries()) {
+    const url = cite.href ?? "";
+    const domain = url ? domainFromUrl(url) : "";
+    rows.push({
+      surface: "ai_overview",
+      position: i + 1,
+      title: cite.text ?? "",
+      url,
+      domain,
+      question: "",
+      answer_excerpt: "",
+      is_target: target ? domain === target : false,
+      is_competitor: target ? Boolean(domain && domain !== target) : Boolean(domain)
+    });
+  }
+  return rows;
+}
+function competitorRows(rows, targetDomain) {
+  const byDomain = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const domain = String(row.domain ?? "");
+    if (!domain || domain === targetDomain) continue;
+    const entry = byDomain.get(domain) ?? { organic: [], paa: 0, ai: 0, urls: /* @__PURE__ */ new Set() };
+    if (row.surface === "organic" && row.position) entry.organic.push(Number(row.position));
+    if (row.surface === "paa") entry.paa += 1;
+    if (row.surface === "ai_overview") entry.ai += 1;
+    if (row.url) entry.urls.add(String(row.url));
+    byDomain.set(domain, entry);
+  }
+  return [...byDomain.entries()].map(([domain, entry]) => ({
+    domain,
+    organic_best_position: entry.organic.length ? Math.min(...entry.organic) : "",
+    organic_count: entry.organic.length,
+    paa_mentions: entry.paa,
+    ai_overview_citations: entry.ai,
+    source_url_count: entry.urls.size
+  })).sort((a, b) => Number(a.organic_best_position || 999) - Number(b.organic_best_position || 999));
+}
+var agentPacketWorkflowDefinition = {
+  id: "agent-packet",
+  title: "Agent-Ready SEO Packet",
+  description: "Create an evidence folder for AI agents from live SERP/PAA/AI search surfaces.",
+  inputSchema: AgentPacketInputSchema,
+  createState: () => ({ serp: null, paa: null, warnings: [] }),
+  steps: [
+    {
+      id: "harvest-serp",
+      title: "Harvest organic SERP + AI Overview",
+      async run({ input, state, ctx }) {
+        if (!input.includeSerp) {
+          return { state, output: { skipped: true, reason: "includeSerp is false" } };
+        }
+        try {
+          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);
+          return {
+            state: { ...state, serp },
+            output: {
+              organicResults: serp.organicResults?.length ?? 0,
+              localPack: serp.localPack?.length ?? 0,
+              aiOverviewDetected: Boolean(serp.aiOverview?.detected),
+              aiOverviewCitations: serp.aiOverview?.citations?.length ?? 0
+            }
+          };
+        } catch (err) {
+          const message = `SERP evidence unavailable: ${err instanceof Error ? err.message : String(err)}`;
+          return { state: { ...state, warnings: [...state.warnings, message] }, output: { error: message }, warnings: [message] };
+        }
+      }
+    },
+    {
+      id: "harvest-paa",
+      title: "Harvest People Also Ask",
+      async run({ input, state, ctx }) {
+        if (!input.includePaa) {
+          return { state, output: { skipped: true, reason: "includePaa is false" } };
+        }
+        try {
+          const 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);
+          return {
+            state: { ...state, paa },
+            output: { paaQuestions: paa.flat?.length ?? 0 }
+          };
+        } catch (err) {
+          const message = `PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`;
+          return { state: { ...state, warnings: [...state.warnings, message] }, output: { error: message }, warnings: [message] };
+        }
+      }
+    },
+    {
+      id: "assemble",
+      title: "Assemble evidence packet",
+      async run({ input, state, ctx }) {
+        const { serp, paa } = state;
+        const warnings = state.warnings;
+        if (!serp && !paa && !input.returnPartial) throw new Error("No SEO evidence was collected");
+        const rows = sourceRows(input, serp, paa);
+        const target = normalizeDomain(input.domain);
+        const competitors = competitorRows(rows, target);
+        const evidence = {
+          input,
+          serp: serp ?? { status: "skipped" },
+          paa: paa ?? { status: "skipped" },
+          target: {
+            domain: target,
+            organicPositions: rows.filter((r) => r.surface === "organic" && r.is_target).map((r) => Number(r.position)),
+            citedInAiOverview: rows.some((r) => r.surface === "ai_overview" && r.is_target),
+            citedInPaa: rows.some((r) => r.surface === "paa" && r.is_target)
+          },
+          competitors,
+          warnings
+        };
+        await ctx.artifacts.writeJson("Evidence JSON", "evidence.json", evidence);
+        await ctx.artifacts.writeCsv("Sources CSV", "sources.csv", ["surface", "position", "title", "url", "domain", "question", "answer_excerpt", "is_target", "is_competitor"], rows);
+        await ctx.artifacts.writeCsv("Competitors CSV", "competitors.csv", ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], competitors);
+        const brief = [
+          `# SEO Evidence Brief: ${input.keyword}`,
+          "",
+          `Location: ${input.location ?? "not specified"}`,
+          `Target domain: ${target ?? "not specified"}`,
+          "",
+          "## Evidence Summary",
+          `- Organic rows: ${rows.filter((r) => r.surface === "organic").length}`,
+          `- PAA rows: ${rows.filter((r) => r.surface === "paa").length}`,
+          `- AI Overview citations: ${rows.filter((r) => r.surface === "ai_overview").length}`,
+          `- Competitor domains: ${competitors.length}`,
+          "",
+          "## Recommended Use",
+          "Use the CSV files as source of truth. Tie content recommendations to evidence rows and mark unsupported ideas as assumptions."
+        ].join("\n");
+        await ctx.artifacts.writeText("Brief", "brief.md", brief);
+        await ctx.artifacts.writeText("Agent tasks", "tasks.md", [
+          "# Agent Tasks",
+          "",
+          "- [ ] Read `evidence.json` before writing recommendations.",
+          "- [ ] Compare the target domain against `competitors.csv`.",
+          "- [ ] Use `sources.csv` for citations and source-grounded page sections.",
+          "- [ ] Mark unsupported recommendations as assumptions."
+        ].join("\n"));
+        await ctx.artifacts.writeText("Agent instructions", "agent-instructions.md", [
+          "# Agent Instructions",
+          "",
+          "You are working from an MCP Scraper SEO evidence packet. Use `evidence.json` and CSV files as source of truth. Do not invent citations. If a recommendation is not supported by evidence, mark it as an assumption."
+        ].join("\n"));
+        const summary = `${rows.length} evidence rows and ${competitors.length} competitor domains collected.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "Agent-Ready SEO Packet",
+          subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Competitor Domains", columns: ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], rows: competitors.slice(0, 50) },
+            { title: "Evidence Sources", columns: ["surface", "position", "title", "domain", "question", "is_target"], rows: rows.slice(0, 100) }
+          ]
+        }));
+        const status2 = warnings.length ? "partial" : "succeeded";
+        const counts = { sources: rows.length, competitors: competitors.length };
+        await ctx.artifacts.writeManifest(status2, counts, warnings, []);
+        return {
+          state,
+          output: { sources: rows.length, competitors: competitors.length, status: status2 },
+          summary: { title: "Agent-Ready SEO Packet", summary, status: status2, counts, warnings, errors: [], reportPath }
+        };
+      }
+    }
+  ]
+};
+
+// src/workflows/workflows/directory.ts
+var import_zod3 = require("zod");
+
+// src/schemas.ts
+var import_zod2 = require("zod");
+var DEFAULT_PROXY_MODE = "none";
+var DEFAULT_MAPS_PROXY_MODE = "none";
+var HarvestOptionsSchema = import_zod2.z.object({
+  query: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop"),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  keepDefaultProxy: import_zod2.z.boolean().optional(),
+  requireUsEgress: import_zod2.z.boolean().optional(),
+  maxAttempts: import_zod2.z.number().int().min(1).max(12).optional(),
+  debug: import_zod2.z.boolean().default(false),
+  depth: import_zod2.z.number().int().min(1).max(30).default(3),
+  maxQuestions: import_zod2.z.number().int().min(1).max(1e3).default(100),
+  headless: import_zod2.z.boolean().default(false),
+  profileDir: import_zod2.z.string().optional(),
+  proxy: import_zod2.z.string().url().optional(),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  outputDir: import_zod2.z.string().default("./paa-output"),
+  format: import_zod2.z.enum(["json", "csv", "both"]).default("both"),
+  serpOnly: import_zod2.z.boolean().default(false),
+  pages: import_zod2.z.number().int().min(1).max(2).default(1),
+  recency: import_zod2.z.enum(["day", "week", "month", "year"]).optional(),
+  softDeadlineMs: import_zod2.z.number().optional()
+});
+var MapsPlaceOptionsSchema = import_zod2.z.object({
+  businessName: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().min(1),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  includeReviews: import_zod2.z.boolean().default(false),
+  maxReviews: import_zod2.z.number().int().min(1).max(500).default(50),
+  includeServices: import_zod2.z.boolean().default(false),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var MapsSearchOptionsSchema = import_zod2.z.object({
+  query: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  maxResults: import_zod2.z.number().int().min(1).max(50).default(10),
+  includeServices: import_zod2.z.boolean().default(false),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  serpRedirect: import_zod2.z.boolean().optional(),
+  forceDirectEgress: import_zod2.z.boolean().optional(),
+  debug: import_zod2.z.boolean().default(false),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var RawPAAItemSchema = import_zod2.z.object({
+  question: import_zod2.z.string().min(1),
+  answer: import_zod2.z.string().optional(),
+  sourceTitle: import_zod2.z.string().optional(),
+  sourceSite: import_zod2.z.string().optional(),
+  sourceCite: import_zod2.z.string().optional()
+});
+var RawMapsOverviewSchema = import_zod2.z.object({
+  name: import_zod2.z.string().nullable(),
+  rating: import_zod2.z.string().nullable(),
+  reviewCount: import_zod2.z.string().nullable(),
+  category: import_zod2.z.string().nullable(),
+  address: import_zod2.z.string().nullable(),
+  hoursSummary: import_zod2.z.string().nullable(),
+  phone: import_zod2.z.string().nullable(),
+  phoneDisplay: import_zod2.z.string().nullable(),
+  website: import_zod2.z.string().nullable(),
+  plusCode: import_zod2.z.string().nullable(),
+  bookingUrl: import_zod2.z.string().nullable()
+});
+var RawMapsHoursRowSchema = import_zod2.z.object({
+  day: import_zod2.z.string(),
+  hours: import_zod2.z.string()
+});
+var RawMapsReviewStatsSchema = import_zod2.z.object({
+  reviewHistogram: import_zod2.z.array(import_zod2.z.object({
+    stars: import_zod2.z.number(),
+    count: import_zod2.z.string()
+  })),
+  reviewTopics: import_zod2.z.array(import_zod2.z.object({
+    label: import_zod2.z.string(),
+    count: import_zod2.z.string()
+  }))
+});
+var RawMapsReviewCardSchema = import_zod2.z.object({
+  reviewId: import_zod2.z.string(),
+  author: import_zod2.z.string().nullable(),
+  stars: import_zod2.z.string().nullable(),
+  date: import_zod2.z.string().nullable(),
+  text: import_zod2.z.string().nullable(),
+  ownerResponse: import_zod2.z.string().nullable()
+});
+var RawMapsAboutAttributeSchema = import_zod2.z.object({
+  section: import_zod2.z.string(),
+  attribute: import_zod2.z.string()
+});
+
+// src/workflows/workflows/directory.ts
+var DirectoryWorkflowCliInputSchema = import_zod3.z.object({
+  query: import_zod3.z.string().min(1),
+  state: import_zod3.z.string().min(2).default("TN"),
+  minPopulation: import_zod3.z.number().int().min(0).default(1e5),
+  maxCities: import_zod3.z.number().int().min(1).max(100).default(25),
+  maxResultsPerCity: import_zod3.z.number().int().min(1).max(50).default(20),
+  concurrency: import_zod3.z.number().int().min(1).max(5).default(5),
+  proxyMode: import_zod3.z.enum(["configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  saveCsv: import_zod3.z.boolean().default(true)
+});
+function directoryRows(result) {
+  const rows = [];
+  for (const city of result.cities) {
+    if (!city.results.length) {
+      rows.push({
+        source_query: result.query,
+        source_location: city.location,
+        city: city.city,
+        state: city.state,
+        population: city.population,
+        result_position: null,
+        business_name: null,
+        review_stars: null,
+        review_count: null,
+        category: null,
+        address: null,
+        phone: null,
+        website_url: null,
+        place_url: null,
+        cid: null,
+        cid_decimal: null,
+        result_status: city.status,
+        error: city.error
+      });
+      continue;
+    }
+    for (const business of city.results) {
+      rows.push({
+        source_query: result.query,
+        source_location: city.location,
+        city: city.city,
+        state: city.state,
+        population: city.population,
+        result_position: business.position,
+        business_name: business.name,
+        review_stars: business.rating,
+        review_count: business.reviewCount,
+        category: business.category,
+        address: business.address,
+        phone: business.phone,
+        website_url: business.websiteUrl,
+        place_url: business.placeUrl,
+        cid: business.cid,
+        cid_decimal: business.cidDecimal,
+        result_status: city.status,
+        error: city.error
+      });
+    }
+  }
+  return rows;
+}
+var DIRECTORY_CSV_HEADERS = [
+  "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"
+];
+var directoryWorkflowDefinition = {
+  id: "directory",
+  title: "Directory Workflow",
+  description: "Select city markets and export Google Maps business candidates.",
+  inputSchema: DirectoryWorkflowCliInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const result = await ctx.client.post("/directory/run", { ...input, background: false }, 9e5);
+    await ctx.artifacts.writeJson("Directory evidence", "evidence.json", result);
+    const rows = directoryRows(result);
+    await ctx.artifacts.writeCsv("Directory CSV", "exports/directory.csv", DIRECTORY_CSV_HEADERS, rows);
+    const cityRows = result.cities.map((city) => ({
+      city: city.city,
+      state: city.state,
+      population: city.population,
+      status: city.status,
+      result_count: city.resultCount,
+      error: city.error ?? ""
+    }));
+    const topRows = rows.filter((row) => row.business_name).slice(0, 100).map((row) => ({
+      city: row.city,
+      position: row.result_position,
+      business: row.business_name,
+      rating: row.review_stars,
+      reviews: row.review_count,
+      category: row.category,
+      website: row.website_url
+    }));
+    const summary = `${result.selectedCityCount} cities processed with ${result.totalResultCount} Maps results.`;
+    await ctx.artifacts.writeText("Summary", "summary.md", `# Directory Workflow
+
+${summary}
+`);
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "Directory Workflow",
+      subtitle: `${input.query} \xB7 ${input.state}`,
+      summary,
+      warnings: result.warnings,
+      tables: [
+        { title: "Cities", columns: ["city", "state", "population", "status", "result_count", "error"], rows: cityRows },
+        { title: "Top Results", columns: ["city", "position", "business", "rating", "reviews", "category", "website"], rows: topRows }
+      ]
+    }));
+    const status2 = result.cities.some((city) => city.status === "failed") ? "partial" : "succeeded";
+    const counts = { cities: result.selectedCityCount, results: result.totalResultCount, rows: rows.length };
+    await ctx.artifacts.writeManifest(status2, counts, result.warnings, []);
+    return { title: "Directory Workflow", summary, status: status2, counts, warnings: result.warnings, errors: [], reportPath };
+  }
+};
+
+// src/workflows/workflows/get-leads.ts
+var import_zod4 = require("zod");
+var GetLeadsInputSchema = import_zod4.z.object({
+  query: import_zod4.z.string().min(1).describe('Business category, niche, or keyword to search on Google Maps, e.g. "roofers", "med spas", "dentists". Do not include the city here.'),
+  location: import_zod4.z.string().min(1).describe('City / market to search, e.g. "Houston, TX" or "Austin, Texas".'),
+  maxResults: import_zod4.z.number().int().min(1).max(50).default(25).describe("How many Maps businesses to collect for the market. Maximum 50."),
+  enrichWebsites: import_zod4.z.boolean().default(true).describe("Visit each business website (home + contact pages) to harvest email and social links. Uses the proxy/browser-backed extractor so blocked sites still resolve."),
+  hydrateReviewCounts: import_zod4.z.boolean().default(true).describe("Deep-dive each profile to confirm the review count and booking URL that the Maps search list omits."),
+  concurrency: import_zod4.z.number().int().min(1).max(4).default(3).describe("How many businesses to enrich in parallel. Keep low to respect per-account concurrency limits."),
+  proxyMode: import_zod4.z.enum(["configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy behavior for the Maps search. Leave unset for clean egress; country/region localization comes from gl/hl plus the city or region in the query.")
+});
+var LEADS_CSV_HEADERS = [
+  "position",
+  "business_name",
+  "review_stars",
+  "review_count",
+  "category",
+  "address",
+  "phone",
+  "website",
+  "email",
+  "email_domain_match",
+  "email_status",
+  "socials",
+  "booking_url",
+  "place_url",
+  "cid",
+  "source_location"
+];
+var EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+var MAILTO_RE = /mailto:([^"'?>\s]+)/gi;
+var SOCIAL_RE = /https?:\/\/(?:www\.)?(?:facebook|instagram|linkedin|twitter|youtube|tiktok)\.com\/[^\s"'<>)]+/gi;
+var EMAIL_BAD = [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico", "sentry", "wix.com", "wixpress", "example.", "godaddy", "squarespace", "schema.org", "@2x", "u003e", "core-js"];
+var EMAIL_PREFIX = ["info@", "office@", "contact@", "sales@", "hello@", "admin@", "service@", "support@"];
+var SOCIAL_SKIP = ["/sharer", "/share?", "/intent/", "plugins/", "/dialog/", "platform.", "badge", "developers."];
+async function mapLimit(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(limit, items.length) }, () => worker()));
+  return out;
+}
+function hostRoot(url) {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "").split(".")[0].toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function cleanEmails(raw) {
+  const out = /* @__PURE__ */ new Set();
+  for (const value of raw) {
+    const email = value.trim().toLowerCase().replace(/\.$/, "");
+    if (email.split("@").length !== 2) continue;
+    if (email.length > 60) continue;
+    if (EMAIL_BAD.some((bad) => email.includes(bad))) continue;
+    out.add(email);
+  }
+  return [...out];
+}
+function pickEmail(emails, host) {
+  if (!emails.length) return "";
+  const root = hostRoot(host);
+  for (const prefix of EMAIL_PREFIX) {
+    const hit = emails.find((e) => e.startsWith(prefix) && root && e.split("@")[1].includes(root));
+    if (hit) return hit;
+  }
+  const domainHit = emails.find((e) => root && e.split("@")[1].includes(root));
+  if (domainHit) return domainHit;
+  for (const prefix of EMAIL_PREFIX) {
+    const hit = emails.find((e) => e.startsWith(prefix));
+    if (hit) return hit;
+  }
+  return emails[0];
+}
+function parseContacts(html) {
+  const mailtos = [...html.matchAll(MAILTO_RE)].map((m) => decodeURIComponent(m[1]).split("?")[0]);
+  const inline = html.match(EMAIL_RE) ?? [];
+  const emails = cleanEmails([...mailtos, ...inline]);
+  const socials = [...new Set((html.match(SOCIAL_RE) ?? []).map((s) => s.replace(/[)"'<>]+$/, "")).filter((s) => !SOCIAL_SKIP.some((skip) => s.toLowerCase().includes(skip))))].slice(0, 5);
+  return { emails, socials };
+}
+function buildAttemptUrls(website) {
+  const urls = /* @__PURE__ */ new Set();
+  urls.add(website);
+  try {
+    const origin = new URL(website).origin;
+    urls.add(`${origin}/contact`);
+    urls.add(`${origin}/contact-us`);
+  } catch {
+    return [...urls];
+  }
+  return [...urls].slice(0, 3);
+}
+var getLeadsWorkflowDefinition = {
+  id: "get-leads",
+  title: "Get Leads",
+  description: "Build an outreach-ready local lead list: Google Maps search for a niche in a market, confirm review counts + booking URLs, then visit each business website (home + contact) to harvest email and social links, with proxy/browser-backed extraction so blocked sites still resolve. Saves a leads CSV.",
+  inputSchema: GetLeadsInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    const errors = [];
+    const search = await ctx.client.post("/maps/search", {
+      query: input.query,
+      location: input.location,
+      maxResults: input.maxResults,
+      proxyMode: input.proxyMode
+    }, 18e4);
+    await ctx.artifacts.writeJson("Maps search raw", "raw/maps-search.json", search);
+    const seen = /* @__PURE__ */ new Set();
+    const deduped = search.results.filter((result) => {
+      const key = result.cid ?? result.placeUrl ?? result.name.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    const rows = await mapLimit(deduped, input.concurrency, async (result) => {
+      let reviewCount = result.reviewCount ?? "";
+      let bookingUrl = "";
+      let website = result.websiteUrl ?? "";
+      if (input.hydrateReviewCounts) {
+        try {
+          const place = await ctx.client.post("/maps/place", {
+            businessName: result.name,
+            location: input.location,
+            includeReviews: false
+          }, 18e4);
+          reviewCount = place.reviewCount ?? reviewCount;
+          bookingUrl = place.bookingUrl ?? "";
+          website = website || (place.website ?? "");
+        } catch (err) {
+          warnings.push(`Review hydration failed for ${result.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+      let email = "";
+      let socials = [];
+      let emailStatus = website ? "no email found" : "no website";
+      let domainMatch = "";
+      if (input.enrichWebsites && website) {
+        const attempts = buildAttemptUrls(website);
+        let reached = false;
+        const allEmails = [];
+        const allSocials = /* @__PURE__ */ new Set();
+        for (const attemptUrl of attempts) {
+          try {
+            const page = await ctx.client.post("/extract-url", { url: attemptUrl }, 12e4);
+            reached = true;
+            const parsed = parseContacts(page.bodyHtml ?? page.bodyMarkdown ?? "");
+            allEmails.push(...parsed.emails);
+            parsed.socials.forEach((s) => allSocials.add(s));
+            if (parsed.emails.length) break;
+          } catch {
+            continue;
+          }
+        }
+        socials = [...allSocials].slice(0, 5);
+        email = pickEmail([...new Set(allEmails)], website);
+        if (email) {
+          domainMatch = hostRoot(website) && email.split("@")[1].includes(hostRoot(website)) ? "yes" : "NO-verify";
+          emailStatus = domainMatch === "yes" ? "ok" : "ok (off-domain \u2014 verify)";
+        } else if (!reached) {
+          emailStatus = "site unreachable";
+        } else if (socials.length) {
+          emailStatus = "form/social only";
+        }
+      }
+      return {
+        position: result.position,
+        business_name: result.name,
+        review_stars: result.rating ?? "",
+        review_count: reviewCount,
+        category: result.category ?? "",
+        address: result.address ?? "",
+        phone: result.phone ?? "",
+        website,
+        email,
+        email_domain_match: domainMatch,
+        email_status: emailStatus,
+        socials: socials.join(" ; "),
+        booking_url: bookingUrl,
+        place_url: result.placeUrl,
+        cid: result.cid ?? "",
+        source_location: input.location
+      };
+    });
+    await ctx.artifacts.writeCsv("Leads CSV", "exports/leads.csv", LEADS_CSV_HEADERS, rows);
+    await ctx.artifacts.writeJson("Leads evidence", "evidence.json", { input, search: { query: search.searchQuery, resultCount: search.resultCount }, rows });
+    const withEmail = rows.filter((r) => r.email).length;
+    const domainMatched = rows.filter((r) => r.email_domain_match === "yes").length;
+    const withReviewCount = rows.filter((r) => r.review_count).length;
+    const withSocials = rows.filter((r) => r.socials).length;
+    const withWebsite = rows.filter((r) => r.website).length;
+    const summary = `${rows.length} ${input.query} in ${input.location}: ${withEmail} emails (${domainMatched} domain-matched), ${withReviewCount} review counts, ${withSocials} with socials.`;
+    await ctx.artifacts.writeText("Summary", "summary.md", `# Get Leads
+
+${summary}
+`);
+    await ctx.artifacts.writeText("Agent tasks", "tasks.md", [
+      "# Get Leads \u2014 next steps",
+      "",
+      "- [ ] Verify deliverability of the harvested emails before outreach (MX/SMTP check).",
+      '- [ ] For "form/social only" rows, use the website contact form or the captured social profile.',
+      '- [ ] Treat "off-domain \u2014 verify" emails with care; they may belong to a web developer or parent brand.',
+      "- [ ] Respect CAN-SPAM / GDPR \u2014 scraped contact data is not consent to email."
+    ].join("\n"));
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "Get Leads",
+      subtitle: `${input.query} \xB7 ${input.location}`,
+      summary,
+      warnings,
+      tables: [
+        {
+          title: "Leads",
+          columns: ["position", "business_name", "review_stars", "review_count", "phone", "website", "email", "email_status", "socials", "booking_url"],
+          rows
+        }
+      ]
+    }));
+    const status2 = errors.length ? "failed" : warnings.length ? "partial" : "succeeded";
+    const counts = {
+      businesses: rows.length,
+      withWebsite,
+      emails: withEmail,
+      domainMatchedEmails: domainMatched,
+      reviewCounts: withReviewCount,
+      withSocials
+    };
+    await ctx.artifacts.writeManifest(status2, counts, warnings, errors);
+    return { title: "Get Leads", summary, status: status2, counts, warnings, errors, reportPath };
+  }
+};
+
+// src/workflows/workflows/local-competitive-audit.ts
+var import_zod5 = require("zod");
+var LocalCompetitiveAuditInputSchema = import_zod5.z.object({
+  query: import_zod5.z.string().min(1),
+  state: import_zod5.z.string().min(2).default("TN"),
+  minPopulation: import_zod5.z.number().int().min(0).default(1e5),
+  maxCities: import_zod5.z.number().int().min(1).max(100).default(25),
+  maxResultsPerCity: import_zod5.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod5.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod5.z.number().int().min(0).max(500).default(50),
+  concurrency: import_zod5.z.number().int().min(1).max(5).default(5),
+  proxyMode: import_zod5.z.enum(["configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod5.z.boolean().default(true)
+});
+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(limit, items.length) }, () => worker()));
+  return out;
+}
+function numberFrom(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 median(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 termsFrom(texts) {
+  const stop = /* @__PURE__ */ new Set(["the", "and", "for", "with", "that", "this", "was", "were", "are", "you", "our", "they", "had", "have", "not", "but", "from", "very", "great", "good"]);
+  const counts = /* @__PURE__ */ new Map();
+  for (const text of texts) {
+    for (const token of text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/)) {
+      if (token.length < 4 || stop.has(token)) continue;
+      counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([term, count]) => `${term} (${count})`).join("; ");
+}
+var localCompetitiveAuditWorkflowDefinition = {
+  id: "local-competitive-audit",
+  title: "Local Competitive Audit",
+  description: "Audit local Maps competitors, categories, review counts, and review themes across city markets.",
+  inputSchema: LocalCompetitiveAuditInputSchema,
+  async run(input, ctx) {
+    await ctx.artifacts.writeManifest("running", {}, [], []);
+    const warnings = [];
+    const errors = [];
+    const 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,
+      background: false
+    }, 9e5);
+    await ctx.artifacts.writeJson("Directory raw JSON", "raw/directory-workflow.json", directory);
+    const baseRows = directoryRows(directory);
+    await ctx.artifacts.writeCsv("Base directory CSV", "exports/directory.csv", DIRECTORY_CSV_HEADERS, baseRows);
+    const selected = directory.cities.flatMap(
+      (city) => city.results.slice(0, input.hydrateTop).map((result) => ({ city, result }))
+    );
+    const seen = /* @__PURE__ */ new Set();
+    const deduped = selected.filter(({ city, result }) => {
+      const key = result.cid ?? result.placeUrl ?? `${city.location}:${result.name.toLowerCase()}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    const hydrated = await mapLimit2(deduped, 3, async ({ city, result }, index) => {
+      try {
+        const detail = await ctx.client.post("/maps/place", {
+          businessName: result.name,
+          location: city.location,
+          includeReviews: input.maxReviews > 0,
+          maxReviews: Math.max(1, input.maxReviews)
+        }, 18e4);
+        await ctx.artifacts.writeJson(`${result.name} profile`, `raw/maps-place-intel/${index + 1}-${result.name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.json`, detail);
+        return { city, result, detail, error: null };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(`Profile hydration failed for ${result.name} (${city.location}): ${message}`);
+        return { city, result, detail: null, error: message };
+      }
+    });
+    const competitorRows2 = hydrated.map(({ city, result, detail, error }) => {
+      const reviews = detail?.reviews ?? [];
+      const ownerResponses = reviews.filter((r) => r.ownerResponse).length;
+      return {
+        city: city.city,
+        state: city.state,
+        source_location: city.location,
+        result_position: result.position,
+        business_name: result.name,
+        category: detail?.category ?? result.category,
+        review_stars: detail?.rating ?? result.rating,
+        review_count: detail?.reviewCount ?? result.reviewCount,
+        phone: result.phone,
+        website_url: detail?.website ?? result.websiteUrl,
+        place_url: result.placeUrl,
+        cid: result.cid,
+        cid_decimal: result.cidDecimal,
+        hydrated: detail ? "true" : "false",
+        reviews_status: detail?.reviewsStatus ?? "",
+        review_topics: (detail?.reviewTopics ?? []).map((t) => `${t.label} (${t.count})`).join("; "),
+        owner_response_rate: reviews.length ? (ownerResponses / reviews.length).toFixed(2) : "",
+        error: error ?? ""
+      };
+    });
+    const reviewInsightRows = hydrated.map(({ city, result, detail }) => {
+      const reviews = detail?.reviews ?? [];
+      const positive = reviews.filter((r) => Number(r.stars) >= 5 && r.text).map((r) => r.text);
+      const negative = reviews.filter((r) => Number(r.stars) > 0 && Number(r.stars) <= 3 && r.text).map((r) => r.text);
+      return {
+        city: city.city,
+        business_name: result.name,
+        cid: result.cid,
+        review_count: detail?.reviewCount ?? result.reviewCount,
+        average_rating: detail?.rating ?? result.rating,
+        topics: (detail?.reviewTopics ?? []).map((t) => `${t.label} (${t.count})`).join("; "),
+        praise_terms: termsFrom(positive),
+        complaint_terms: termsFrom(negative),
+        positive_sample: positive[0]?.slice(0, 280) ?? "",
+        negative_sample: negative[0]?.slice(0, 280) ?? ""
+      };
+    });
+    const citySummaryRows = directory.cities.map((city) => {
+      const resultReviewCounts = city.results.map((r) => numberFrom(r.reviewCount));
+      const resultRatings = city.results.map((r) => numberFrom(r.rating));
+      const topThreeReviews = city.results.slice(0, 3).map((r) => numberFrom(r.reviewCount)).filter((v) => v !== null);
+      const categories = /* @__PURE__ */ new Map();
+      for (const result of city.results) {
+        if (!result.category) continue;
+        categories.set(result.category, (categories.get(result.category) ?? 0) + 1);
+      }
+      const medReviews = median(resultReviewCounts);
+      const medRating = median(resultRatings);
+      const topThreeAvg = topThreeReviews.length ? Math.round(topThreeReviews.reduce((a, b) => a + b, 0) / topThreeReviews.length) : null;
+      const difficulty = Math.min(100, Math.round((topThreeAvg ?? 0) / 20 + (medRating ?? 0) * 10 + city.results.filter((r) => r.websiteUrl).length));
+      const opportunity = Math.max(0, 100 - difficulty);
+      return {
+        city: city.city,
+        state: city.state,
+        population: city.population,
+        result_count: city.resultCount,
+        median_review_count: medReviews ?? "",
+        median_rating: medRating ?? "",
+        top_three_average_review_count: topThreeAvg ?? "",
+        top_categories: [...categories.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([cat, count]) => `${cat} (${count})`).join("; "),
+        opportunity_score: opportunity,
+        difficulty_score: difficulty
+      };
+    });
+    await ctx.artifacts.writeCsv("Competitors CSV", "competitors.csv", ["city", "state", "source_location", "result_position", "business_name", "category", "review_stars", "review_count", "phone", "website_url", "place_url", "cid", "cid_decimal", "hydrated", "reviews_status", "review_topics", "owner_response_rate", "error"], competitorRows2);
+    await ctx.artifacts.writeCsv("Review insights CSV", "review-insights.csv", ["city", "business_name", "cid", "review_count", "average_rating", "topics", "praise_terms", "complaint_terms", "positive_sample", "negative_sample"], reviewInsightRows);
+    await ctx.artifacts.writeCsv("City summary CSV", "city-summary.csv", ["city", "state", "population", "result_count", "median_review_count", "median_rating", "top_three_average_review_count", "top_categories", "opportunity_score", "difficulty_score"], citySummaryRows);
+    await ctx.artifacts.writeJson("Audit evidence", "evidence.json", { input, directory, hydrated, citySummaryRows, competitorRows: competitorRows2, reviewInsightRows });
+    await ctx.artifacts.writeText("Agent tasks", "tasks.md", [
+      "# Local Competitive Audit Tasks",
+      "",
+      "- [ ] Review city opportunity and difficulty scores as heuristics, not absolute truth.",
+      "- [ ] Use review topics and samples as customer-language evidence.",
+      "- [ ] Compare target GBP category, review count, and website quality against top competitors.",
+      "- [ ] Identify cities with low review-count leaders and weak website coverage."
+    ].join("\n"));
+    const summary = `${directory.selectedCityCount} cities, ${directory.totalResultCount} Maps results, ${hydrated.filter((h) => h.detail).length} hydrated profiles.`;
+    await ctx.artifacts.writeText("Summary", "summary.md", `# Local Competitive Audit
+
+${summary}
+`);
+    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+      title: "Local Competitive Audit",
+      subtitle: `${input.query} \xB7 ${input.state}`,
+      summary,
+      warnings,
+      tables: [
+        { title: "City Opportunity", columns: ["city", "state", "population", "result_count", "median_review_count", "median_rating", "top_three_average_review_count", "top_categories", "opportunity_score", "difficulty_score"], rows: citySummaryRows },
+        { title: "Hydrated Competitors", columns: ["city", "result_position", "business_name", "category", "review_stars", "review_count", "hydrated", "review_topics"], rows: competitorRows2.slice(0, 100) },
+        { title: "Review Insights", columns: ["city", "business_name", "topics", "praise_terms", "complaint_terms"], rows: reviewInsightRows.slice(0, 100) }
+      ]
+    }));
+    const status2 = warnings.length || directory.cities.some((city) => city.status === "failed") ? "partial" : "succeeded";
+    const counts = { cities: directory.selectedCityCount, mapsResults: directory.totalResultCount, hydratedProfiles: hydrated.filter((h) => h.detail).length };
+    await ctx.artifacts.writeManifest(status2, counts, warnings, errors);
+    return { title: "Local Competitive Audit", summary, status: status2, counts, warnings, errors, reportPath };
+  }
+};
+
+// src/workflows/workflows/comparison-briefs.ts
+var import_zod6 = 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 mapLimit3(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_zod6.z.enum(["configured", "none"]);
+var MapComparisonInputSchema = import_zod6.z.object({
+  query: import_zod6.z.string().min(1),
+  location: import_zod6.z.string().optional(),
+  state: import_zod6.z.string().optional(),
+  minPopulation: import_zod6.z.number().int().min(0).default(1e5),
+  maxCities: import_zod6.z.number().int().min(1).max(100).default(5),
+  maxResultsPerCity: import_zod6.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod6.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod6.z.number().int().min(0).max(500).default(25),
+  concurrency: import_zod6.z.number().int().min(1).max(5).default(5),
+  proxyMode: ProxyModeSchema.default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod6.z.boolean().default(true)
+}).refine((input) => input.location || input.state, {
+  message: "Either location or state is required for map-comparison"
+});
+var SerpComparisonInputSchema = import_zod6.z.object({
+  keyword: import_zod6.z.string().min(1),
+  domain: import_zod6.z.string().optional(),
+  url: import_zod6.z.string().url().optional(),
+  location: import_zod6.z.string().optional(),
+  maxResults: import_zod6.z.number().int().min(1).max(20).default(10),
+  maxQuestions: import_zod6.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod6.z.number().int().min(0).max(10).default(5),
+  includePaa: import_zod6.z.boolean().default(true),
+  includeAiOverview: import_zod6.z.boolean().default(true),
+  returnPartial: import_zod6.z.boolean().default(true)
+});
+var PaaExpansionBriefInputSchema = import_zod6.z.object({
+  keyword: import_zod6.z.string().min(1),
+  location: import_zod6.z.string().optional(),
+  maxQuestions: import_zod6.z.number().int().min(1).max(300).default(80),
+  depth: import_zod6.z.number().int().min(1).max(6).default(3),
+  returnPartial: import_zod6.z.boolean().default(true)
+});
+var AiOverviewLanguageInputSchema = import_zod6.z.object({
+  keyword: import_zod6.z.string().min(1),
+  domain: import_zod6.z.string().optional(),
+  url: import_zod6.z.string().url().optional(),
+  location: import_zod6.z.string().optional(),
+  maxQuestions: import_zod6.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod6.z.number().int().min(0).max(8).default(3),
+  returnPartial: import_zod6.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 mapLimit3(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,
+        background: false
+      }, 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 mapLimit3(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,
+  getLeadsWorkflowDefinition,
+  agentPacketWorkflowDefinition,
+  localCompetitiveAuditWorkflowDefinition,
+  mapComparisonWorkflowDefinition,
+  serpComparisonWorkflowDefinition,
+  paaExpansionBriefWorkflowDefinition,
+  aiOverviewLanguageWorkflowDefinition
+];
+function listWorkflowDefinitions() {
+  return DEFINITIONS.map(({ id, title, description }) => ({ id, title, description }));
+}
+function workflowDefinition(id) {
+  const definition = DEFINITIONS.find((def) => def.id === id);
+  if (!definition) throw new Error(`Unknown workflow "${id}". Available: ${DEFINITIONS.map((def) => def.id).join(", ")}`);
+  return definition;
+}
+function resolveApiKey(options) {
+  const apiKey = options.apiKey?.trim() || process.env.MCP_SCRAPER_API_KEY?.trim();
+  if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required for workflow runs. Pass --api-key or set the environment variable.");
+  return apiKey;
+}
+function resolveApiUrl(options) {
+  return options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
+}
+async function runWorkflow(id, rawInput, options = {}) {
+  const definition = workflowDefinition(id);
+  const input = definition.inputSchema.parse(rawInput);
+  const apiKey = resolveApiKey(options);
+  const apiUrl = resolveApiUrl(options);
+  const artifacts = await ArtifactWriter.create(definition.id, definition.title, input, options.outputDir, options.runId);
+  const client = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
+  const ctx = { runId: artifacts.runId, startedAt: artifacts.startedAt, client, artifacts, signal: options.signal };
+  try {
+    if (definition.steps && definition.steps.length > 0) {
+      let state = definition.createState ? definition.createState(input) : {};
+      let summary = null;
+      for (const step of definition.steps) {
+        const outcome = await step.run({ input, state, ctx });
+        state = outcome.state;
+        if (outcome.summary) summary = outcome.summary;
+      }
+      if (!summary) throw new Error(`Workflow "${id}" produced no terminal step summary`);
+      return summary;
+    }
+    if (definition.run) return await definition.run(input, ctx);
+    throw new Error(`Workflow "${id}" has neither steps nor a run() implementation`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    await artifacts.writeText("Failure", "summary.md", `# ${definition.title}
+
+${message}
+`);
+    await artifacts.writeManifest("failed", {}, [], [message]);
+    throw err;
+  }
+}
+
+// src/cli/human-cli.ts
+function numberOpt(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function booleanOpt(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return void 0;
+}
+function compactInput(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+function workflowInput(id, opts) {
+  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 === "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 ?? opts.maxResults),
+      concurrency: numberOpt(opts.concurrency),
+      proxyMode: opts.proxyMode,
+      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
+    });
+  }
+  return compactInput(opts);
+}
+function writeOutput(data, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  } else if (typeof data === "string") {
+    process.stdout.write(`${data}
+`);
+  } else {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  }
+}
+function maskSecrets(value) {
+  return value.replace(/sk_[A-Za-z0-9_-]+/g, "sk_***");
+}
+function runLocalCommand(command, args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process2.spawn)(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+    child.on("error", (err) => {
+      done({ code: 127, stdout: "", stderr: err.message });
+    });
+    child.on("close", (code) => {
+      done({
+        code: typeof code === "number" ? code : 1,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8")
+      });
+    });
+  });
+}
+function cadenceOpt(opts) {
+  if (opts.daily) return "daily";
+  if (opts.monthly) return "monthly";
+  return "weekly";
+}
+function apiOptions(opts) {
+  const apiKey = String(opts.apiKey ?? process.env.MCP_SCRAPER_API_KEY ?? "").trim();
+  if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required. Pass --api-key or set the environment variable.");
+  return {
+    apiUrl: String(opts.apiUrl ?? process.env.MCP_SCRAPER_API_URL ?? "https://mcpscraper.dev").replace(/\/$/, ""),
+    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}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey
+    },
+    body: body == null ? void 0 : JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = typeof data.error === "string" ? data.error : `API request failed with ${res.status}`;
+    throw new Error(message);
+  }
+  return data;
+}
+function addWorkflowInputOptions(command) {
+  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();
+  program.name("mcp-scraper-cli").description("Human CLI for MCP Scraper setup, workflows, reports, and agent-ready SEO artifacts.").version(PACKAGE_VERSION);
+  program.command("doctor").description("Check setup, API key, output directory, package version, and recommended MCP config.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--output-dir <path>", "Output directory to test").option("--json", "Print machine-readable JSON").action(async (opts) => {
+    const output = await runDoctor({ apiKey: opts.apiKey, apiUrl: opts.apiUrl, outputDir: opts.outputDir });
+    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);
+  });
+  billing.command("subscribe <tier>").description("Subscribe to a plan (starter | growth | scale) via a hosted Stripe checkout link.").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 (tier, opts) => {
+    const result = await apiRequest("/billing/subscribe/terminal-checkout", "POST", opts, { tier: String(tier).toLowerCase() });
+    if (opts.json) {
+      writeOutput(result, true);
+      return;
+    }
+    if (result.updated) {
+      writeOutput(result.message ?? `Switched to ${result.tier}.`, false);
+      return;
+    }
+    const opened = opts.open !== false && !!result.checkout_url && openExternalUrl(result.checkout_url);
+    const interval = result.billing_interval === "year" ? "year" : "month";
+    const amount = result.amount_usd ?? result.monthly_usd;
+    const credits = result.credits_per_interval ?? result.credits_per_month;
+    const perInterval = interval === "year" ? "/yr" : "/mo";
+    const creditsPer = interval === "year" ? "credits/yr" : "credits/mo";
+    const extras = [
+      result.credits_never_expire ? "credits never expire" : null,
+      result.includes_memory ? "includes Memory Pro" : null,
+      result.intro
+    ].filter(Boolean).join(" \xB7 ");
+    writeOutput([
+      `Plan: ${result.label ?? tier} \u2014 $${amount}${perInterval} \xB7 ${credits?.toLocaleString()} ${creditsPer} \xB7 ${result.concurrency} concurrency${extras ? ` \xB7 ${extras}` : ""}`,
+      opened ? `Opened checkout: ${result.checkout_url}` : `Checkout URL: ${result.checkout_url}`,
+      result.next_step ?? "Complete payment in the browser."
+    ].join("\n"), false);
+  });
+  const agent = program.command("agent").description("Generate AI-agent install configs and workflow prompts.");
+  agent.command("install <host>").description("Print or apply install/config instructions for codex, claude/claude-code, or claude-desktop.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--browser-profile <name>", "Default saved browser profile for browser_open sessions.").option("--save-browser-profile-changes", "Persist cookies and browser storage back to the named browser profile when sessions close").option("--apply", "Apply the config to this client when supported. For Claude Code, this upserts the user-scope mcp-scraper server.").option("--json", "Print machine-readable JSON").action(async (hostInput, opts) => {
+    const host = normalizeAgentHost(hostInput);
+    const apiKey = opts.apiKey ?? process.env.MCP_SCRAPER_API_KEY;
+    if (opts.apply) {
+      if (host !== "claude") throw new Error('--apply is currently supported for Claude Code only. Use host "claude" or "claude-code".');
+      if (!apiKey?.trim()) {
+        throw new Error("MCP_SCRAPER_API_KEY is required for --apply. Set it in the environment or pass --api-key.");
+      }
+      const configOptions = {
+        apiKey,
+        packageSpec: opts.package,
+        browserProfileName: opts.browserProfile,
+        browserProfileSaveChanges: opts.saveBrowserProfileChanges
+      };
+      const existing = await runLocalCommand("claude", claudeMcpGetArgs());
+      const snapshot = existing.code === 0 ? parseClaudeMcpGet(existing.stdout) : null;
+      const remove = await runLocalCommand("claude", claudeMcpRemoveArgs());
+      const add = await runLocalCommand("claude", claudeMcpAddArgs(configOptions));
+      if (add.code !== 0) {
+        const reason = maskSecrets([add.stderr, add.stdout].filter(Boolean).join("\n").trim());
+        let rollback;
+        if (remove.code !== 0) {
+          rollback = "No existing entry was removed, so your configuration is unchanged.";
+        } else if (!snapshot) {
+          rollback = "WARNING: the previous mcp-scraper entry was removed and could not be captured for rollback. Re-add it manually.";
+        } else {
+          const restore = await runLocalCommand("claude", claudeMcpRestoreArgs(snapshot));
+          rollback = restore.code === 0 ? "Your previous mcp-scraper entry was restored; nothing was lost." : "WARNING: the previous mcp-scraper entry was removed and could NOT be restored. Re-add it with:\n  claude " + claudeMcpRestoreArgs(snapshot).join(" ");
+        }
+        throw new Error([
+          "Claude Code MCP registration failed.",
+          reason || "No error output returned.",
+          rollback,
+          "Make sure Claude Code is installed and the `claude` command is on PATH."
+        ].join("\n"));
+      }
+      const list = await runLocalCommand("claude", ["mcp", "list"]);
+      const result = {
+        host: "claude",
+        applied: true,
+        replacedExisting: remove.code === 0,
+        command: "npx",
+        args: combinedNpxArgs(configOptions),
+        nextStep: "Fully exit Claude Code, start a new Claude terminal, then run: claude mcp list",
+        list: maskSecrets([list.stdout, list.stderr].filter(Boolean).join("\n").trim())
+      };
+      if (opts.json) {
+        writeOutput(result, true);
+        return;
+      }
+      writeOutput([
+        "Applied Claude Code MCP config: mcp-scraper",
+        remove.code === 0 ? "Replaced existing mcp-scraper entry." : "No existing mcp-scraper entry found; added a new one.",
+        "Command: npx " + combinedNpxArgs(configOptions).join(" "),
+        opts.browserProfile ? `Browser profile: ${opts.browserProfile}` : "",
+        "",
+        "Next step: fully exit Claude Code, start a new Claude terminal, then run:",
+        "  claude mcp list",
+        "",
+        result.list ? `Current Claude MCP list:
+${result.list}` : ""
+      ].filter(Boolean).join("\n"), false);
+      return;
+    }
+    const text = renderAgentInstall(host, {
+      apiKey: opts.apiKey,
+      packageSpec: opts.package,
+      browserProfileName: opts.browserProfile,
+      browserProfileSaveChanges: opts.saveBrowserProfileChanges
+    });
+    writeOutput(opts.json ? { host, text } : text, opts.json);
+  });
+  agent.command("prompt [name]").description("Print an agent prompt template.").option("--json", "Print machine-readable JSON").action((name, opts) => {
+    if (!name) {
+      writeOutput(opts.json ? { prompts: listPrompts() } : listPrompts().join("\n"), opts.json);
+      return;
+    }
+    const text = renderPrompt(name);
+    writeOutput(opts.json ? { name, text } : text, opts.json);
+  });
+  const workflow = program.command("workflow").description("Run named SEO workflows.");
+  workflow.command("list").description("List available workflows.").option("--json", "Print machine-readable JSON").action((opts) => {
+    const rows = listWorkflowDefinitions();
+    if (opts.json) writeOutput({ workflows: rows }, true);
+    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("--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,
+      outputDir: opts.outputDir
+    });
+    if (opts.json) writeOutput(summary, true);
+    else {
+      writeOutput([
+        `${summary.title}: ${summary.status}`,
+        summary.summary,
+        summary.reportPath ? `Report: ${summary.reportPath}` : "",
+        summary.warnings.length ? `Warnings:
+${summary.warnings.map((w) => `- ${w}`).join("\n")}` : ""
+      ].filter(Boolean).join("\n"), false);
+    }
+  });
+  const report = program.command("report").description("List and open local workflow reports.");
+  report.command("list").description("List recent workflow reports.").option("--output-dir <path>", "Workflow output directory").option("--json", "Print machine-readable JSON").action(async (opts) => {
+    const reports = await listWorkflowReports(opts.outputDir);
+    writeOutput(opts.json ? { reports } : reports.map((r) => `${r.startedAt}	${r.workflow}	${r.status}	${r.reportPath ?? r.manifestPath}`).join("\n"), opts.json);
+  });
+  report.command("path [id]").description("Print a report path. Defaults to last.").option("--output-dir <path>", "Workflow output directory").option("--json", "Print machine-readable JSON").action(async (id = "last", opts) => {
+    const found = await findWorkflowReport(id, opts.outputDir);
+    if (!found?.reportPath) throw new Error(`No report found for "${id}"`);
+    writeOutput(opts.json ? { path: found.reportPath, run: found } : found.reportPath, opts.json);
+  });
+  report.command("open [id]").description("Open a report. Defaults to last.").option("--output-dir <path>", "Workflow output directory").option("--json", "Print machine-readable JSON instead of opening").action(async (id = "last", opts) => {
+    if (opts.json) {
+      const found = await findWorkflowReport(id, opts.outputDir);
+      if (!found?.reportPath) throw new Error(`No report found for "${id}"`);
+      writeOutput({ path: found.reportPath, run: found }, true);
+      return;
+    }
+    const path = await openWorkflowReport(id, opts.outputDir);
+    writeOutput(`Opened: ${path}`, false);
+  });
+  const schedule = program.command("schedule").description("Create and manage hosted workflow schedules.");
+  addWorkflowInputOptions(schedule.command("create <workflowId>").description("Create a recurring hosted workflow schedule.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--name <name>", "Schedule name").option("--daily", "Run daily").option("--weekly", "Run weekly").option("--monthly", "Run monthly").option("--timezone <tz>", "Schedule timezone", "UTC").option("--webhook <url>", "HTTPS webhook URL").option("--next-run-at <iso>", "First run time as an ISO timestamp").option("--json", "Print machine-readable JSON")).action(async (workflowId, opts) => {
+    const result = await apiRequest("/workflows/schedules", "POST", opts, {
+      workflowId,
+      name: opts.name,
+      input: workflowInput(workflowId, opts),
+      cadence: cadenceOpt(opts),
+      timezone: opts.timezone,
+      webhookUrl: opts.webhook,
+      nextRunAt: opts.nextRunAt
+    });
+    writeOutput(result, opts.json);
+  });
+  schedule.command("list").description("List hosted workflow schedules.").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("/workflows/schedules", "GET", opts);
+    if (opts.json) writeOutput(result, true);
+    else writeOutput(result.schedules.map((scheduleRow) => `${scheduleRow.id}	${scheduleRow.status}	${scheduleRow.workflow_id}	${scheduleRow.next_run_at ?? ""}`).join("\n"), false);
+  });
+  schedule.command("pause <id>").description("Pause a hosted workflow schedule.").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 (id, opts) => writeOutput(await apiRequest(`/workflows/schedules/${id}`, "PATCH", opts, { status: "paused" }), opts.json));
+  schedule.command("resume <id>").description("Resume a hosted workflow schedule.").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 (id, opts) => writeOutput(await apiRequest(`/workflows/schedules/${id}`, "PATCH", opts, { status: "active" }), opts.json));
+  schedule.command("delete <id>").description("Delete a hosted workflow schedule.").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 (id, opts) => writeOutput(await apiRequest(`/workflows/schedules/${id}`, "DELETE", opts), opts.json));
+  schedule.command("run <id>").description("Run a hosted workflow schedule now.").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 (id, opts) => writeOutput(await apiRequest(`/workflows/schedules/${id}/run`, "POST", opts, {}), opts.json));
+  const runs = program.command("runs").description("Inspect and download hosted workflow runs.");
+  runs.command("list").description("List hosted workflow runs.").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("/workflows/runs", "GET", opts);
+    if (opts.json) writeOutput(result, true);
+    else writeOutput(result.runs.map((run) => `${run.id}	${run.status}	${run.workflow_id}	${run.queued_at}`).join("\n"), false);
+  });
+  runs.command("status <id>").description("Show a hosted workflow run.").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 (id, opts) => writeOutput(await apiRequest(`/workflows/runs/${id}`, "GET", opts), opts.json));
+  runs.command("download <id>").description("Download hosted workflow run artifacts.").option("--api-key <key>", "MCP Scraper API key").option("--api-url <url>", "MCP Scraper API URL", "https://mcpscraper.dev").option("--output-dir <path>", "Download directory").option("--json", "Print machine-readable JSON").action(async (id, opts) => {
+    const result = await apiRequest(`/workflows/runs/${id}`, "GET", opts);
+    const { apiUrl, apiKey } = apiOptions(opts);
+    const outDir = (0, import_node_path3.join)(opts.outputDir ?? workflowOutputBaseDir(), "workflow-downloads", id);
+    await (0, import_promises4.mkdir)(outDir, { recursive: true });
+    const downloaded = [];
+    for (const artifact of result.run.artifacts ?? []) {
+      const res = await fetch(`${apiUrl}/workflows/runs/${id}/artifacts/${artifact.id}`, { headers: { "x-api-key": apiKey } });
+      if (!res.ok) throw new Error(`Failed to download ${artifact.label}: HTTP ${res.status}`);
+      const file = (0, import_node_path3.join)(outDir, (0, import_node_path3.basename)(artifact.path));
+      await (0, import_promises4.writeFile)(file, Buffer.from(await res.arrayBuffer()));
+      downloaded.push(file);
+    }
+    writeOutput(opts.json ? { runId: id, files: downloaded } : downloaded.join("\n"), opts.json);
+  });
+  return program;
+}
+async function runHumanCli(argv = process.argv) {
+  await buildHumanCli().parseAsync(argv);
+}
+
+// bin/mcp-scraper-cli.ts
+runHumanCli().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
+//# sourceMappingURL=mcp-scraper-cli.cjs.map