mcp-scraper 0.2.19 → 0.2.21

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

@@ -4,11 +4,213 @@
 // src/cli/human-cli.ts
 var import_commander = require("commander");
 var import_node_child_process2 = require("child_process");
-var import_promises3 = require("fs/promises");
-var import_node_path3 = require("path");
+var import_promises6 = require("fs/promises");
+var import_node_path5 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.19";
+var PACKAGE_VERSION = "0.2.20";
+
+// src/lib/chrome-profiles.ts
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+function defaultChromeUserDataDir() {
+  if (process.platform === "darwin") return (0, import_node_path.join)((0, import_node_os.homedir)(), "Library", "Application Support", "Google", "Chrome");
+  if (process.platform === "win32") {
+    return (0, import_node_path.join)(process.env.LOCALAPPDATA ?? (0, import_node_path.join)((0, import_node_os.homedir)(), "AppData", "Local"), "Google", "Chrome", "User Data");
+  }
+  return (0, import_node_path.join)(process.env.XDG_CONFIG_HOME ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".config"), "google-chrome");
+}
+function recommendedKernelProfileName(value) {
+  return value.trim().toLowerCase().replace(/@/g, "-").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "browser-profile";
+}
+async function listLocalChromeProfiles(userDataDir = defaultChromeUserDataDir(), emailFilter) {
+  const raw = await (0, import_promises.readFile)((0, import_node_path.join)(userDataDir, "Local State"), "utf8");
+  const localState = JSON.parse(raw);
+  const wanted = emailFilter?.trim().toLowerCase();
+  return Object.entries(localState.profile?.info_cache ?? {}).map(([directory, info]) => {
+    const email = (info.user_name ?? "").trim();
+    const displayName = (info.name ?? info.shortcut_name ?? "").trim();
+    const labelSource = email || displayName || directory;
+    return {
+      email,
+      displayName,
+      chromeProfileDirectory: directory,
+      chromeProfilePath: (0, import_node_path.join)(userDataDir, directory),
+      recommendedKernelProfileName: recommendedKernelProfileName(labelSource)
+    };
+  }).filter((row) => !wanted || row.email.toLowerCase() === wanted || row.displayName.toLowerCase().includes(wanted));
+}
+
+// src/lib/local-browser-profiles.ts
+var import_node_fs = require("fs");
+var import_promises2 = require("fs/promises");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var EXCLUDED_PROFILE_NAMES = [
+  "Cache",
+  "Code Cache",
+  "Crashpad",
+  "DawnCache",
+  "DawnGraphiteCache",
+  "DawnWebGPUCache",
+  "GPUCache",
+  "GrShaderCache",
+  "ShaderCache",
+  "Shared Dictionary"
+];
+function defaultImportedBrowserProfilesDir() {
+  return process.env.MCP_SCRAPER_BROWSER_PROFILE_BASE_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".mcp-scraper", "browser-profiles");
+}
+function defaultChromeExecutablePath() {
+  const envPath = process.env.MCP_SCRAPER_BROWSER_EXECUTABLE?.trim() || process.env.CHROME_PATH?.trim();
+  if (envPath) return envPath;
+  const candidates = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"] : process.platform === "win32" ? [
+    (0, import_node_path2.join)(process.env.PROGRAMFILES ?? "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+    (0, import_node_path2.join)(process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", "Google", "Chrome", "Application", "chrome.exe")
+  ] : ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium-browser", "/usr/bin/chromium"];
+  return candidates.find((candidate) => (0, import_node_fs.existsSync)(candidate));
+}
+function importedProfileName(value) {
+  return recommendedKernelProfileName(value);
+}
+function importedProfileRoot(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(outputDir, importedProfileName(name));
+}
+function importedProfileManifestPath(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(importedProfileRoot(name, outputDir), "manifest.json");
+}
+function importedProfileUserDataDir(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(importedProfileRoot(name, outputDir), "user-data");
+}
+async function readExistingManifest(path) {
+  try {
+    return JSON.parse(await (0, import_promises2.readFile)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isExcludedProfilePath(sourceRoot, sourcePath) {
+  const rel = (0, import_node_path2.relative)(sourceRoot, sourcePath);
+  if (!rel) return false;
+  const parts = rel.split(import_node_path2.sep).filter(Boolean);
+  const last = parts[parts.length - 1] ?? "";
+  if (last.startsWith("Singleton")) return true;
+  if (last === "LOCK" || last.endsWith(".lock")) return true;
+  if (parts.some((part) => EXCLUDED_PROFILE_NAMES.includes(part))) return true;
+  if (parts.includes("Service Worker") && parts.includes("CacheStorage")) return true;
+  return false;
+}
+async function copyProfileTree(sourceProfilePath, destinationProfilePath) {
+  await (0, import_promises2.cp)(sourceProfilePath, destinationProfilePath, {
+    recursive: true,
+    force: true,
+    errorOnExist: false,
+    dereference: false,
+    filter: (source) => !isExcludedProfilePath(sourceProfilePath, source)
+  });
+}
+function selectProfile(profiles, options) {
+  const requestedDirectory = options.chromeProfileDirectory?.trim();
+  const requestedEmail = options.email?.trim().toLowerCase();
+  const exactDirectory = requestedDirectory ? profiles.find((profile) => profile.chromeProfileDirectory === requestedDirectory) : void 0;
+  if (exactDirectory) return exactDirectory;
+  const exactEmail = requestedEmail ? profiles.find((profile) => profile.email.toLowerCase() === requestedEmail) : void 0;
+  if (exactEmail) return exactEmail;
+  const first = profiles[0];
+  if (first) return first;
+  const hint = requestedDirectory ? `Chrome profile directory "${requestedDirectory}"` : requestedEmail ? `Chrome account "${requestedEmail}"` : "Chrome profile";
+  throw new Error(`${hint} was not found in ${options.sourceUserDataDir ?? defaultChromeUserDataDir()}`);
+}
+async function ensureProfilePathExists(profile) {
+  const details = await (0, import_promises2.stat)(profile.chromeProfilePath).catch(() => null);
+  if (!details?.isDirectory()) {
+    throw new Error(`Chrome profile path does not exist or is not a directory: ${profile.chromeProfilePath}`);
+  }
+}
+async function writeNormalizedLocalState(sourceLocalStatePath, destinationLocalStatePath, sourceProfileDirectory) {
+  const raw = await (0, import_promises2.readFile)(sourceLocalStatePath, "utf8");
+  const localState = JSON.parse(raw);
+  const selectedInfo = localState.profile?.info_cache?.[sourceProfileDirectory] ?? localState.profile?.info_cache?.Default ?? {};
+  localState.profile = {
+    ...localState.profile ?? {},
+    info_cache: { Default: selectedInfo },
+    last_used: "Default",
+    last_active_profiles: ["Default"]
+  };
+  await (0, import_promises2.writeFile)(destinationLocalStatePath, `${JSON.stringify(localState, null, 2)}
+`);
+}
+async function importChromeProfile(options = {}) {
+  const sourceUserDataDir = options.sourceUserDataDir?.trim() || defaultChromeUserDataDir();
+  const profiles = await listLocalChromeProfiles(sourceUserDataDir, options.email);
+  const sourceProfile = selectProfile(profiles, { ...options, sourceUserDataDir });
+  await ensureProfilePathExists(sourceProfile);
+  const name = importedProfileName(options.name?.trim() || sourceProfile.recommendedKernelProfileName);
+  const outputDir = options.outputDir?.trim() || defaultImportedBrowserProfilesDir();
+  const profileRoot = importedProfileRoot(name, outputDir);
+  const manifestPath = importedProfileManifestPath(name, outputDir);
+  const userDataDir = importedProfileUserDataDir(name, outputDir);
+  const existingManifest = await readExistingManifest(manifestPath);
+  const existing = (0, import_node_fs.existsSync)(profileRoot);
+  if (existing && !options.overwrite) {
+    throw new Error(`Imported browser profile "${name}" already exists at ${profileRoot}. Re-run with --overwrite to refresh it.`);
+  }
+  if (existing) await (0, import_promises2.rm)(profileRoot, { recursive: true, force: true });
+  await (0, import_promises2.mkdir)((0, import_node_path2.join)(userDataDir, "Default"), { recursive: true });
+  await writeNormalizedLocalState(
+    (0, import_node_path2.join)(sourceUserDataDir, "Local State"),
+    (0, import_node_path2.join)(userDataDir, "Local State"),
+    sourceProfile.chromeProfileDirectory
+  );
+  await copyProfileTree(sourceProfile.chromeProfilePath, (0, import_node_path2.join)(userDataDir, "Default"));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const manifest = {
+    layoutVersion: 1,
+    name,
+    profileRoot,
+    userDataDir,
+    browserExecutablePath: options.browserExecutablePath?.trim() || defaultChromeExecutablePath() || null,
+    sourceUserDataDir,
+    sourceProfileDirectory: sourceProfile.chromeProfileDirectory,
+    sourceProfilePath: sourceProfile.chromeProfilePath,
+    email: sourceProfile.email,
+    displayName: sourceProfile.displayName,
+    createdAt: existingManifest?.createdAt ?? now,
+    updatedAt: now,
+    copyMode: "chrome-profile-clone"
+  };
+  await (0, import_promises2.writeFile)(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  return {
+    profile: manifest,
+    sourceProfile,
+    excludedNames: EXCLUDED_PROFILE_NAMES
+  };
+}
+async function loadImportedBrowserProfile(name = process.env.MCP_SCRAPER_BROWSER_PROFILE?.trim() || "default", outputDir = defaultImportedBrowserProfilesDir()) {
+  const profileName = importedProfileName(name);
+  const manifestPath = importedProfileManifestPath(profileName, outputDir);
+  const manifest = await readExistingManifest(manifestPath);
+  if (!manifest) {
+    throw new Error(
+      `Imported browser profile "${profileName}" was not found. Run: mcp-scraper-cli browser import-chrome --name ${profileName}`
+    );
+  }
+  return manifest;
+}
+async function syncImportedChromeProfile(name, options = {}) {
+  const outputDir = options.outputDir?.trim() || defaultImportedBrowserProfilesDir();
+  const manifest = await loadImportedBrowserProfile(name, outputDir);
+  return importChromeProfile({
+    name: manifest.name,
+    sourceUserDataDir: manifest.sourceUserDataDir,
+    chromeProfileDirectory: manifest.sourceProfileDirectory,
+    outputDir,
+    overwrite: true,
+    browserExecutablePath: options.browserExecutablePath ?? manifest.browserExecutablePath ?? void 0
+  });
+}
 
 // src/cli/agent-config.ts
 function apiKeyValue(options) {
@@ -20,18 +222,37 @@ function packageSpec(options) {
 function combinedNpxArgs(options = {}) {
   return ["-y", "-p", packageSpec(options), "mcp-scraper-combined"];
 }
+function envConfig(options) {
+  const env = { MCP_SCRAPER_API_KEY: apiKeyValue(options) };
+  const profileName = options.browserProfileName?.trim();
+  if (options.browserMode === "local") {
+    env.MCP_SCRAPER_BROWSER_MODE = "local";
+    if (profileName) env.MCP_SCRAPER_BROWSER_PROFILE = profileName;
+    const executablePath = options.browserExecutablePath?.trim();
+    if (executablePath) env.MCP_SCRAPER_BROWSER_EXECUTABLE = executablePath;
+  } else {
+    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 = { MCP_SCRAPER_API_KEY = "${apiKeyValue(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 MCP_SCRAPER_API_KEY=${apiKeyValue(options)}`,
+    ...env,
     `  -- npx ${combinedNpxArgs(options).join(" ")}`
   ].join(" \\\n");
 }
@@ -41,9 +262,7 @@ function renderClaudeDesktopConfig(options = {}) {
       "mcp-scraper": {
         command: "npx",
         args: combinedNpxArgs(options),
-        env: {
-          MCP_SCRAPER_API_KEY: apiKeyValue(options)
-        }
+        env: envConfig(options)
       }
     }
   }, null, 2);
@@ -76,9 +295,9 @@ function renderAgentInstall(host, options = {}) {
 }
 
 // src/cli/doctor.ts
-var import_promises = require("fs/promises");
-var import_node_os = require("os");
-var import_node_path = require("path");
+var import_promises3 = require("fs/promises");
+var import_node_os3 = require("os");
+var import_node_path3 = require("path");
 function status(ok, warn = false) {
   if (ok) return "pass";
   return warn ? "warn" : "fail";
@@ -87,9 +306,9 @@ 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");
+  const path = process.env.MCP_SCRAPER_KEY_PATH?.trim() || (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".mcp-scraper-key");
   try {
-    const value = (await (0, import_promises.readFile)(path, "utf8")).trim();
+    const value = (await (0, import_promises3.readFile)(path, "utf8")).trim();
     return value || null;
   } catch {
     return null;
@@ -110,7 +329,7 @@ async function npmLatest(fetchImpl) {
 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 outputDir = options.outputDir ?? process.env.MCP_SCRAPER_OUTPUT_DIR ?? (0, import_node_path3.join)((0, import_node_os3.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 = [];
@@ -137,8 +356,8 @@ async function runDoctor(options = {}) {
     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);
+    await (0, import_promises3.mkdir)(outputDir, { recursive: true });
+    await (0, import_promises3.access)(outputDir);
     checks.push({ id: "output_dir", label: "Output directory", status: "pass", detail: outputDir });
   } catch (err) {
     checks.push({
@@ -284,10 +503,10 @@ function renderPrompt(name) {
 }
 
 // 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_promises4 = require("fs/promises");
+var import_node_fs2 = require("fs");
+var import_node_os4 = require("os");
+var import_node_path4 = require("path");
 var import_node_child_process = require("child_process");
 
 // src/directory/csv.ts
@@ -310,7 +529,7 @@ function slugify(s) {
 
 // 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");
+  return outputDir?.trim() || process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path4.join)((0, import_node_os4.homedir)(), "Downloads", "mcp-scraper");
 }
 function timestamp() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
@@ -341,31 +560,31 @@ var ArtifactWriter = class _ArtifactWriter {
     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 });
+    const runDir = (0, import_node_path4.join)(baseDir, "workflows", workflowId, `${timestamp()}-${safeSlug(nameSource)}-${safeSlug(runId).slice(0, 20)}`);
+    await (0, import_promises4.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);
+    const size = await (0, import_promises4.stat)(path).then((s) => s.size).catch(() => void 0);
     this.artifacts.push({ kind, label, path, bytes: size, rows });
     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");
+    const path = (0, import_node_path4.join)(this.runDir, relativePath);
+    await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+    await (0, import_promises4.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");
+    const path = (0, import_node_path4.join)(this.runDir, relativePath);
+    await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+    await (0, import_promises4.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");
+    const path = (0, import_node_path4.join)(this.runDir, relativePath);
+    await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+    await (0, import_promises4.writeFile)(path, rowsToCsv(headers, rows), "utf8");
     return this.remember("csv", label, path, rows.length);
   }
   async writeHtml(label, relativePath, html) {
@@ -385,20 +604,20 @@ var ArtifactWriter = class _ArtifactWriter {
       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");
+    const path = (0, import_node_path4.join)(this.runDir, "manifest.json");
+    await (0, import_promises4.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");
+  return (0, import_node_path4.join)(baseDir, "workflows", "index.json");
 }
 async function readIndex(baseDir) {
   const path = indexPath(baseDir);
-  if (!(0, import_node_fs.existsSync)(path)) return { runs: [] };
+  if (!(0, import_node_fs2.existsSync)(path)) return { runs: [] };
   try {
-    return JSON.parse(await (0, import_promises2.readFile)(path, "utf8"));
+    return JSON.parse(await (0, import_promises4.readFile)(path, "utf8"));
   } catch {
     return { runs: [] };
   }
@@ -418,8 +637,8 @@ async function updateWorkflowIndex(manifest, manifestPath, baseDir) {
     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");
+  await (0, import_promises4.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+  await (0, import_promises4.writeFile)(path, JSON.stringify(index, null, 2), "utf8");
 }
 async function listWorkflowReports(outputDir) {
   return (await readIndex(workflowOutputBaseDir(outputDir))).runs;
@@ -432,7 +651,7 @@ async function findWorkflowReport(id, outputDir) {
 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") {
+  if ((0, import_node_os4.platform)() === "darwin") {
     await new Promise((resolve, reject) => {
       (0, import_node_child_process.execFile)("open", [run.reportPath], (err) => err ? reject(err) : resolve());
     });
@@ -441,7 +660,8 @@ async function openWorkflowReport(id, outputDir) {
 }
 
 // src/workflows/registry.ts
-var import_zod5 = require("zod");
+var import_promises5 = require("fs/promises");
+var import_zod6 = require("zod");
 
 // src/workflows/http-client.ts
 var WorkflowHttpClient = class {
@@ -622,115 +842,254 @@ var agentPacketWorkflowDefinition = {
   title: "Agent-Ready SEO Packet",
   description: "Create an evidence folder for AI agents from live SERP/PAA/AI search surfaces.",
   inputSchema: AgentPacketInputSchema,
-  async run(input, ctx) {
-    await ctx.artifacts.writeManifest("running", {}, [], []);
-    const warnings = [];
-    const errors = [];
-    let serp = null;
-    let paa = null;
-    if (input.includeSerp) {
-      try {
-        serp = await ctx.client.post("/harvest/sync", {
-          query: input.keyword,
-          location: input.location,
-          serpOnly: true,
-          maxQuestions: 1,
-          format: "json"
-        }, 18e4);
-      } catch (err) {
-        warnings.push(`SERP evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  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] };
+        }
       }
-    }
-    if (input.includePaa) {
-      try {
-        paa = await ctx.client.post("/harvest/sync", {
-          query: input.keyword,
-          location: input.location,
-          maxQuestions: input.maxQuestions,
-          format: "json"
-        }, 28e4);
-      } catch (err) {
-        warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    },
+    {
+      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 }
+        };
       }
     }
-    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, errors);
-    return { 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 DirectoryWorkflowCliInputSchema = import_zod2.z.object({
+var DEFAULT_PROXY_MODE = "configured";
+var DEFAULT_MAPS_PROXY_MODE = "location";
+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(),
+  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)
+});
+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),
+  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),
-  state: import_zod2.z.string().min(2).default("TN"),
-  minPopulation: import_zod2.z.number().int().min(0).default(1e5),
-  maxCities: import_zod2.z.number().int().min(1).max(100).default(25),
-  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50).default(20),
-  concurrency: import_zod2.z.number().int().min(1).max(5).default(5),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location"),
-  saveCsv: import_zod2.z.boolean().default(true)
+  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),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).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(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  saveCsv: import_zod3.z.boolean().default(true)
 });
 function directoryRows(result) {
   const rows = [];
@@ -854,18 +1213,18 @@ ${summary}
 };
 
 // src/workflows/workflows/local-competitive-audit.ts
-var import_zod3 = require("zod");
-var LocalCompetitiveAuditInputSchema = 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),
-  hydrateTop: import_zod3.z.number().int().min(0).max(10).default(5),
-  maxReviews: import_zod3.z.number().int().min(0).max(500).default(50),
-  concurrency: import_zod3.z.number().int().min(1).max(5).default(5),
-  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default("location"),
-  returnPartial: import_zod3.z.boolean().default(true)
+var import_zod4 = require("zod");
+var LocalCompetitiveAuditInputSchema = import_zod4.z.object({
+  query: import_zod4.z.string().min(1),
+  state: import_zod4.z.string().min(2).default("TN"),
+  minPopulation: import_zod4.z.number().int().min(0).default(1e5),
+  maxCities: import_zod4.z.number().int().min(1).max(100).default(25),
+  maxResultsPerCity: import_zod4.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod4.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod4.z.number().int().min(0).max(500).default(50),
+  concurrency: import_zod4.z.number().int().min(1).max(5).default(5),
+  proxyMode: import_zod4.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod4.z.boolean().default(true)
 });
 async function mapLimit(items, limit, fn) {
   const out = new Array(items.length);
@@ -1053,7 +1412,7 @@ ${summary}
 };
 
 // src/workflows/workflows/comparison-briefs.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 
 // src/workflows/workflows/seo-workflow-utils.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
@@ -1211,49 +1570,49 @@ async function mapLimit2(items, limit, fn) {
 }
 
 // src/workflows/workflows/comparison-briefs.ts
-var ProxyModeSchema = import_zod4.z.enum(["location", "configured", "none"]);
-var MapComparisonInputSchema = import_zod4.z.object({
-  query: import_zod4.z.string().min(1),
-  location: import_zod4.z.string().optional(),
-  state: import_zod4.z.string().optional(),
-  minPopulation: import_zod4.z.number().int().min(0).default(1e5),
-  maxCities: import_zod4.z.number().int().min(1).max(100).default(5),
-  maxResultsPerCity: import_zod4.z.number().int().min(1).max(50).default(20),
-  hydrateTop: import_zod4.z.number().int().min(0).max(10).default(5),
-  maxReviews: import_zod4.z.number().int().min(0).max(500).default(25),
-  concurrency: import_zod4.z.number().int().min(1).max(5).default(5),
-  proxyMode: ProxyModeSchema.default("location"),
-  returnPartial: import_zod4.z.boolean().default(true)
+var ProxyModeSchema = import_zod5.z.enum(["location", "configured", "none"]);
+var MapComparisonInputSchema = import_zod5.z.object({
+  query: import_zod5.z.string().min(1),
+  location: import_zod5.z.string().optional(),
+  state: import_zod5.z.string().optional(),
+  minPopulation: import_zod5.z.number().int().min(0).default(1e5),
+  maxCities: import_zod5.z.number().int().min(1).max(100).default(5),
+  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(25),
+  concurrency: import_zod5.z.number().int().min(1).max(5).default(5),
+  proxyMode: ProxyModeSchema.default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod5.z.boolean().default(true)
 }).refine((input) => input.location || input.state, {
   message: "Either location or state is required for map-comparison"
 });
-var SerpComparisonInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  domain: import_zod4.z.string().optional(),
-  url: import_zod4.z.string().url().optional(),
-  location: import_zod4.z.string().optional(),
-  maxResults: import_zod4.z.number().int().min(1).max(20).default(10),
-  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
-  extractTop: import_zod4.z.number().int().min(0).max(10).default(5),
-  includePaa: import_zod4.z.boolean().default(true),
-  includeAiOverview: import_zod4.z.boolean().default(true),
-  returnPartial: import_zod4.z.boolean().default(true)
+var SerpComparisonInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  domain: import_zod5.z.string().optional(),
+  url: import_zod5.z.string().url().optional(),
+  location: import_zod5.z.string().optional(),
+  maxResults: import_zod5.z.number().int().min(1).max(20).default(10),
+  maxQuestions: import_zod5.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod5.z.number().int().min(0).max(10).default(5),
+  includePaa: import_zod5.z.boolean().default(true),
+  includeAiOverview: import_zod5.z.boolean().default(true),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
-var PaaExpansionBriefInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  location: import_zod4.z.string().optional(),
-  maxQuestions: import_zod4.z.number().int().min(1).max(300).default(80),
-  depth: import_zod4.z.number().int().min(1).max(6).default(3),
-  returnPartial: import_zod4.z.boolean().default(true)
+var PaaExpansionBriefInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  location: import_zod5.z.string().optional(),
+  maxQuestions: import_zod5.z.number().int().min(1).max(300).default(80),
+  depth: import_zod5.z.number().int().min(1).max(6).default(3),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
-var AiOverviewLanguageInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  domain: import_zod4.z.string().optional(),
-  url: import_zod4.z.string().url().optional(),
-  location: import_zod4.z.string().optional(),
-  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
-  extractTop: import_zod4.z.number().int().min(0).max(8).default(3),
-  returnPartial: import_zod4.z.boolean().default(true)
+var AiOverviewLanguageInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  domain: import_zod5.z.string().optional(),
+  url: import_zod5.z.string().url().optional(),
+  location: import_zod5.z.string().optional(),
+  maxQuestions: import_zod5.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod5.z.number().int().min(0).max(8).default(3),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
 function businessRowsFromMaps(location, query, results) {
   return results.map((result) => ({
@@ -1769,22 +2128,36 @@ function workflowDefinition(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 = 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.");
-  const apiUrl = options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
+  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 {
-    return await definition.run(input, {
-      runId: artifacts.runId,
-      startedAt: artifacts.startedAt,
-      client,
-      artifacts,
-      signal: options.signal
-    });
+    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}
@@ -1946,11 +2319,87 @@ function buildHumanCli() {
       result.next_step ?? "Complete checkout, then retry the MCP request."
     ].join("\n"), false);
   });
+  const browser = program.command("browser").description("Inspect and manage browser-agent profile setup helpers.");
+  browser.command("profiles").description("List local Chrome profiles and suggested managed browser profile names.").option("--email <email>", "Filter by Chrome account email or displayed profile name").option("--user-data-dir <path>", "Chrome user data directory").option("--json", "Print machine-readable JSON").action(async (opts) => {
+    const profiles = await listLocalChromeProfiles(opts.userDataDir, opts.email);
+    if (opts.json) {
+      writeOutput({ profiles }, true);
+      return;
+    }
+    if (!profiles.length) {
+      writeOutput("No matching Chrome profiles found.", false);
+      return;
+    }
+    const lines = [
+      "Local Chrome profiles:",
+      ...profiles.map((profile) => [
+        `${profile.email || "(no email)"}	${profile.chromeProfileDirectory}	${profile.displayName}`,
+        `  suggested profile name: ${profile.recommendedKernelProfileName}`,
+        `  local Chrome path: ${profile.chromeProfilePath}`
+      ].join("\n")),
+      "",
+      "To clone a real local Chrome profile for MCP local browser mode:",
+      "  mcp-scraper-cli browser import-chrome --email you@example.com --name <suggested profile name>",
+      "Then generate config with:",
+      "  mcp-scraper-cli agent install claude-desktop --browser-mode local --browser-profile <suggested profile name>"
+    ];
+    writeOutput(lines.join("\n"), false);
+  });
+  browser.command("import-chrome").description("Clone a local Chrome profile into MCP Scraper managed local browser storage.").option("--email <email>", "Chrome account email or displayed profile name to import").option("--name <name>", "Managed MCP Scraper browser profile name").option("--chrome-profile <directory>", "Chrome profile directory, for example Default or Profile 1").option("--user-data-dir <path>", "Source Chrome user data directory").option("--output-dir <path>", "Managed profile base directory").option("--browser-executable <path>", "Chrome executable path for local launches").option("--overwrite", "Overwrite an existing managed profile clone").option("--json", "Print machine-readable JSON").action(async (opts) => {
+    const result = await importChromeProfile({
+      email: opts.email,
+      name: opts.name,
+      chromeProfileDirectory: opts.chromeProfile,
+      sourceUserDataDir: opts.userDataDir,
+      outputDir: opts.outputDir,
+      browserExecutablePath: opts.browserExecutable,
+      overwrite: opts.overwrite
+    });
+    if (opts.json) {
+      writeOutput(result, true);
+      return;
+    }
+    writeOutput([
+      `Imported Chrome profile: ${result.profile.name}`,
+      `Source: ${result.sourceProfile.email || result.sourceProfile.displayName || result.sourceProfile.chromeProfileDirectory} (${result.sourceProfile.chromeProfileDirectory})`,
+      `Managed user data dir: ${result.profile.userDataDir}`,
+      "",
+      "Install/config command:",
+      `  mcp-scraper-cli agent install codex --browser-mode local --browser-profile ${result.profile.name}`,
+      "",
+      "Restart the MCP client after updating config. Re-run sync-profile after signing into new sites in normal Chrome."
+    ].join("\n"), false);
+  });
+  browser.command("sync-profile <name>").description("Refresh a managed local browser profile from its recorded source Chrome profile.").option("--output-dir <path>", "Managed profile base directory").option("--browser-executable <path>", "Chrome executable path for local launches").option("--json", "Print machine-readable JSON").action(async (name, opts) => {
+    const result = await syncImportedChromeProfile(name, {
+      outputDir: opts.outputDir,
+      browserExecutablePath: opts.browserExecutable
+    });
+    if (opts.json) {
+      writeOutput(result, true);
+      return;
+    }
+    writeOutput([
+      `Synced Chrome profile: ${result.profile.name}`,
+      `Source: ${result.sourceProfile.email || result.sourceProfile.displayName || result.sourceProfile.chromeProfileDirectory} (${result.sourceProfile.chromeProfileDirectory})`,
+      `Managed user data dir: ${result.profile.userDataDir}`,
+      "Restart any local browser sessions that were using this profile."
+    ].join("\n"), false);
+  });
   const agent = program.command("agent").description("Generate AI-agent install configs and workflow prompts.");
-  agent.command("install <host>").description("Print install/config instructions for codex, claude, or claude-desktop.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--json", "Print machine-readable JSON").action((host, opts) => {
+  agent.command("install <host>").description("Print install/config instructions for codex, claude, or claude-desktop.").option("--api-key <key>", "API key to place in generated config").option("--package <spec>", "npm package spec", "mcp-scraper@latest").option("--browser-mode <mode>", "Browser mode: hosted or local", "hosted").option("--browser-profile <name>", "Default browser profile for browser_open sessions. In local mode this is a managed MCP Scraper profile name; in hosted mode it is a Kernel profile name.").option("--browser-executable <path>", "Chrome executable path for local browser mode").option("--save-browser-profile-changes", "Persist cookies/local storage back to the named browser profile when sessions close").option("--json", "Print machine-readable JSON").action((host, opts) => {
     const valid = ["codex", "claude", "claude-desktop"];
     if (!valid.includes(host)) throw new Error(`Unknown host "${host}". Use: ${valid.join(", ")}`);
-    const text = renderAgentInstall(host, { apiKey: opts.apiKey, packageSpec: opts.package });
+    const browserMode = String(opts.browserMode ?? "hosted");
+    if (!["hosted", "local"].includes(browserMode)) throw new Error("Unknown browser mode. Use: hosted or local");
+    const text = renderAgentInstall(host, {
+      apiKey: opts.apiKey,
+      packageSpec: opts.package,
+      browserMode,
+      browserProfileName: opts.browserProfile,
+      browserProfileSaveChanges: opts.saveBrowserProfileChanges,
+      browserExecutablePath: opts.browserExecutable
+    });
     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) => {
@@ -2037,14 +2486,14 @@ ${summary.warnings.map((w) => `- ${w}`).join("\n")}` : ""
   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_promises3.mkdir)(outDir, { recursive: true });
+    const outDir = (0, import_node_path5.join)(opts.outputDir ?? workflowOutputBaseDir(), "workflow-downloads", id);
+    await (0, import_promises6.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_promises3.writeFile)(file, Buffer.from(await res.arrayBuffer()));
+      const file = (0, import_node_path5.join)(outDir, (0, import_node_path5.basename)(artifact.path));
+      await (0, import_promises6.writeFile)(file, Buffer.from(await res.arrayBuffer()));
       downloaded.push(file);
     }
     writeOutput(opts.json ? { runId: id, files: downloaded } : downloaded.join("\n"), opts.json);