mcp-scraper 0.2.19 → 0.2.20

package/dist/bin/api-server.cjs

@@ -4809,7 +4809,7 @@ function parsePageData(url, html, status, via) {
   }
   const h1 = headings.find((h) => h.level === 1)?.text ?? null;
   const bodyText = html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
-  const wordCount = bodyText.split(" ").filter((w) => w.length > 2).length;
+  const wordCount2 = bodyText.split(" ").filter((w) => w.length > 2).length;
   const schemaTypes = [];
   const schema = [];
   for (const m of html.matchAll(/<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
@@ -4845,7 +4845,7 @@ function parsePageData(url, html, status, via) {
     } catch {
     }
   }
-  return { url, status, via, title, metaDescription, h1, headings, wordCount, schemaTypes, canonicalUrl, internalLinks, externalLinks, bodyMarkdown, schema };
+  return { url, status, via, title, metaDescription, h1, headings, wordCount: wordCount2, schemaTypes, canonicalUrl, internalLinks, externalLinks, bodyMarkdown, schema };
 }
 async function fetchAndParse(url, kernelApiKey) {
   try {
@@ -6906,6 +6906,8 @@ var db_exports = {};
 __export(db_exports, {
   SiteAuditJobRowSchema: () => SiteAuditJobRowSchema,
   SiteAuditPhaseLogRowSchema: () => SiteAuditPhaseLogRowSchema,
+  advanceWorkflowRunStep: () => advanceWorkflowRunStep,
+  appendWorkflowArtifacts: () => appendWorkflowArtifacts,
   cancelJob: () => cancelJob,
   checkRateLimit: () => checkRateLimit,
   claimMonthlyFreeRefresh: () => claimMonthlyFreeRefresh,
@@ -6946,6 +6948,7 @@ __export(db_exports, {
   getWorkflowArtifact: () => getWorkflowArtifact,
   getWorkflowRun: () => getWorkflowRun,
   getWorkflowRunByIdempotencyKey: () => getWorkflowRunByIdempotencyKey,
+  getWorkflowRunStepState: () => getWorkflowRunStepState,
   getWorkflowSchedule: () => getWorkflowSchedule,
   hashPassword: () => hashPassword,
   ledgerExistsForOperation: () => ledgerExistsForOperation,
@@ -7227,9 +7230,34 @@ async function migrate() {
       queued_at       TEXT NOT NULL DEFAULT (datetime('now')),
       started_at      TEXT,
       completed_at    TEXT,
-      idempotency_key TEXT
+      idempotency_key TEXT,
+      step_index      INTEGER NOT NULL DEFAULT 0,
+      total_steps     INTEGER,
+      step_state_json TEXT,
+      step_log_json   TEXT,
+      webhook_url     TEXT
     )
   `);
+  try {
+    await db.execute(`ALTER TABLE workflow_runs ADD COLUMN step_index INTEGER NOT NULL DEFAULT 0`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE workflow_runs ADD COLUMN total_steps INTEGER`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE workflow_runs ADD COLUMN step_state_json TEXT`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE workflow_runs ADD COLUMN step_log_json TEXT`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE workflow_runs ADD COLUMN webhook_url TEXT`);
+  } catch {
+  }
   await db.execute(`CREATE INDEX IF NOT EXISTS workflow_runs_user_created ON workflow_runs(user_id, queued_at DESC)`);
   await db.execute(`CREATE INDEX IF NOT EXISTS workflow_runs_schedule ON workflow_runs(schedule_id, queued_at DESC)`);
   await db.execute(`CREATE UNIQUE INDEX IF NOT EXISTS workflow_runs_idempotency ON workflow_runs(idempotency_key) WHERE idempotency_key IS NOT NULL`);
@@ -7244,9 +7272,14 @@ async function migrate() {
       content_type TEXT NOT NULL,
       bytes        INTEGER,
       rows_count   INTEGER,
+      content      TEXT,
       created_at   TEXT NOT NULL DEFAULT (datetime('now'))
     )
   `);
+  try {
+    await db.execute(`ALTER TABLE workflow_artifacts ADD COLUMN content TEXT`);
+  } catch {
+  }
   await db.execute(`CREATE INDEX IF NOT EXISTS workflow_artifacts_run ON workflow_artifacts(run_id)`);
   await db.execute(`
     CREATE TABLE IF NOT EXISTS workflow_webhook_deliveries (
@@ -7692,9 +7725,22 @@ function rowToWorkflowRun(row) {
     queued_at: String(row.queued_at),
     started_at: row.started_at != null ? String(row.started_at) : null,
     completed_at: row.completed_at != null ? String(row.completed_at) : null,
-    idempotency_key: row.idempotency_key != null ? String(row.idempotency_key) : null
+    idempotency_key: row.idempotency_key != null ? String(row.idempotency_key) : null,
+    step_index: row.step_index != null ? Number(row.step_index) : 0,
+    total_steps: row.total_steps != null ? Number(row.total_steps) : null,
+    step_log: parseWorkflowStepLog(row.step_log_json),
+    webhook_url: row.webhook_url != null ? String(row.webhook_url) : null
   };
 }
+function parseWorkflowStepLog(value) {
+  if (value == null) return [];
+  try {
+    const parsed = JSON.parse(String(value));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
 function rowToWorkflowArtifact(row) {
   return {
     id: String(row.id),
@@ -7706,6 +7752,7 @@ function rowToWorkflowArtifact(row) {
     content_type: String(row.content_type),
     bytes: row.bytes != null ? Number(row.bytes) : null,
     rows_count: row.rows_count != null ? Number(row.rows_count) : null,
+    content: row.content != null ? String(row.content) : null,
     created_at: String(row.created_at)
   };
 }
@@ -7817,13 +7864,15 @@ async function createWorkflowRun(input) {
     input.scheduleId ?? null,
     input.workflowId,
     JSON.stringify(input.workflowInput),
-    input.idempotencyKey ?? null
+    input.idempotencyKey ?? null,
+    input.webhookUrl ?? null,
+    input.totalSteps ?? null
   ];
   try {
     await getDb().execute({
       sql: `
-        INSERT INTO workflow_runs (id, user_id, schedule_id, workflow_id, input_json, idempotency_key)
-        VALUES (?, ?, ?, ?, ?, ?)
+        INSERT INTO workflow_runs (id, user_id, schedule_id, workflow_id, input_json, idempotency_key, webhook_url, total_steps)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
       `,
       args
     });
@@ -7877,30 +7926,53 @@ function workflowArtifactContentType(kind) {
   if (kind === "json") return "application/json; charset=utf-8";
   return "text/plain; charset=utf-8";
 }
+async function insertWorkflowArtifact(runId, userId, artifact) {
+  await getDb().execute({
+    sql: `
+      INSERT INTO workflow_artifacts (id, run_id, user_id, kind, label, path, content_type, bytes, rows_count, content)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    args: [
+      (0, import_node_crypto.randomUUID)(),
+      runId,
+      userId,
+      artifact.kind,
+      artifact.label,
+      artifact.path,
+      workflowArtifactContentType(artifact.kind),
+      artifact.bytes ?? null,
+      artifact.rows ?? null,
+      artifact.content ?? null
+    ]
+  });
+}
 async function replaceWorkflowArtifacts(runId, userId, artifacts) {
-  const db = getDb();
-  await db.execute({ sql: "DELETE FROM workflow_artifacts WHERE run_id = ? AND user_id = ?", args: [runId, userId] });
-  for (const artifact of artifacts) {
-    await db.execute({
-      sql: `
-        INSERT INTO workflow_artifacts (id, run_id, user_id, kind, label, path, content_type, bytes, rows_count)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `,
-      args: [
-        (0, import_node_crypto.randomUUID)(),
-        runId,
-        userId,
-        artifact.kind,
-        artifact.label,
-        artifact.path,
-        workflowArtifactContentType(artifact.kind),
-        artifact.bytes ?? null,
-        artifact.rows ?? null
-      ]
-    });
-  }
+  await getDb().execute({ sql: "DELETE FROM workflow_artifacts WHERE run_id = ? AND user_id = ?", args: [runId, userId] });
+  for (const artifact of artifacts) await insertWorkflowArtifact(runId, userId, artifact);
   return listWorkflowArtifacts(runId, userId);
 }
+async function appendWorkflowArtifacts(runId, userId, artifacts) {
+  for (const artifact of artifacts) await insertWorkflowArtifact(runId, userId, artifact);
+  return listWorkflowArtifacts(runId, userId);
+}
+async function getWorkflowRunStepState(id, userId) {
+  const res = userId == null ? await getDb().execute({ sql: "SELECT step_index, total_steps, step_state_json, step_log_json FROM workflow_runs WHERE id = ? LIMIT 1", args: [id] }) : await getDb().execute({ sql: "SELECT step_index, total_steps, step_state_json, step_log_json FROM workflow_runs WHERE id = ? AND user_id = ? LIMIT 1", args: [id, userId] });
+  const row = res.rows[0];
+  if (!row) return null;
+  return {
+    stepIndex: row.step_index != null ? Number(row.step_index) : 0,
+    totalSteps: row.total_steps != null ? Number(row.total_steps) : null,
+    state: row.step_state_json != null ? parseNullableJson(row.step_state_json) : null,
+    stepLog: parseWorkflowStepLog(row.step_log_json)
+  };
+}
+async function advanceWorkflowRunStep(id, input) {
+  const stepLog = [...input.appendLog, input.logEntry];
+  await getDb().execute({
+    sql: `UPDATE workflow_runs SET status = ?, step_index = ?, total_steps = ?, step_state_json = ?, step_log_json = ?, started_at = COALESCE(started_at, datetime('now')) WHERE id = ?`,
+    args: [input.status, input.stepIndex, input.totalSteps, JSON.stringify(input.state ?? null), JSON.stringify(stepLog), id]
+  });
+}
 async function listWorkflowArtifacts(runId, userId) {
   const res = await getDb().execute({
     sql: "SELECT * FROM workflow_artifacts WHERE run_id = ? AND user_id = ? ORDER BY created_at ASC",
@@ -8909,6 +8981,7 @@ var init_schemas2 = __esm({
       downloadMp3: import_zod12.z.boolean().default(false),
       outputDir: import_zod12.z.string().default("./yt-output"),
       kernelApiKey: import_zod12.z.string().optional(),
+      kernelProxyId: import_zod12.z.string().optional(),
       headless: import_zod12.z.boolean().default(false)
     }).refine(
       (o) => o.mode === "search" ? !!o.query : !!o.channelHandle,
@@ -9833,6 +9906,7 @@ var init_YouTubeExtractor = __esm({
         const config = {
           headless: options.headless,
           kernelApiKey: options.kernelApiKey,
+          kernelProxyId: options.kernelProxyId,
           viewport: { width: 1280, height: 800 },
           locale: "en-US"
         };
@@ -10044,7 +10118,11 @@ async function ytHarvest(rawOptions) {
     throw new Error("A browser backend API key is required \u2014 YouTube harvesting requires a stealth session.");
   }
   const raw = typeof rawOptions === "object" && rawOptions !== null ? rawOptions : {};
-  const options = YouTubeHarvestOptionsSchema.parse({ kernelApiKey, ...raw });
+  const options = YouTubeHarvestOptionsSchema.parse({
+    kernelApiKey,
+    kernelProxyId: browserServiceProxyId(),
+    ...raw
+  });
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
     try {
       const result = await extractOnce(options);
@@ -10153,10 +10231,11 @@ function parseTimedtextXml(xml) {
 async function fetchViaKernelInnertube(videoId) {
   const kernelApiKey = browserServiceApiKey();
   if (!kernelApiKey) return null;
+  const kernelProxyId = browserServiceProxyId();
   const driver = new BrowserDriver();
   const start = Date.now();
   try {
-    await driver.launch({ kernelApiKey, headless: true, viewport: { width: 1280, height: 800 }, locale: "en-US" });
+    await driver.launch({ kernelApiKey, kernelProxyId, headless: true, viewport: { width: 1280, height: 800 }, locale: "en-US" });
     const page = driver.getPage();
     await driver.navigateTo(`https://www.youtube.com/watch?v=${videoId}`);
     await page.waitForFunction(
@@ -10250,10 +10329,10 @@ async function captureAudioViaMediaRecorder(page) {
   if (!result.ok || !result.base64 || !result.mimeType) return null;
   return { bytes: Buffer.from(result.base64, "base64"), mimeType: result.mimeType };
 }
-async function attemptKernelWhisper(videoId, kernelApiKey, falKey, start) {
+async function attemptKernelWhisper(videoId, kernelApiKey, kernelProxyId, falKey, start) {
   const driver = new BrowserDriver();
   try {
-    await driver.launch({ kernelApiKey, headless: true, viewport: { width: 1280, height: 800 }, locale: "en-US" });
+    await driver.launch({ kernelApiKey, kernelProxyId, headless: true, viewport: { width: 1280, height: 800 }, locale: "en-US" });
     const page = driver.getPage();
     await driver.navigateTo(`https://www.youtube.com/watch?v=${videoId}`);
     await page.waitForFunction(
@@ -10295,12 +10374,13 @@ async function attemptKernelWhisper(videoId, kernelApiKey, falKey, start) {
 }
 async function fetchViaKernelWhisper(videoId) {
   const kernelApiKey = browserServiceApiKey();
+  const kernelProxyId = browserServiceProxyId();
   const falKey = process.env.FAL_KEY;
   if (!kernelApiKey || !falKey) return null;
   const start = Date.now();
   for (let attempt = 0; attempt < 4; attempt++) {
     if (attempt > 0) await new Promise((r) => setTimeout(r, 2e3 * attempt));
-    const result = await attemptKernelWhisper(videoId, kernelApiKey, falKey, start);
+    const result = await attemptKernelWhisper(videoId, kernelApiKey, kernelProxyId, falKey, start);
     if (result) return result;
   }
   return null;
@@ -12283,6 +12363,110 @@ var init_kernel_proxy_resolver = __esm({
   }
 });
 
+// src/schemas.ts
+var import_zod15, DEFAULT_PROXY_MODE, DEFAULT_MAPS_PROXY_MODE, HarvestOptionsSchema, MapsPlaceOptionsSchema, MapsSearchOptionsSchema, RawPAAItemSchema, RawMapsOverviewSchema, RawMapsHoursRowSchema, RawMapsReviewStatsSchema, RawMapsReviewCardSchema, RawMapsAboutAttributeSchema;
+var init_schemas3 = __esm({
+  "src/schemas.ts"() {
+    "use strict";
+    import_zod15 = require("zod");
+    DEFAULT_PROXY_MODE = "configured";
+    DEFAULT_MAPS_PROXY_MODE = "location";
+    HarvestOptionsSchema = import_zod15.z.object({
+      query: import_zod15.z.string().min(1),
+      location: import_zod15.z.string().optional(),
+      gl: import_zod15.z.string().length(2).default("us"),
+      hl: import_zod15.z.string().length(2).default("en"),
+      device: import_zod15.z.enum(["desktop", "mobile"]).default("desktop"),
+      proxyMode: import_zod15.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE),
+      proxyZip: import_zod15.z.string().regex(/^\d{5}$/).optional(),
+      debug: import_zod15.z.boolean().default(false),
+      depth: import_zod15.z.number().int().min(1).max(30).default(3),
+      maxQuestions: import_zod15.z.number().int().min(1).max(1e3).default(100),
+      headless: import_zod15.z.boolean().default(false),
+      profileDir: import_zod15.z.string().optional(),
+      proxy: import_zod15.z.string().url().optional(),
+      kernelApiKey: import_zod15.z.string().optional(),
+      kernelProxyId: import_zod15.z.string().optional(),
+      kernelProxyResolution: import_zod15.z.unknown().optional(),
+      outputDir: import_zod15.z.string().default("./paa-output"),
+      format: import_zod15.z.enum(["json", "csv", "both"]).default("both"),
+      serpOnly: import_zod15.z.boolean().default(false),
+      pages: import_zod15.z.number().int().min(1).max(2).default(1)
+    });
+    MapsPlaceOptionsSchema = import_zod15.z.object({
+      businessName: import_zod15.z.string().min(1),
+      location: import_zod15.z.string().min(1),
+      gl: import_zod15.z.string().length(2).default("us"),
+      hl: import_zod15.z.string().length(2).default("en"),
+      includeReviews: import_zod15.z.boolean().default(false),
+      maxReviews: import_zod15.z.number().int().min(1).max(500).default(50),
+      kernelApiKey: import_zod15.z.string().optional(),
+      kernelProxyId: import_zod15.z.string().optional(),
+      headless: import_zod15.z.boolean().default(true)
+    });
+    MapsSearchOptionsSchema = import_zod15.z.object({
+      query: import_zod15.z.string().min(1),
+      location: import_zod15.z.string().optional(),
+      gl: import_zod15.z.string().length(2).default("us"),
+      hl: import_zod15.z.string().length(2).default("en"),
+      maxResults: import_zod15.z.number().int().min(1).max(50).default(10),
+      proxyMode: import_zod15.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+      proxyZip: import_zod15.z.string().regex(/^\d{5}$/).optional(),
+      debug: import_zod15.z.boolean().default(false),
+      kernelApiKey: import_zod15.z.string().optional(),
+      kernelProxyId: import_zod15.z.string().optional(),
+      kernelProxyResolution: import_zod15.z.unknown().optional(),
+      headless: import_zod15.z.boolean().default(true)
+    });
+    RawPAAItemSchema = import_zod15.z.object({
+      question: import_zod15.z.string().min(1),
+      answer: import_zod15.z.string().optional(),
+      sourceTitle: import_zod15.z.string().optional(),
+      sourceSite: import_zod15.z.string().optional(),
+      sourceCite: import_zod15.z.string().optional()
+    });
+    RawMapsOverviewSchema = import_zod15.z.object({
+      name: import_zod15.z.string().nullable(),
+      rating: import_zod15.z.string().nullable(),
+      reviewCount: import_zod15.z.string().nullable(),
+      category: import_zod15.z.string().nullable(),
+      address: import_zod15.z.string().nullable(),
+      hoursSummary: import_zod15.z.string().nullable(),
+      phone: import_zod15.z.string().nullable(),
+      phoneDisplay: import_zod15.z.string().nullable(),
+      website: import_zod15.z.string().nullable(),
+      plusCode: import_zod15.z.string().nullable(),
+      bookingUrl: import_zod15.z.string().nullable()
+    });
+    RawMapsHoursRowSchema = import_zod15.z.object({
+      day: import_zod15.z.string(),
+      hours: import_zod15.z.string()
+    });
+    RawMapsReviewStatsSchema = import_zod15.z.object({
+      reviewHistogram: import_zod15.z.array(import_zod15.z.object({
+        stars: import_zod15.z.number(),
+        count: import_zod15.z.string()
+      })),
+      reviewTopics: import_zod15.z.array(import_zod15.z.object({
+        label: import_zod15.z.string(),
+        count: import_zod15.z.string()
+      }))
+    });
+    RawMapsReviewCardSchema = import_zod15.z.object({
+      reviewId: import_zod15.z.string(),
+      author: import_zod15.z.string().nullable(),
+      stars: import_zod15.z.string().nullable(),
+      date: import_zod15.z.string().nullable(),
+      text: import_zod15.z.string().nullable(),
+      ownerResponse: import_zod15.z.string().nullable()
+    });
+    RawMapsAboutAttributeSchema = import_zod15.z.object({
+      section: import_zod15.z.string(),
+      attribute: import_zod15.z.string()
+    });
+  }
+});
+
 // src/api/facebook-ad-routes.ts
 function invalidRequest(message) {
   return { error_code: "invalid_request", message };
@@ -12338,9 +12522,8 @@ async function kernelLaunchOptsResidential() {
   try {
     const resolution2 = await resolveKernelProxyId({
       kernelApiKey: browserServiceApiKey(),
-      proxyMode: "location",
+      proxyMode: DEFAULT_PROXY_MODE,
       configuredKernelProxyId: browserServiceProxyId(),
-      location: "New York, NY",
       gl: "us"
     });
     if (resolution2.kernelProxyId) proxyId = resolution2.kernelProxyId;
@@ -12349,13 +12532,13 @@ async function kernelLaunchOptsResidential() {
   }
   return { headless: true, kernelApiKey: browserServiceApiKey(), kernelProxyId: proxyId, viewport: { width: 1280, height: 900 }, locale: "en-US" };
 }
-var import_hono4, import_zod15, import_client3, FacebookAdBodySchema, FacebookPageIntelBodySchema, FacebookTranscribeBodySchema, FacebookVideoTranscribeBodySchema, FacebookSearchBodySchema, FacebookMediaBodySchema, facebookAdApp, ALLOWED_MEDIA_HOSTS;
+var import_hono4, import_zod16, import_client3, FacebookAdBodySchema, FacebookPageIntelBodySchema, FacebookTranscribeBodySchema, FacebookVideoTranscribeBodySchema, FacebookSearchBodySchema, FacebookMediaBodySchema, facebookAdApp, ALLOWED_MEDIA_HOSTS;
 var init_facebook_ad_routes = __esm({
   "src/api/facebook-ad-routes.ts"() {
     "use strict";
     import_hono4 = require("hono");
     init_browser_service_env();
-    import_zod15 = require("zod");
+    import_zod16 = require("zod");
     init_db();
     init_rates();
     init_BrowserDriver();
@@ -12363,39 +12546,40 @@ var init_facebook_ad_routes = __esm({
     init_FacebookAdGraphql();
     init_FacebookOrganicVideoExtractor();
     init_kernel_proxy_resolver();
+    init_schemas3();
     import_client3 = require("@fal-ai/client");
     init_api_auth();
     init_url_utils();
     init_concurrency_gates();
-    FacebookAdBodySchema = import_zod15.z.object({
-      url: import_zod15.z.string().trim().optional(),
-      libraryId: import_zod15.z.string().trim().optional(),
-      openModal: import_zod15.z.boolean().optional()
+    FacebookAdBodySchema = import_zod16.z.object({
+      url: import_zod16.z.string().trim().optional(),
+      libraryId: import_zod16.z.string().trim().optional(),
+      openModal: import_zod16.z.boolean().optional()
     }).refine((d) => !!d.url || !!d.libraryId, { message: "url or libraryId is required" });
-    FacebookPageIntelBodySchema = import_zod15.z.object({
-      pageId: import_zod15.z.string().trim().optional(),
-      query: import_zod15.z.string().trim().optional(),
-      libraryId: import_zod15.z.string().trim().optional(),
-      maxAds: import_zod15.z.number().int().min(1).max(200).optional(),
-      country: import_zod15.z.string().trim().toUpperCase().optional()
+    FacebookPageIntelBodySchema = import_zod16.z.object({
+      pageId: import_zod16.z.string().trim().optional(),
+      query: import_zod16.z.string().trim().optional(),
+      libraryId: import_zod16.z.string().trim().optional(),
+      maxAds: import_zod16.z.number().int().min(1).max(200).optional(),
+      country: import_zod16.z.string().trim().toUpperCase().optional()
     }).refine((d) => !!d.pageId || !!d.query || !!d.libraryId, {
       message: "pageId, libraryId, or query is required"
     });
-    FacebookTranscribeBodySchema = import_zod15.z.object({
-      videoUrl: import_zod15.z.string().trim().min(1, "videoUrl is required")
+    FacebookTranscribeBodySchema = import_zod16.z.object({
+      videoUrl: import_zod16.z.string().trim().min(1, "videoUrl is required")
     });
-    FacebookVideoTranscribeBodySchema = import_zod15.z.object({
-      url: import_zod15.z.string().trim().min(1, "url is required"),
-      quality: import_zod15.z.enum(["best", "hd", "sd"]).default("best")
+    FacebookVideoTranscribeBodySchema = import_zod16.z.object({
+      url: import_zod16.z.string().trim().min(1, "url is required"),
+      quality: import_zod16.z.enum(["best", "hd", "sd"]).default("best")
     });
-    FacebookSearchBodySchema = import_zod15.z.object({
-      query: import_zod15.z.string().trim().min(1, "query is required"),
-      country: import_zod15.z.string().trim().toUpperCase().optional(),
-      maxResults: import_zod15.z.number().int().min(1).max(20).optional()
+    FacebookSearchBodySchema = import_zod16.z.object({
+      query: import_zod16.z.string().trim().min(1, "query is required"),
+      country: import_zod16.z.string().trim().toUpperCase().optional(),
+      maxResults: import_zod16.z.number().int().min(1).max(20).optional()
     });
-    FacebookMediaBodySchema = import_zod15.z.object({
-      url: import_zod15.z.string().trim().min(1, "url is required"),
-      filename: import_zod15.z.string().trim().optional()
+    FacebookMediaBodySchema = import_zod16.z.object({
+      url: import_zod16.z.string().trim().min(1, "url is required"),
+      filename: import_zod16.z.string().trim().optional()
     });
     facebookAdApp = new import_hono4.Hono();
     facebookAdApp.post("/ad", createApiKeyAuth(), async (c) => {
@@ -12721,108 +12905,6 @@ var init_facebook_ad_routes = __esm({
   }
 });
 
-// src/schemas.ts
-var import_zod16, HarvestOptionsSchema, MapsPlaceOptionsSchema, MapsSearchOptionsSchema, RawPAAItemSchema, RawMapsOverviewSchema, RawMapsHoursRowSchema, RawMapsReviewStatsSchema, RawMapsReviewCardSchema, RawMapsAboutAttributeSchema;
-var init_schemas3 = __esm({
-  "src/schemas.ts"() {
-    "use strict";
-    import_zod16 = require("zod");
-    HarvestOptionsSchema = import_zod16.z.object({
-      query: import_zod16.z.string().min(1),
-      location: import_zod16.z.string().optional(),
-      gl: import_zod16.z.string().length(2).default("us"),
-      hl: import_zod16.z.string().length(2).default("en"),
-      device: import_zod16.z.enum(["desktop", "mobile"]).default("desktop"),
-      proxyMode: import_zod16.z.enum(["location", "configured", "none"]).default("location"),
-      proxyZip: import_zod16.z.string().regex(/^\d{5}$/).optional(),
-      debug: import_zod16.z.boolean().default(false),
-      depth: import_zod16.z.number().int().min(1).max(30).default(3),
-      maxQuestions: import_zod16.z.number().int().min(1).max(1e3).default(100),
-      headless: import_zod16.z.boolean().default(false),
-      profileDir: import_zod16.z.string().optional(),
-      proxy: import_zod16.z.string().url().optional(),
-      kernelApiKey: import_zod16.z.string().optional(),
-      kernelProxyId: import_zod16.z.string().optional(),
-      kernelProxyResolution: import_zod16.z.unknown().optional(),
-      outputDir: import_zod16.z.string().default("./paa-output"),
-      format: import_zod16.z.enum(["json", "csv", "both"]).default("both"),
-      serpOnly: import_zod16.z.boolean().default(false),
-      pages: import_zod16.z.number().int().min(1).max(2).default(1)
-    });
-    MapsPlaceOptionsSchema = import_zod16.z.object({
-      businessName: import_zod16.z.string().min(1),
-      location: import_zod16.z.string().min(1),
-      gl: import_zod16.z.string().length(2).default("us"),
-      hl: import_zod16.z.string().length(2).default("en"),
-      includeReviews: import_zod16.z.boolean().default(false),
-      maxReviews: import_zod16.z.number().int().min(1).max(500).default(50),
-      kernelApiKey: import_zod16.z.string().optional(),
-      kernelProxyId: import_zod16.z.string().optional(),
-      headless: import_zod16.z.boolean().default(true)
-    });
-    MapsSearchOptionsSchema = import_zod16.z.object({
-      query: import_zod16.z.string().min(1),
-      location: import_zod16.z.string().optional(),
-      gl: import_zod16.z.string().length(2).default("us"),
-      hl: import_zod16.z.string().length(2).default("en"),
-      maxResults: import_zod16.z.number().int().min(1).max(50).default(10),
-      proxyMode: import_zod16.z.enum(["location", "configured", "none"]).default("location"),
-      proxyZip: import_zod16.z.string().regex(/^\d{5}$/).optional(),
-      debug: import_zod16.z.boolean().default(false),
-      kernelApiKey: import_zod16.z.string().optional(),
-      kernelProxyId: import_zod16.z.string().optional(),
-      kernelProxyResolution: import_zod16.z.unknown().optional(),
-      headless: import_zod16.z.boolean().default(true)
-    });
-    RawPAAItemSchema = import_zod16.z.object({
-      question: import_zod16.z.string().min(1),
-      answer: import_zod16.z.string().optional(),
-      sourceTitle: import_zod16.z.string().optional(),
-      sourceSite: import_zod16.z.string().optional(),
-      sourceCite: import_zod16.z.string().optional()
-    });
-    RawMapsOverviewSchema = import_zod16.z.object({
-      name: import_zod16.z.string().nullable(),
-      rating: import_zod16.z.string().nullable(),
-      reviewCount: import_zod16.z.string().nullable(),
-      category: import_zod16.z.string().nullable(),
-      address: import_zod16.z.string().nullable(),
-      hoursSummary: import_zod16.z.string().nullable(),
-      phone: import_zod16.z.string().nullable(),
-      phoneDisplay: import_zod16.z.string().nullable(),
-      website: import_zod16.z.string().nullable(),
-      plusCode: import_zod16.z.string().nullable(),
-      bookingUrl: import_zod16.z.string().nullable()
-    });
-    RawMapsHoursRowSchema = import_zod16.z.object({
-      day: import_zod16.z.string(),
-      hours: import_zod16.z.string()
-    });
-    RawMapsReviewStatsSchema = import_zod16.z.object({
-      reviewHistogram: import_zod16.z.array(import_zod16.z.object({
-        stars: import_zod16.z.number(),
-        count: import_zod16.z.string()
-      })),
-      reviewTopics: import_zod16.z.array(import_zod16.z.object({
-        label: import_zod16.z.string(),
-        count: import_zod16.z.string()
-      }))
-    });
-    RawMapsReviewCardSchema = import_zod16.z.object({
-      reviewId: import_zod16.z.string(),
-      author: import_zod16.z.string().nullable(),
-      stars: import_zod16.z.string().nullable(),
-      date: import_zod16.z.string().nullable(),
-      text: import_zod16.z.string().nullable(),
-      ownerResponse: import_zod16.z.string().nullable()
-    });
-    RawMapsAboutAttributeSchema = import_zod16.z.object({
-      section: import_zod16.z.string(),
-      attribute: import_zod16.z.string()
-    });
-  }
-});
-
 // src/extractor/MapsNavigator.ts
 var MapsNavigator;
 var init_MapsNavigator = __esm({
@@ -14432,13 +14514,25 @@ ${videoRows}`,
     }
   };
 }
+function structuredTranscriptChunks(chunks) {
+  return chunks.map((c) => ({
+    startSec: Number.isFinite(c.timestamp?.[0]) ? c.timestamp[0] : 0,
+    endSec: Number.isFinite(c.timestamp?.[1]) ? c.timestamp[1] : 0,
+    text: c.text
+  }));
+}
+function wordCount(text) {
+  return text.trim() ? text.trim().split(/\s+/).length : 0;
+}
 function formatYoutubeTranscribe(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
+  const videoId = d.videoId ?? input.videoId ?? null;
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const words = wordCount(text);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -14446,8 +14540,8 @@ function formatYoutubeTranscribe(raw, input) {
     return `| ${mm}:${ss} | ${cell(truncate(c.text, 120))} |`;
   }).join("\n");
   const full = [
-    `# YouTube Transcript: \`${input.videoId}\``,
-    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `# YouTube Transcript: \`${videoId ?? input.url ?? "video"}\``,
+    `**Duration:** ${durSec}s \xB7 **${words} words**`,
     `
 ## Full Transcript
 ${text}`,
@@ -14460,7 +14554,22 @@ ${chunkRows}` : "",
 ---
 \u{1F4A1} Harvest more from this channel: use \`youtube_harvest\` with \`mode: "channel"\``
   ].filter(Boolean).join("\n");
-  return oneBlock(full);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      videoId,
+      url: videoId ? `https://www.youtube.com/watch?v=${videoId}` : input.url ?? null,
+      wordCount: words,
+      chunkCount: chunks.length,
+      durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
+      transcriptText: text,
+      chunks: structuredTranscriptChunks(chunks),
+      resolvedInputs: {
+        videoId,
+        url: input.url ?? null
+      }
+    }
+  };
 }
 function formatFacebookPageIntel(raw, input) {
   const parsed = parseData(raw);
@@ -14470,12 +14579,13 @@ function formatFacebookPageIntel(raw, input) {
   const ads = d.ads ?? [];
   const s = d.summary ?? { totalAds: 0, activeCount: 0, videoCount: 0, imageCount: 0 };
   const adBlocks = ads.map((ad, i) => [
-    `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? "\u2014"}`,
+    `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? ad.started ?? "\u2014"}`,
     ad.headline ? `**Headline:** ${ad.headline}` : "",
     ad.primaryText ? `**Copy:** ${truncate(ad.primaryText, 200)}` : "",
     ad.cta ? `**CTA:** ${ad.cta}` : "",
-    ad.videoUrl ? `**Video URL:** \`${ad.videoUrl}\`` : "",
-    ad.variations ? `**Variations:** ${ad.variations}` : ""
+    ad.landingUrl ? `**Landing URL:** ${ad.landingUrl}` : "",
+    ad.videoUrl ?? ad.videoSrc ? `**Video URL:** \`${ad.videoUrl ?? ad.videoSrc}\`` : "",
+    ad.variations ?? ad.clusterCount ? `**Variations:** ${ad.variations ?? ad.clusterCount}` : ""
   ].filter(Boolean).join("\n")).join("\n\n---\n\n");
   const full = [
     `# Facebook Ad Intel: ${advertiser}`,
@@ -14501,11 +14611,16 @@ ${adBlocks}`,
         libraryId: ad.libraryId ?? null,
         status: ad.status ?? null,
         creativeType: ad.creativeType ?? null,
+        primaryText: ad.primaryText ?? null,
         headline: ad.headline ?? null,
         cta: ad.cta ?? null,
-        startDate: ad.startDate ?? null,
-        videoUrl: ad.videoUrl ?? null,
-        variations: typeof ad.variations === "number" ? ad.variations : null
+        startDate: ad.startDate ?? ad.started ?? null,
+        landingUrl: ad.landingUrl ?? null,
+        domain: ad.domain ?? null,
+        videoUrl: ad.videoUrl ?? ad.videoSrc ?? null,
+        imageUrl: ad.imageUrl ?? ad.imageSrc ?? null,
+        videoPoster: ad.videoPoster ?? null,
+        variations: typeof ad.variations === "number" ? ad.variations : typeof ad.clusterCount === "number" ? ad.clusterCount : null
       }))
     }
   };
@@ -14539,8 +14654,11 @@ ${rows}`,
       advertiserCount: advertisers.length,
       advertisers: advertisers.map((a) => ({
         name: a.pageName ?? a.name ?? null,
+        pageId: a.pageId ?? null,
+        pageUrl: a.pageUrl ?? null,
         adCount: typeof a.adCount === "number" ? a.adCount : null,
-        libraryId: a.sampleLibraryId ?? a.libraryId ?? null
+        libraryId: a.sampleLibraryId ?? a.libraryId ?? null,
+        sampleLibraryId: a.sampleLibraryId ?? null
       }))
     }
   };
@@ -14638,6 +14756,34 @@ function formatWorkflowSuggest(input) {
     }
   };
 }
+function workflowStepLines(data) {
+  const step = data.step;
+  const nextStep = data.nextStep;
+  const done = data.done === true;
+  const lines = [];
+  if (step) {
+    const index = Number(step.index ?? 0);
+    const totalSteps = step.totalSteps != null ? Number(step.totalSteps) : void 0;
+    const stepLabel = totalSteps ? `${index + 1}/${totalSteps}` : `${index + 1}`;
+    lines.push(`
+## Step ${stepLabel}: ${step.title ?? step.id ?? ""}`);
+    const output = step.output;
+    if (output && Object.keys(output).length) {
+      lines.push(Object.entries(output).map(([k, v]) => `- ${k}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`).join("\n"));
+    }
+    const warnings = Array.isArray(step.warnings) ? step.warnings : [];
+    if (warnings.length) lines.push(`
+**Warnings:**
+${warnings.map((w) => `- ${w}`).join("\n")}`);
+  }
+  if (done) {
+    lines.push("\n**Done.** All steps complete.");
+  } else if (nextStep && typeof nextStep === "object") {
+    lines.push(`
+**Next step:** \`${nextStep.id ?? nextStep.index}\` \u2014 call \`workflow_step\` with this run id to continue.`);
+  }
+  return lines;
+}
 function formatWorkflowRun(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -14651,6 +14797,7 @@ function formatWorkflowRun(raw, input) {
     `**Run ID:** \`${runId || "unknown"}\``,
     `**Status:** ${status}`,
     summary?.title ? `**Title:** ${summary.title}` : "",
+    ...workflowStepLines(parsed.data),
     summary?.summary ? `
 ## Summary
 ${summary.summary}` : "",
@@ -14666,6 +14813,42 @@ ${workflowArtifactRows(artifacts)}` : "",
       input: input.input ?? {},
       run,
       summary,
+      step: parsed.data.step,
+      nextStep: parsed.data.nextStep ?? null,
+      done: parsed.data.done === true,
+      artifacts
+    }
+  };
+}
+function formatWorkflowStep(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const run = parsed.data.run;
+  const summary = parsed.data.summary;
+  const artifacts = workflowArtifactsFrom(run);
+  const done = parsed.data.done === true;
+  const full = [
+    `# Workflow Step`,
+    `**Run ID:** \`${input.runId}\``,
+    `**Status:** ${run?.status ?? (done ? "done" : "running")}`,
+    ...workflowStepLines(parsed.data),
+    done && summary?.summary ? `
+## Summary
+${summary.summary}` : "",
+    artifacts.length ? `
+## Artifacts
+${workflowArtifactRows(artifacts)}` : "",
+    done && artifacts.length ? "\nUse `workflow_artifact_read` with the run id and artifact id to pull CSV, JSON, Markdown, or report content into context." : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      runId: input.runId,
+      run,
+      summary: summary ?? null,
+      step: parsed.data.step,
+      nextStep: parsed.data.nextStep ?? null,
+      done,
       artifacts
     }
   };
@@ -15070,6 +15253,7 @@ function formatFacebookAdTranscribe(raw, input) {
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const words = wordCount(text);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -15078,7 +15262,7 @@ function formatFacebookAdTranscribe(raw, input) {
   }).join("\n");
   const full = [
     `# Facebook Ad Transcript`,
-    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `**Duration:** ${durSec}s \xB7 **${words} words**`,
     `
 ## Full Transcript
 ${text}`,
@@ -15091,7 +15275,20 @@ ${chunkRows}` : "",
 ---
 \u{1F4A1} Get more ads from this advertiser: use \`facebook_page_intel\`. For public Facebook reel/post URLs, use \`facebook_video_transcribe\`.`
   ].filter(Boolean).join("\n");
-  return oneBlock(full);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      videoUrl: input.videoUrl,
+      wordCount: words,
+      chunkCount: chunks.length,
+      durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
+      transcriptText: text,
+      chunks: structuredTranscriptChunks(chunks),
+      resolvedInputs: {
+        videoUrl: input.videoUrl
+      }
+    }
+  };
 }
 function formatFacebookVideoTranscribe(raw, input) {
   const parsed = parseData(raw);
@@ -15099,7 +15296,7 @@ function formatFacebookVideoTranscribe(raw, input) {
   const d = parsed.data;
   const text = d.text ?? "";
   const chunks = d.chunks ?? [];
-  const wordCount = text.trim() ? text.trim().split(/\s+/).length : 0;
+  const wordCount2 = text.trim() ? text.trim().split(/\s+/).length : 0;
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
   const videoDuration = typeof d.videoDurationSec === "number" ? `${Math.round(d.videoDurationSec)}s` : "\u2014";
   const label = d.videoId ? `Facebook Organic Video \`${d.videoId}\`` : "Facebook Organic Video";
@@ -15112,7 +15309,7 @@ function formatFacebookVideoTranscribe(raw, input) {
   const full = [
     `# ${label} Transcript`,
     d.ownerName ? `**Owner:** ${d.ownerName}` : "",
-    `**Video duration:** ${videoDuration} \xB7 **Transcribed in:** ${durSec}s \xB7 **${wordCount} words**`,
+    `**Video duration:** ${videoDuration} \xB7 **Transcribed in:** ${durSec}s \xB7 **${wordCount2} words**`,
     d.pageUrl ? `**Page URL:** ${d.pageUrl}` : `**Page URL:** ${input.url}`,
     d.videoUrl ? `**Extracted MP4:** \`${d.videoUrl}\`` : "",
     `
@@ -15138,7 +15335,7 @@ ${chunkRows}` : "",
       bitrate: typeof d.bitrate === "number" ? d.bitrate : null,
       videoDurationSec: typeof d.videoDurationSec === "number" ? d.videoDurationSec : null,
       videoUrl: d.videoUrl ?? "",
-      wordCount,
+      wordCount: wordCount2,
       chunkCount: chunks.length,
       transcriptText: text,
       chunks: chunks.map((c) => ({
@@ -15149,6 +15346,96 @@ ${chunkRows}` : "",
     }
   };
 }
+function formatCaptureSerpSnapshot(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const providerPayload = d;
+  const organic = Array.isArray(d.organicResults) ? d.organicResults : Array.isArray(d.organic) ? d.organic : [];
+  const localPack = Array.isArray(d.localPack) ? d.localPack : [];
+  const artifacts = Array.isArray(d.artifacts) ? d.artifacts : [];
+  const status = String(d.status ?? d.captureStatus ?? "captured");
+  const query = typeof d.query === "string" ? d.query : typeof input.query === "string" ? input.query : null;
+  const location2 = typeof d.location === "string" ? d.location : typeof input.location === "string" ? input.location : null;
+  const capturedAt = typeof d.capturedAt === "string" ? d.capturedAt : typeof d.extractedAt === "string" ? d.extractedAt : null;
+  const resultCount = organic.length + localPack.length;
+  const full = [
+    `# SERP Intelligence Snapshot: ${query ?? "query"}`,
+    `**Status:** ${status}`,
+    location2 ? `**Location:** ${location2}` : "",
+    `**Result count:** ${resultCount}`,
+    artifacts.length ? `**Artifacts:** ${artifacts.length}` : "",
+    "",
+    "Use `capture_serp_page_snapshots` when you need page-level evidence for ranking URLs."
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      schemaVersion: "serp-intelligence.capture.v1",
+      status,
+      query,
+      location: location2,
+      capturedAt,
+      resultCount,
+      snapshotId: typeof d.snapshotId === "string" ? d.snapshotId : typeof d.snapshot_id === "string" ? d.snapshot_id : typeof d.id === "string" ? d.id : null,
+      resolvedInputs: {
+        query: input.query ?? null,
+        location: input.location ?? null,
+        gl: input.gl ?? null,
+        hl: input.hl ?? null,
+        device: input.device ?? null,
+        proxyMode: input.proxyMode ?? null,
+        proxyZip: input.proxyZip ?? null,
+        pages: input.pages ?? null
+      },
+      artifacts,
+      diagnostics: d.diagnostics && typeof d.diagnostics === "object" ? d.diagnostics : null,
+      providerPayload
+    }
+  };
+}
+function formatCaptureSerpPageSnapshots(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const captures = Array.isArray(d.captures) ? d.captures : Array.isArray(d.results) ? d.results : [];
+  const failedCount = captures.filter((c) => c.status === "failed" || c.error).length;
+  const status = String(d.status ?? (failedCount ? "partial" : "captured"));
+  const rows = captures.slice(0, 25).map((capture, i) => {
+    const url = typeof capture.url === "string" ? capture.url : "";
+    const sourceKind = typeof capture.sourceKind === "string" ? capture.sourceKind : typeof capture.source_kind === "string" ? capture.source_kind : "configured_target";
+    return `| ${i + 1} | ${cell(url)} | ${cell(sourceKind)} | ${cell(String(capture.status ?? (capture.error ? "failed" : "ok")))} |`;
+  }).join("\n");
+  const full = [
+    "# SERP Intelligence Page Snapshots",
+    `**Status:** ${status}`,
+    `**Captured:** ${captures.length}`,
+    `**Failed:** ${failedCount}`,
+    captures.length ? `
+| # | URL | Source | Status |
+|---|-----|--------|--------|
+${rows}` : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      schemaVersion: "serp-intelligence.page-snapshots.v1",
+      status,
+      count: captures.length,
+      failedCount,
+      captures,
+      resolvedInputs: {
+        urls: input.urls ?? null,
+        targets: input.targets ?? null,
+        maxConcurrency: input.maxConcurrency ?? null,
+        timeoutMs: input.timeoutMs ?? null,
+        debug: input.debug ?? null
+      },
+      diagnostics: d.diagnostics && typeof d.diagnostics === "object" ? d.diagnostics : null,
+      providerPayload: d
+    }
+  };
+}
 var import_node_fs3, import_node_os3, import_node_path5, reportSavingEnabled;
 var init_mcp_response_formatter = __esm({
   "src/mcp/mcp-response-formatter.ts"() {
@@ -15623,6 +15910,7 @@ var init_directory_workflow = __esm({
     init_mcp_response_formatter();
     init_browser_service_env();
     init_maps_search_rotation();
+    init_schemas3();
     init_csv();
     init_location_db();
     DirectoryWorkflowOptionsSchema = import_zod18.z.object({
@@ -15638,7 +15926,7 @@ var init_directory_workflow = __esm({
       saveCsv: import_zod18.z.boolean().default(true),
       gl: import_zod18.z.string().length(2).default("us"),
       hl: import_zod18.z.string().length(2).default("en"),
-      proxyMode: import_zod18.z.enum(["location", "configured", "none"]).default("location"),
+      proxyMode: import_zod18.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
       proxyZip: import_zod18.z.string().regex(/^\d{5}$/).optional(),
       debug: import_zod18.z.boolean().default(false),
       headless: import_zod18.z.boolean().default(true),
@@ -16062,102 +16350,141 @@ var init_agent_packet = __esm({
       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 status = warnings.length ? "partial" : "succeeded";
+            const counts = { sources: rows.length, competitors: competitors.length };
+            await ctx.artifacts.writeManifest(status, counts, warnings, []);
+            return {
+              state,
+              output: { sources: rows.length, competitors: competitors.length, status },
+              summary: { title: "Agent-Ready SEO Packet", summary, status, 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 status = warnings.length ? "partial" : "succeeded";
-        const counts = { sources: rows.length, competitors: competitors.length };
-        await ctx.artifacts.writeManifest(status, counts, warnings, errors);
-        return { title: "Agent-Ready SEO Packet", summary, status, counts, warnings, errors, reportPath };
-      }
+      ]
     };
   }
 });
@@ -16220,6 +16547,7 @@ var init_directory = __esm({
     "use strict";
     import_zod20 = require("zod");
     init_report_renderer();
+    init_schemas3();
     DirectoryWorkflowCliInputSchema = import_zod20.z.object({
       query: import_zod20.z.string().min(1),
       state: import_zod20.z.string().min(2).default("TN"),
@@ -16227,7 +16555,7 @@ var init_directory = __esm({
       maxCities: import_zod20.z.number().int().min(1).max(100).default(25),
       maxResultsPerCity: import_zod20.z.number().int().min(1).max(50).default(20),
       concurrency: import_zod20.z.number().int().min(1).max(5).default(5),
-      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default("location"),
+      proxyMode: import_zod20.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
       saveCsv: import_zod20.z.boolean().default(true)
     });
     DIRECTORY_CSV_HEADERS = [
@@ -16344,6 +16672,7 @@ var init_local_competitive_audit = __esm({
     import_zod21 = require("zod");
     init_report_renderer();
     init_directory();
+    init_schemas3();
     LocalCompetitiveAuditInputSchema = import_zod21.z.object({
       query: import_zod21.z.string().min(1),
       state: import_zod21.z.string().min(2).default("TN"),
@@ -16353,7 +16682,7 @@ var init_local_competitive_audit = __esm({
       hydrateTop: import_zod21.z.number().int().min(0).max(10).default(5),
       maxReviews: import_zod21.z.number().int().min(0).max(500).default(50),
       concurrency: import_zod21.z.number().int().min(1).max(5).default(5),
-      proxyMode: import_zod21.z.enum(["location", "configured", "none"]).default("location"),
+      proxyMode: import_zod21.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
       returnPartial: import_zod21.z.boolean().default(true)
     });
     localCompetitiveAuditWorkflowDefinition = {
@@ -16805,6 +17134,7 @@ var init_comparison_briefs = __esm({
     init_report_renderer();
     init_directory();
     init_seo_workflow_utils();
+    init_schemas3();
     ProxyModeSchema = import_zod22.z.enum(["location", "configured", "none"]);
     MapComparisonInputSchema = import_zod22.z.object({
       query: import_zod22.z.string().min(1),
@@ -16816,7 +17146,7 @@ var init_comparison_briefs = __esm({
       hydrateTop: import_zod22.z.number().int().min(0).max(10).default(5),
       maxReviews: import_zod22.z.number().int().min(0).max(500).default(25),
       concurrency: import_zod22.z.number().int().min(1).max(5).default(5),
-      proxyMode: ProxyModeSchema.default("location"),
+      proxyMode: ProxyModeSchema.default(DEFAULT_MAPS_PROXY_MODE),
       returnPartial: import_zod22.z.boolean().default(true)
     }).refine((input) => input.location || input.state, {
       message: "Either location or state is required for map-comparison"
@@ -17230,22 +17560,44 @@ function workflowDefinition(id) {
   if (!definition) throw new Error(`Unknown workflow "${id}". Available: ${DEFINITIONS.map((def) => def.id).join(", ")}`);
   return definition;
 }
-async function runWorkflow(id, rawInput, options = {}) {
+function workflowStepCount(id) {
   const definition = workflowDefinition(id);
-  const input = definition.inputSchema.parse(rawInput);
+  return definition.steps?.length ?? 1;
+}
+function workflowSupportsSteps(id) {
+  const definition = workflowDefinition(id);
+  return Boolean(definition.steps && definition.steps.length > 0);
+}
+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.");
-  const apiUrl = options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
+  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 client2 = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
+  const ctx = { runId: artifacts.runId, startedAt: artifacts.startedAt, client: client2, artifacts, signal: options.signal };
   try {
-    return await definition.run(input, {
-      runId: artifacts.runId,
-      startedAt: artifacts.startedAt,
-      client: client2,
-      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}
@@ -17256,10 +17608,50 @@ ${message}
     throw err;
   }
 }
-var import_zod23, DEFINITIONS;
+async function runWorkflowStep(id, rawInput, opts) {
+  const definition = workflowDefinition(id);
+  const steps = definition.steps;
+  if (!steps || steps.length === 0) throw new Error(`Workflow "${id}" does not support stepwise execution`);
+  if (opts.stepIndex < 0 || opts.stepIndex >= steps.length) {
+    throw new Error(`Step index ${opts.stepIndex} is out of range for "${id}" (${steps.length} steps)`);
+  }
+  const options = opts.options ?? {};
+  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 client2 = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
+  const ctx = { runId: artifacts.runId, startedAt: artifacts.startedAt, client: client2, artifacts, signal: options.signal };
+  const state = opts.state ?? (definition.createState ? definition.createState(input) : {});
+  const step = steps[opts.stepIndex];
+  const outcome = await step.run({ input, state, ctx });
+  const writtenArtifacts = await Promise.all(
+    artifacts.artifacts.map(async (artifact) => ({
+      ...artifact,
+      content: await (0, import_promises7.readFile)(artifact.path, "utf8").catch(() => "")
+    }))
+  );
+  return {
+    runId: artifacts.runId,
+    workflowId: definition.id,
+    title: definition.title,
+    stepIndex: opts.stepIndex,
+    stepId: step.id,
+    stepTitle: step.title,
+    totalSteps: steps.length,
+    isLast: opts.stepIndex === steps.length - 1,
+    output: outcome.output,
+    state: outcome.state,
+    warnings: outcome.warnings ?? [],
+    summary: outcome.summary ?? null,
+    artifacts: writtenArtifacts
+  };
+}
+var import_promises7, import_zod23, DEFINITIONS;
 var init_registry2 = __esm({
   "src/workflows/registry.ts"() {
     "use strict";
+    import_promises7 = require("fs/promises");
     import_zod23 = require("zod");
     init_artifact_writer();
     init_http_client2();
@@ -17328,7 +17720,7 @@ async function readManifestFromSummary(summary) {
   if (!summary.reportPath) return null;
   const manifestPath = summary.reportPath.replace(/report\.html$/, "manifest.json");
   try {
-    return JSON.parse(await (0, import_promises7.readFile)(manifestPath, "utf8"));
+    return JSON.parse(await (0, import_promises8.readFile)(manifestPath, "utf8"));
   } catch {
     return null;
   }
@@ -17409,6 +17801,88 @@ async function executeWorkflowRun(input) {
     throw err;
   }
 }
+async function runWorkflowStepAndPersist(input) {
+  const runId = input.run.id;
+  const workflowId = input.run.workflow_id;
+  await markWorkflowRunRunning(runId);
+  let result;
+  try {
+    result = await runWorkflowStep(workflowId, input.workflowInput, {
+      stepIndex: input.stepIndex,
+      state: input.priorState ?? void 0,
+      options: {
+        apiKey: input.user.api_key,
+        apiUrl: input.apiUrl,
+        outputDir: hostedWorkflowOutputDir(),
+        runId,
+        headers: input.concurrencyLockId ? { "x-mcp-scraper-concurrency-lock": input.concurrencyLockId } : void 0
+      }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    await failWorkflowRunRecord(runId, message, { error: message });
+    const failedRun = await getWorkflowRun(runId, input.user.id);
+    if (failedRun) await deliverWorkflowWebhook({ userId: input.user.id, run: failedRun, scheduleId: failedRun.schedule_id, webhookUrl: input.webhookUrl ?? null, summary: null, artifacts: [] });
+    throw err;
+  }
+  if (result.artifacts.length) {
+    await appendWorkflowArtifacts(runId, input.user.id, result.artifacts.map((a) => ({
+      kind: a.kind,
+      label: a.label,
+      path: a.path,
+      bytes: a.bytes,
+      rows: a.rows,
+      content: a.content
+    })));
+  }
+  const logEntry = {
+    stepIndex: result.stepIndex,
+    stepId: result.stepId,
+    stepTitle: result.stepTitle,
+    output: result.output,
+    warnings: result.warnings,
+    at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const status = result.isLast ? result.summary?.status ?? "succeeded" : "running";
+  await advanceWorkflowRunStep(runId, {
+    stepIndex: result.stepIndex + 1,
+    totalSteps: result.totalSteps,
+    state: result.state,
+    status,
+    logEntry,
+    appendLog: input.priorLog
+  });
+  if (result.isLast && result.summary) {
+    const manifest = await readManifestFromSummary(result.summary);
+    await completeWorkflowRunRecord(runId, result.summary.status, manifest ?? { summary: result.summary });
+  }
+  const run = await getWorkflowRun(runId, input.user.id);
+  const artifacts = await listWorkflowArtifacts(runId, input.user.id);
+  if (result.isLast && run) {
+    await deliverWorkflowWebhook({ userId: input.user.id, run, scheduleId: run.schedule_id, webhookUrl: input.webhookUrl ?? null, summary: result.summary, artifacts });
+  }
+  const definition = workflowDefinition(workflowId);
+  const nextIndex = result.stepIndex + 1;
+  const nextStep = result.isLast ? null : {
+    index: nextIndex,
+    id: definition.steps?.[nextIndex]?.id ?? null,
+    title: definition.steps?.[nextIndex]?.title ?? null
+  };
+  return {
+    run: run ? exposeRun(input.c, run, artifacts) : null,
+    summary: result.isLast ? result.summary : null,
+    step: {
+      index: result.stepIndex,
+      id: result.stepId,
+      title: result.stepTitle,
+      totalSteps: result.totalSteps,
+      output: result.output,
+      warnings: result.warnings
+    },
+    nextStep,
+    done: result.isLast
+  };
+}
 async function dispatchDueWorkflowSchedules(apiUrl, limit = 3) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const due = await listDueWorkflowSchedules(now, limit);
@@ -17461,12 +17935,12 @@ async function dispatchDueWorkflowSchedules(apiUrl, limit = 3) {
   }
   return { dispatched: results.length, results };
 }
-var import_node_crypto3, import_promises7, import_hono7, import_zod24, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema;
+var import_node_crypto3, import_promises8, import_hono7, import_zod24, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema, TERMINAL_RUN_STATUSES;
 var init_workflow_routes = __esm({
   "src/api/workflow-routes.ts"() {
     "use strict";
     import_node_crypto3 = require("crypto");
-    import_promises7 = require("fs/promises");
+    import_promises8 = require("fs/promises");
     import_hono7 = require("hono");
     import_zod24 = require("zod");
     init_artifact_writer();
@@ -17525,7 +17999,29 @@ var init_workflow_routes = __esm({
       if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       let run = null;
       try {
-        run = await createWorkflowRun({ userId: user.id, workflowId: parsed.data.workflowId, workflowInput: input });
+        const stepwise = workflowSupportsSteps(parsed.data.workflowId);
+        run = await createWorkflowRun({
+          userId: user.id,
+          workflowId: parsed.data.workflowId,
+          workflowInput: input,
+          webhookUrl,
+          totalSteps: stepwise ? workflowStepCount(parsed.data.workflowId) : 1
+        });
+        if (stepwise) {
+          const response = await runWorkflowStepAndPersist({
+            c,
+            user,
+            run,
+            workflowInput: input,
+            stepIndex: 0,
+            priorState: null,
+            priorLog: [],
+            apiUrl: originFromUrl(c.req.url),
+            webhookUrl,
+            concurrencyLockId: gate.lockId
+          });
+          return c.json(response);
+        }
         const executed = await executeWorkflowRun({
           runId: run.id,
           user,
@@ -17535,7 +18031,7 @@ var init_workflow_routes = __esm({
           webhookUrl,
           concurrencyLockId: gate.lockId
         });
-        return c.json({ run: exposeRun(c, executed.run, executed.artifacts), summary: executed.summary });
+        return c.json({ run: exposeRun(c, executed.run, executed.artifacts), summary: executed.summary, done: true });
       } catch (err) {
         const failed = run ? await getWorkflowRun(run.id, user.id) : null;
         return c.json({ run: failed, error: err instanceof Error ? err.message : String(err) }, 500);
@@ -17543,6 +18039,50 @@ var init_workflow_routes = __esm({
         await releaseConcurrencyGate(gate.lockId);
       }
     });
+    TERMINAL_RUN_STATUSES = ["succeeded", "partial", "failed", "cancelled"];
+    workflowApp.post("/runs/:id/step", createApiKeyAuth(), async (c) => {
+      const user = c.get("user");
+      const run = await getWorkflowRun(c.req.param("id"), user.id);
+      if (!run) return c.json({ error: "Run not found" }, 404);
+      if (!workflowSupportsSteps(run.workflow_id)) {
+        return c.json({ error: `Workflow "${run.workflow_id}" does not support stepwise execution` }, 400);
+      }
+      const artifactsNow = await listWorkflowArtifacts(run.id, user.id);
+      if (TERMINAL_RUN_STATUSES.includes(run.status)) {
+        return c.json({ run: exposeRun(c, run, artifactsNow), done: true, error: `Run is already ${run.status}` }, 409);
+      }
+      const stepState = await getWorkflowRunStepState(run.id, user.id);
+      const stepIndex = stepState?.stepIndex ?? run.step_index;
+      const totalSteps = workflowStepCount(run.workflow_id);
+      if (stepIndex >= totalSteps) {
+        return c.json({ run: exposeRun(c, run, artifactsNow), done: true, error: "No remaining steps" }, 409);
+      }
+      const gate = await acquireConcurrencyGate(user, "workflow_run", {
+        ttlSeconds: 60 * 60,
+        metadata: { workflowId: run.workflow_id, step: stepIndex }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      try {
+        const response = await runWorkflowStepAndPersist({
+          c,
+          user,
+          run,
+          workflowInput: run.input,
+          stepIndex,
+          priorState: stepState?.state ?? null,
+          priorLog: stepState?.stepLog ?? run.step_log,
+          apiUrl: originFromUrl(c.req.url),
+          webhookUrl: run.webhook_url,
+          concurrencyLockId: gate.lockId
+        });
+        return c.json(response);
+      } catch (err) {
+        const failed = await getWorkflowRun(run.id, user.id);
+        return c.json({ run: failed, error: err instanceof Error ? err.message : String(err) }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
+      }
+    });
     workflowApp.get("/runs", createApiKeyAuth(), async (c) => {
       const user = c.get("user");
       const runs = await listWorkflowRuns(user.id);
@@ -17561,14 +18101,17 @@ var init_workflow_routes = __esm({
       if (!run) return c.json({ error: "Run not found" }, 404);
       const artifact = await getWorkflowArtifact(c.req.param("artifactId"), user.id);
       if (!artifact || artifact.run_id !== run.id) return c.json({ error: "Artifact not found" }, 404);
+      const filename = artifact.path.split("/").pop() || artifact.id;
+      const headers = {
+        "Content-Type": artifact.content_type,
+        "Content-Disposition": `attachment; filename="${filename}"`
+      };
+      if (artifact.content != null) {
+        return new Response(artifact.content, { headers });
+      }
       try {
-        const content = await (0, import_promises7.readFile)(artifact.path);
-        return new Response(content, {
-          headers: {
-            "Content-Type": artifact.content_type,
-            "Content-Disposition": `attachment; filename="${artifact.path.split("/").pop() || artifact.id}"`
-          }
-        });
+        const content = await (0, import_promises8.readFile)(artifact.path);
+        return new Response(content, { headers });
       } catch {
         return c.json({ error: "Artifact file is no longer available" }, 410);
       }
@@ -17856,7 +18399,7 @@ async function capturePageSnapshot(target, options = {}) {
     const textContent = truncateContent(text, maxContentChars);
     const schemaTypes = getSchemaTypes(extraction.schema, extraction.kpo.schemaTypes);
     const metrics = countLinks(extraction.bodyHtml, extraction.url);
-    const wordCount = countWords(extraction.bodyMarkdown);
+    const wordCount2 = countWords(extraction.bodyMarkdown);
     const contentSha256 = sha256(extraction.bodyMarkdown);
     const canonicalUrl = extraction.kpo.canonicalUrl ? new URL(extraction.kpo.canonicalUrl, extraction.url).href : null;
     const contentIncluded = Boolean(options.includeContent);
@@ -17910,10 +18453,10 @@ async function capturePageSnapshot(target, options = {}) {
       },
       error: null,
       schemaTypes,
-      wordCount,
+      wordCount: wordCount2,
       linkCounts: {
         ...metrics,
-        wordCount
+        wordCount: wordCount2
       },
       hashes: {
         htmlSha256: sha256(extraction.bodyHtml),
@@ -19489,7 +20032,7 @@ async function harvest(rawOptions) {
   const signal = getAbortSignal(rawOptions);
   const onAttemptEvent = getAttemptLogSink(rawOptions);
   const requestedProxyMode = raw.proxyMode;
-  const proxyMode = requestedProxyMode === "none" ? "none" : requestedProxyMode === "configured" ? "configured" : "location";
+  const proxyMode = requestedProxyMode === "location" || requestedProxyMode === "none" || requestedProxyMode === "configured" ? requestedProxyMode : DEFAULT_PROXY_MODE;
   const kernelApiKey = typeof raw.kernelApiKey === "string" ? raw.kernelApiKey.trim() : browserServiceApiKey();
   const configuredKernelProxyId = typeof raw.kernelProxyId === "string" ? raw.kernelProxyId.trim() : browserServiceProxyId();
   const proxyOpts = {
@@ -19863,6 +20406,7 @@ var init_schemas4 = __esm({
   "src/serp-intelligence/schemas.ts"() {
     "use strict";
     import_zod25 = require("zod");
+    init_schemas3();
     SerpIntelligenceDeviceValues = ["desktop", "mobile"];
     SerpIntelligenceProxyModeValues = ["location", "configured", "none"];
     SerpIntelligenceAttemptOutcomeValues = [
@@ -19903,7 +20447,7 @@ var init_schemas4 = __esm({
       gl: import_zod25.z.string().trim().length(2).default("us"),
       hl: import_zod25.z.string().trim().length(2).default("en"),
       device: import_zod25.z.enum(SerpIntelligenceDeviceValues).default("desktop"),
-      proxyMode: import_zod25.z.enum(SerpIntelligenceProxyModeValues).default("location"),
+      proxyMode: import_zod25.z.enum(SerpIntelligenceProxyModeValues).default(DEFAULT_PROXY_MODE),
       proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional(),
       pages: import_zod25.z.number().int().min(1).max(2).default(1),
       debug: import_zod25.z.boolean().default(false),
@@ -20433,16 +20977,17 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.19";
+    PACKAGE_VERSION = "0.2.20";
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod26, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod26, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, TranscriptChunkOutput, YoutubeTranscribeOutputSchema, FacebookAdTranscribeOutputSchema, CaptureSerpSnapshotOutputSchema, CaptureSerpPageSnapshotsOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStepInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStepOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
     import_zod26 = require("zod");
+    init_schemas3();
     HarvestPaaInputSchema = {
       query: import_zod26.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
       location: import_zod26.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
@@ -20450,8 +20995,8 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
       hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
       device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
       debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
     };
     ExtractUrlInputSchema = {
@@ -20475,22 +21020,23 @@ var init_mcp_tool_schemas = __esm({
       mode: import_zod26.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
       query: import_zod26.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
       channelHandle: import_zod26.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
-      maxVideos: import_zod26.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50. Increase when user asks for full channel/history.")
+      maxVideos: import_zod26.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50, maximum 500. Use 10-25 for quick topic discovery, 50 for normal channel/search harvests, and larger values only when the user asks for full channel/history because large responses consume more context.")
     };
     YoutubeTranscribeInputSchema = {
-      videoId: import_zod26.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+      videoId: import_zod26.z.string().min(1).optional().describe("YouTube video ID, e.g. dQw4w9WgXcQ. Use only an ID returned by youtube_harvest or visible in a YouTube URL; do not invent one."),
+      url: import_zod26.z.string().url().optional().describe("Full YouTube URL, e.g. https://www.youtube.com/watch?v=dQw4w9WgXcQ or https://youtu.be/dQw4w9WgXcQ. Use this when the user pasted a URL instead of an ID. Provide videoId or url.")
     };
     FacebookPageIntelInputSchema = {
-      pageId: import_zod26.z.string().optional(),
-      libraryId: import_zod26.z.string().optional(),
+      pageId: import_zod26.z.string().optional().describe("Facebook advertiser/page ID. Use only a pageId returned by facebook_ad_search/facebook_page_intel or copied from Facebook Ad Library; do not construct one yourself."),
+      libraryId: import_zod26.z.string().optional().describe("Facebook Ad Library archive ID for a known ad or advertiser sample. Use a libraryId returned by facebook_ad_search, or a libraryId/adArchiveId visible in Ad Library."),
       query: import_zod26.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
-      maxAds: import_zod26.z.number().int().min(1).max(200).default(50),
-      country: import_zod26.z.string().length(2).default("US")
+      maxAds: import_zod26.z.number().int().min(1).max(200).default(50).describe("Maximum ads to inspect. Default 50, maximum 200. Prefer 25-50 for focused advertiser scans; use 100-200 only when the user asks for a broad ad archive sweep."),
+      country: import_zod26.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US. Examples: US, CA, GB, AU. Infer from the user request when they name a country.")
     };
     FacebookAdSearchInputSchema = {
       query: import_zod26.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
-      country: import_zod26.z.string().length(2).default("US"),
-      maxResults: import_zod26.z.number().int().min(1).max(20).default(10)
+      country: import_zod26.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US. Examples: US, CA, GB, AU."),
+      maxResults: import_zod26.z.number().int().min(1).max(20).default(10).describe("Maximum advertisers to return. Default 10, maximum 20. Prefer tighter search terms over maxing this out.")
     };
     FacebookAdTranscribeInputSchema = {
       videoUrl: import_zod26.z.string().url().describe("Direct Facebook CDN video URL from a facebook_page_intel ad result. Do not pass a public Facebook reel/post/share URL here; use facebook_video_transcribe for organic Facebook URLs.")
@@ -20504,8 +21050,8 @@ var init_mcp_tool_schemas = __esm({
       location: import_zod26.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
       gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location."),
       hl: import_zod26.z.string().length(2).default("en").describe("Language inferred from user request."),
-      includeReviews: import_zod26.z.boolean().default(false).describe("Whether to fetch individual review cards"),
-      maxReviews: import_zod26.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+      includeReviews: import_zod26.z.boolean().default(false).describe("Whether to fetch individual review cards. Use true when the user asks for reviews, customer pain, complaints, praise, themes, or review evidence."),
+      maxReviews: import_zod26.z.number().int().min(1).max(500).default(50).describe("Max review cards to return when includeReviews is true. Default 50, maximum 500. Use 50 for normal review analysis and larger values only for deep review mining.")
     };
     MapsSearchInputSchema = {
       query: import_zod26.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
@@ -20513,7 +21059,7 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location."),
       hl: import_zod26.z.string().length(2).default("en").describe("Language inferred from user request."),
       maxResults: import_zod26.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
-      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting mode. Maps defaults to location so local market searches get city/state residential proxy targeting and rotation. Use configured to force the service proxy without city/ZIP targeting, and none only for local direct-network debugging."),
       proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
       debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
     };
@@ -20528,8 +21074,8 @@ var init_mcp_tool_schemas = __esm({
       includeZipGroups: import_zod26.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
       usZipsCsvPath: import_zod26.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
       saveCsv: import_zod26.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
-      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
-      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting mode for every city Maps search. Maps workflows default to location so each city can use city/state or ZIP-group residential proxy targeting. Use configured to force the service proxy without city/ZIP targeting, and none only for local direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its ZIP group or city/state location."),
       debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
     };
     RankTrackerModeSchema = import_zod26.z.enum(["maps", "organic", "ai_overview", "paa"]);
@@ -20843,8 +21389,11 @@ var init_mcp_tool_schemas = __esm({
       advertiserCount: import_zod26.z.number().int().min(0),
       advertisers: import_zod26.z.array(import_zod26.z.object({
         name: NullableString,
+        pageId: NullableString,
+        pageUrl: NullableString,
         adCount: import_zod26.z.number().int().nullable(),
-        libraryId: NullableString
+        libraryId: NullableString,
+        sampleLibraryId: NullableString
       }))
     };
     FacebookPageIntelOutputSchema = {
@@ -20857,10 +21406,15 @@ var init_mcp_tool_schemas = __esm({
         libraryId: NullableString,
         status: NullableString,
         creativeType: NullableString,
+        primaryText: NullableString,
         headline: NullableString,
         cta: NullableString,
         startDate: NullableString,
+        landingUrl: NullableString,
+        domain: NullableString,
         videoUrl: NullableString,
+        imageUrl: NullableString,
+        videoPoster: NullableString,
         variations: import_zod26.z.number().int().nullable()
       }))
     };
@@ -20882,6 +21436,58 @@ var init_mcp_tool_schemas = __esm({
         text: import_zod26.z.string()
       }))
     };
+    TranscriptChunkOutput = import_zod26.z.object({
+      startSec: import_zod26.z.number(),
+      endSec: import_zod26.z.number(),
+      text: import_zod26.z.string()
+    });
+    YoutubeTranscribeOutputSchema = {
+      videoId: NullableString,
+      url: NullableString,
+      wordCount: import_zod26.z.number().int().min(0),
+      chunkCount: import_zod26.z.number().int().min(0),
+      durationMs: import_zod26.z.number().nullable(),
+      transcriptText: import_zod26.z.string(),
+      chunks: import_zod26.z.array(TranscriptChunkOutput),
+      resolvedInputs: import_zod26.z.object({
+        videoId: NullableString,
+        url: NullableString
+      })
+    };
+    FacebookAdTranscribeOutputSchema = {
+      videoUrl: import_zod26.z.string().url(),
+      wordCount: import_zod26.z.number().int().min(0),
+      chunkCount: import_zod26.z.number().int().min(0),
+      durationMs: import_zod26.z.number().nullable(),
+      transcriptText: import_zod26.z.string(),
+      chunks: import_zod26.z.array(TranscriptChunkOutput),
+      resolvedInputs: import_zod26.z.object({
+        videoUrl: import_zod26.z.string().url()
+      })
+    };
+    CaptureSerpSnapshotOutputSchema = {
+      schemaVersion: import_zod26.z.literal("serp-intelligence.capture.v1"),
+      status: import_zod26.z.string(),
+      query: NullableString,
+      location: NullableString,
+      capturedAt: NullableString,
+      resultCount: import_zod26.z.number().int().min(0).nullable(),
+      snapshotId: NullableString,
+      resolvedInputs: import_zod26.z.record(import_zod26.z.unknown()),
+      artifacts: import_zod26.z.array(import_zod26.z.record(import_zod26.z.unknown())),
+      diagnostics: import_zod26.z.record(import_zod26.z.unknown()).nullable(),
+      providerPayload: import_zod26.z.record(import_zod26.z.unknown())
+    };
+    CaptureSerpPageSnapshotsOutputSchema = {
+      schemaVersion: import_zod26.z.literal("serp-intelligence.page-snapshots.v1"),
+      status: import_zod26.z.string(),
+      count: import_zod26.z.number().int().min(0),
+      failedCount: import_zod26.z.number().int().min(0),
+      captures: import_zod26.z.array(import_zod26.z.record(import_zod26.z.unknown())),
+      resolvedInputs: import_zod26.z.record(import_zod26.z.unknown()),
+      diagnostics: import_zod26.z.record(import_zod26.z.unknown()).nullable(),
+      providerPayload: import_zod26.z.record(import_zod26.z.unknown())
+    };
     CreditsInfoInputSchema = {
       item: import_zod26.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
       includeLedger: import_zod26.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
@@ -20909,16 +21515,19 @@ var init_mcp_tool_schemas = __esm({
       maxSuggestions: import_zod26.z.number().int().min(1).max(8).default(3).describe("Number of matching workflow recipes to return.")
     };
     WorkflowRunInputSchema = {
-      workflowId: WorkflowIdSchema2.describe("Workflow to run. Use workflow_list or workflow_suggest first when unsure."),
+      workflowId: WorkflowIdSchema2.describe("Workflow to run: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. Use only these values; call workflow_list or workflow_suggest first when unsure."),
       input: import_zod26.z.record(import_zod26.z.unknown()).default({}).describe("Workflow-specific input object. Examples: agent-packet uses {keyword, domain?, location?, maxQuestions?}; local-competitive-audit uses {query, state, minPopulation?, maxCities?, maxResultsPerCity?, hydrateTop?, maxReviews?}; serp-comparison uses {keyword, domain?, url?, location?, extractTop?}."),
       webhookUrl: import_zod26.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
     };
+    WorkflowStepInputSchema = {
+      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself. Advances the run by exactly one step (one logical leg, e.g. one live harvest).")
+    };
     WorkflowStatusInputSchema = {
-      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run.")
+      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself.")
     };
     WorkflowArtifactReadInputSchema = {
-      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run or workflow_status."),
-      artifactId: import_zod26.z.string().min(1).describe("Artifact id from the run artifact list."),
+      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run, workflow_step, or workflow_status. Use only a returned runId; do not construct one yourself."),
+      artifactId: import_zod26.z.string().min(1).describe("Artifact id from the run artifact list returned by workflow_run, workflow_step, or workflow_status. Use only a returned artifactId; do not construct one yourself."),
       maxBytes: import_zod26.z.number().int().min(1e3).max(1e6).default(2e5).describe("Maximum bytes of artifact text to return inline. Use lower values for large CSV/JSON artifacts; call again with the downloadUrl if needed outside MCP.")
     };
     WorkflowRecipeOutput = import_zod26.z.object({
@@ -20951,6 +21560,18 @@ var init_mcp_tool_schemas = __esm({
       input: import_zod26.z.record(import_zod26.z.unknown()),
       run: import_zod26.z.record(import_zod26.z.unknown()).optional(),
       summary: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      step: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      nextStep: import_zod26.z.record(import_zod26.z.unknown()).nullable().optional(),
+      done: import_zod26.z.boolean().optional(),
+      artifacts: import_zod26.z.array(WorkflowArtifactOutput)
+    };
+    WorkflowStepOutputSchema = {
+      runId: import_zod26.z.string(),
+      run: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      summary: import_zod26.z.record(import_zod26.z.unknown()).nullable().optional(),
+      step: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      nextStep: import_zod26.z.record(import_zod26.z.unknown()).nullable().optional(),
+      done: import_zod26.z.boolean(),
       artifacts: import_zod26.z.array(WorkflowArtifactOutput)
     };
     WorkflowStatusOutputSchema = {
@@ -20971,8 +21592,8 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
       hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from user request."),
       device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general SERP success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
       debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
       pages: import_zod26.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
     };
@@ -20982,8 +21603,8 @@ var init_mcp_tool_schemas = __esm({
       gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
       hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from the user request."),
       device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
-      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy behavior for capture. Default configured uses the service proxy without city/ZIP targeting for the highest general capture success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when a precise city-center or ZIP proxy is needed."),
       pages: import_zod26.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
       debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
       includePageSnapshots: import_zod26.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
@@ -21402,70 +22023,72 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server);
   server.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or the market evidence is wrong. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
+    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting for the highest general success rate. Use proxyMode location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
     inputSchema: HarvestPaaInputSchema,
     outputSchema: HarvestPaaOutputSchema,
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear, the proxy tunnel fails, or location evidence is wrong."),
+    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting. Use proxyMode location and proxyZip only when the user explicitly needs city/ZIP-targeted residential proxy evidence."),
     inputSchema: SearchSerpInputSchema,
     outputSchema: SearchSerpOutputSchema,
     annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
   server.registerTool("extract_url", {
     title: "Single URL Extract",
-    description: withReportNote("Extract structured data from one public URL: page content as Markdown, heading structure, JSON-LD schema, entity details, NAP score, metadata, and missing schema fields. Use when the user provides a single URL or asks to inspect/scrape one page."),
+    description: withReportNote("Extract structured data from one public URL when the user provides one page, asks to inspect/scrape a page, or needs page content, schema, headings, metadata, screenshots, branding, or media assets. Returns structured page fields plus artifact handles for saved reports/screenshots/media when requested. Use map_site_urls before extracting a site inventory; use extract_site for multi-page crawling."),
     inputSchema: ExtractUrlInputSchema,
     outputSchema: ExtractUrlOutputSchema,
     annotations: liveWebToolAnnotations("Single URL Extract")
   }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
   server.registerTool("map_site_urls", {
     title: "Site URL Map",
-    description: withReportNote("Map/crawl a public website to build a URL inventory with HTTP status codes, broken links, redirects, and site scope. Use before extract_site for audits or when the user asks for a sitemap/URL inventory."),
+    description: withReportNote("Map/crawl a public website when the user asks for a sitemap, URL inventory, broken-link scan, redirect scan, or crawl planning. Returns internal URLs with HTTP status and truncation metadata. Use this before extract_site when choosing pages for an audit; use extract_url for one known page."),
     inputSchema: MapSiteUrlsInputSchema,
     outputSchema: MapSiteUrlsOutputSchema,
     annotations: liveWebToolAnnotations("Site URL Map")
   }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
   server.registerTool("extract_site", {
     title: "Multi-Page Site Extract",
-    description: withReportNote("Run multi-page extraction across a public website. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use for website audits, competitor audits, and full-site extraction."),
+    description: withReportNote("Run multi-page extraction across a public website when the user asks for a website audit, competitor audit, full-site content crawl, schema inventory, or page metadata review. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use map_site_urls first when URL selection matters; use extract_url for one page."),
     inputSchema: ExtractSiteInputSchema,
     outputSchema: ExtractSiteOutputSchema,
     annotations: liveWebToolAnnotations("Multi-Page Site Extract")
   }, async (input) => formatExtractSite(await executor.extractSite(input), input));
   server.registerTool("youtube_harvest", {
     title: "YouTube Video Harvest",
-    description: withReportNote('Harvest YouTube video metadata by search query or channel handle/ID/URL. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, dates, durations, URLs, thumbnails, and videoIds for follow-up transcription.'),
+    description: withReportNote('Harvest YouTube video metadata when the user wants to find videos by topic, inspect a channel library, compare video angles, or get videoIds for later transcription. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, durations, URLs, and videoIds for follow-up transcription. Use youtube_transcribe after selecting one video.'),
     inputSchema: YoutubeHarvestInputSchema,
     outputSchema: YoutubeHarvestOutputSchema,
     annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
   server.registerTool("youtube_transcribe", {
     title: "YouTube Transcription",
-    description: withReportNote("Fetch and transcribe captions from a YouTube video. Returns full transcript, timestamped chunks, and word count. Pass a videoId from youtube_harvest results or infer it from a YouTube URL if the user provided one."),
+    description: withReportNote("Fetch and transcribe captions from a YouTube video. Use this when the user asks what was said in a YouTube video, wants claims/offers/lessons extracted from a video, or provides a YouTube URL for transcript work. Returns full transcript, timestamped chunks, word count, and resolvedInputs. Pass videoId from youtube_harvest results, or pass url when the user pasted a YouTube URL. Use youtube_harvest first when you need to discover videos by topic/channel."),
     inputSchema: YoutubeTranscribeInputSchema,
+    outputSchema: YoutubeTranscribeOutputSchema,
     annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server.registerTool("facebook_page_intel", {
     title: "Facebook Advertiser Ad Intel",
-    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and direct ad video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible. For normal public Facebook reels/posts/watch/share URLs, use facebook_video_transcribe instead."),
+    description: withReportNote("Harvest ads from a Facebook advertiser when the user wants current ad copy, creative angles, CTAs, video URLs, or competitive ad intelligence for one brand/page. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and direct ad video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name as query. Use facebook_ad_search first when the advertiser handle is unknown. For normal public Facebook reels/posts/watch/share URLs, use facebook_video_transcribe instead."),
     inputSchema: FacebookPageIntelInputSchema,
     outputSchema: FacebookPageIntelOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
   server.registerTool("facebook_ad_search", {
     title: "Facebook Ad Library Search",
-    description: withReportNote("Search Facebook Ad Library by brand, advertiser, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel."),
+    description: withReportNote("Search Facebook Ad Library when the user wants to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use this to discover competitor/page handles, then pass libraryId or pageId to facebook_page_intel for ad details."),
     inputSchema: FacebookAdSearchInputSchema,
     outputSchema: FacebookAdSearchOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
-    description: "Transcribe audio from a Facebook ad video CDN URL. Returns full transcript and timestamped chunks. Use only with the direct videoUrl value from facebook_page_intel results, not public Facebook post/reel/share URLs.",
+    description: "Transcribe audio from a Facebook ad video CDN URL. Use this when facebook_page_intel returned a direct videoUrl and the user asks what the ad says, what claims it makes, or wants ad-message extraction. Returns full transcript, timestamped chunks, word count, and resolvedInputs. Use only with the direct videoUrl value from facebook_page_intel results; do not pass public Facebook post/reel/share URLs. Use facebook_video_transcribe for organic Facebook URLs, and facebook_page_intel first when you only have a brand/page/ad library handle.",
     inputSchema: FacebookAdTranscribeInputSchema,
+    outputSchema: FacebookAdTranscribeOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
   server.registerTool("facebook_video_transcribe", {
@@ -21484,14 +22107,14 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service creates a fresh residential proxy ID and browser session for the market; retryable failures rotate to a new proxy and new browser session for up to 5 attempts. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." Maps is the default location-targeted surface: omit proxyMode for normal Maps use so the service creates residential proxy evidence for the requested market and rotates on retryable failures. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
     inputSchema: MapsSearchInputSchema,
     outputSchema: MapsSearchOutputSchema,
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city search creates fresh residential proxy IDs and browser sessions; retryable city failures rotate to a new proxy and new browser session for up to 5 attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
+    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Maps workflows default to location-targeted proxying so each city can use city/state or ZIP-group residential proxy evidence; use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
     inputSchema: DirectoryWorkflowInputSchema,
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
@@ -21512,21 +22135,28 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatWorkflowSuggest(input));
   server.registerTool("workflow_run", {
     title: "Run Workflow",
-    description: withReportNote("Run a higher-level MCP Scraper workflow and return the run id, summary, and artifacts. Use after workflow_suggest or workflow_list. Runnable workflow ids: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. This is the main MCP tool for executing market analysis, ICP evidence packets, local competitive audits, Maps/SERP comparisons, content gap briefs, and AI Overview language guidance."),
+    description: withReportNote("Start a higher-level MCP Scraper workflow. Use after workflow_suggest or workflow_list. Runnable workflow ids: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. This is the main MCP tool for market analysis, ICP evidence packets, local competitive audits, Maps/SERP comparisons, content gap briefs, and AI Overview language guidance. Stepwise workflows (e.g. agent-packet) run ONE leg per call and return runId, the step output, and nextStep \u2014 when nextStep is present, call workflow_step with the runId to run the next leg, and keep calling it until done is true. This keeps each call short instead of one long blocking run, so report each step result to the user as it arrives."),
     inputSchema: WorkflowRunInputSchema,
     outputSchema: WorkflowRunOutputSchema,
     annotations: liveWebToolAnnotations("Run Workflow")
   }, async (input) => formatWorkflowRun(await executor.workflowRun(input), input));
+  server.registerTool("workflow_step", {
+    title: "Advance Workflow Step",
+    description: withReportNote("Run the next leg of a stepwise MCP Scraper workflow started with workflow_run. Pass the runId. Each call executes exactly one logical step (typically one live harvest), persists that step's artifacts, and returns the step output plus nextStep. Keep calling workflow_step with the same runId until done is true, reporting each step result to the user as it lands. Use this instead of waiting on one long workflow call \u2014 it avoids client timeouts on long multi-step jobs."),
+    inputSchema: WorkflowStepInputSchema,
+    outputSchema: WorkflowStepOutputSchema,
+    annotations: liveWebToolAnnotations("Advance Workflow Step")
+  }, async (input) => formatWorkflowStep(await executor.workflowStep(input), input));
   server.registerTool("workflow_status", {
     title: "Workflow Status",
-    description: "Fetch a hosted workflow run by id and list its current status and artifacts. Use after workflow_run when the model needs to re-open a run, inspect artifact ids, or recover from a long workflow.",
+    description: "Fetch a hosted workflow run by id and list its current status and artifacts. Use when a workflow may still be running, when the model needs to re-open a run, inspect artifact ids, recover from a long workflow, or decide whether to call workflow_step or workflow_artifact_read next. Use only a runId returned by workflow_run/workflow_step/workflow_status; do not construct one yourself.",
     inputSchema: WorkflowStatusInputSchema,
     outputSchema: WorkflowStatusOutputSchema,
     annotations: liveWebToolAnnotations("Workflow Status")
   }, async (input) => formatWorkflowStatus(await executor.workflowStatus(input), input));
   server.registerTool("workflow_artifact_read", {
     title: "Read Workflow Artifact",
-    description: "Read a workflow artifact back into MCP context by run id and artifact id. Use this before writing final deliverables so the answer is grounded in generated evidence.json, CSVs, Markdown briefs, reports, and task files instead of memory. Use maxBytes to limit large CSV/JSON artifacts.",
+    description: "Read a workflow artifact back into MCP context by run id and artifact id. Use this before writing final deliverables so the answer is grounded in generated evidence.json, CSVs, Markdown briefs, reports, and task files instead of memory. Use workflow_status first when artifact ids are unknown. Use only artifactId values returned by workflow_run/workflow_step/workflow_status; do not construct one yourself. Use maxBytes to limit large CSV/JSON artifacts.",
     inputSchema: WorkflowArtifactReadInputSchema,
     outputSchema: WorkflowArtifactReadOutputSchema,
     annotations: liveWebToolAnnotations("Read Workflow Artifact")
@@ -21568,6 +22198,27 @@ var init_paa_mcp_server = __esm({
 });
 
 // src/mcp/http-mcp-tool-executor.ts
+function youtubeVideoIdFromUrl(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname.replace(/^www\./, "").replace(/^m\./, "");
+    if (host === "youtu.be") {
+      const id = parsed.pathname.split("/").filter(Boolean)[0];
+      return id || null;
+    }
+    if (host === "youtube.com" || host === "music.youtube.com") {
+      const watchId = parsed.searchParams.get("v");
+      if (watchId) return watchId;
+      const parts = parsed.pathname.split("/").filter(Boolean);
+      const markerIndex = parts.findIndex((part) => ["shorts", "embed", "live"].includes(part));
+      if (markerIndex >= 0 && parts[markerIndex + 1]) return parts[markerIndex + 1];
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
 var HttpMcpToolExecutor;
 var init_http_mcp_tool_executor = __esm({
   "src/mcp/http-mcp-tool-executor.ts"() {
@@ -21698,7 +22349,21 @@ var init_http_mcp_tool_executor = __esm({
         return this.call("/youtube/harvest", input);
       }
       youtubeTranscribe(input) {
-        return this.call("/youtube/transcribe", input);
+        const videoId = input.videoId?.trim() || youtubeVideoIdFromUrl(input.url);
+        if (!videoId) {
+          return Promise.resolve({
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                error_code: "youtube_video_id_required",
+                error: "Pass videoId from youtube_harvest or a YouTube url that contains a video id.",
+                retryable: false
+              })
+            }],
+            isError: true
+          });
+        }
+        return this.call("/youtube/transcribe", { videoId });
       }
       facebookPageIntel(input) {
         return this.call("/facebook/page-intel", input);
@@ -21735,6 +22400,10 @@ var init_http_mcp_tool_executor = __esm({
           webhookUrl: input.webhookUrl
         }, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 9e5);
       }
+      workflowStep(input) {
+        const timeoutMs = this.httpTimeoutOverrideMs ?? Number(process.env.MCP_SCRAPER_WORKFLOW_TIMEOUT_MS ?? 9e5);
+        return this.call(`/workflows/runs/${encodeURIComponent(input.runId)}/step`, {}, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 9e5);
+      }
       workflowStatus(input) {
         return this.getJson(`/workflows/runs/${encodeURIComponent(input.runId)}`);
       }
@@ -21788,16 +22457,18 @@ async function requireMcpCallerKey(c) {
 function registerSerpIntelligenceCaptureTools(server, executor) {
   server.registerTool("capture_serp_snapshot", {
     title: "SERP Intelligence Snapshot",
-    description: "Capture a structured SERP Intelligence Google snapshot through POST /serp-intelligence/capture, the same product capture path used by Phoenix. Split query from location, infer gl/hl, use proxyMode location for localized US residential evidence; location mode creates fresh proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or location evidence is wrong. Use configured only for the static residential proxy, and none only for direct-network debugging. Set debug true when investigating location evidence, proxy behavior, CAPTCHA, or capture reliability.",
+    description: "Capture a structured SERP Intelligence Google snapshot through POST /serp-intelligence/capture, the same product capture path used by Phoenix. Split query from location and infer gl/hl. Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting for the highest general success rate. Use proxyMode location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging. Set debug true when investigating location evidence, proxy behavior, CAPTCHA, or capture reliability.",
     inputSchema: CaptureSerpSnapshotInputSchema,
+    outputSchema: CaptureSerpSnapshotOutputSchema,
     annotations: liveWebToolAnnotations("SERP Intelligence Snapshot")
-  }, async (input) => executor.captureSerpSnapshot(input));
+  }, async (input) => formatCaptureSerpSnapshot(await executor.captureSerpSnapshot(input), input));
   server.registerTool("capture_serp_page_snapshots", {
     title: "SERP Intelligence Page Snapshots",
     description: "Capture public ranking-page evidence through POST /serp-intelligence/page-snapshots, the same product page snapshot path used by Phoenix. Provide urls for simple captures or targets when preserving organic, AI citation, local-pack, configured target, or site-subject source metadata. Private IPs, localhost, file URLs, and internal URLs are rejected by the service. Use timeoutMs for slow pages and debug true for sanitized proxy/browser diagnostics.",
     inputSchema: CaptureSerpPageSnapshotsInputSchema,
+    outputSchema: CaptureSerpPageSnapshotsOutputSchema,
     annotations: liveWebToolAnnotations("SERP Intelligence Page Snapshots")
-  }, async (input) => executor.captureSerpPageSnapshots(input));
+  }, async (input) => formatCaptureSerpPageSnapshots(await executor.captureSerpPageSnapshots(input), input));
 }
 var import_hono9, import_webStandardStreamableHttp, mcpApp;
 var init_mcp_routes = __esm({
@@ -23518,6 +24189,7 @@ var init_server = __esm({
     init_rates();
     init_billing_schemas();
     init_server_schemas();
+    init_schemas3();
     init_credit_operations();
     init_harvest();
     init_harvest_problems();
@@ -23747,7 +24419,7 @@ var init_server = __esm({
         gl: body.gl ?? "us",
         hl: body.hl ?? "en",
         device: body.device ?? "desktop",
-        proxyMode: body.proxyMode ?? "location",
+        proxyMode: body.proxyMode ?? DEFAULT_PROXY_MODE,
         proxyZip: body.proxyZip,
         debug: body.debug ?? false,
         serpOnly: body.serpOnly ?? false,
@@ -23783,7 +24455,7 @@ var init_server = __esm({
         gl: body.gl ?? "us",
         hl: body.hl ?? "en",
         device: body.device ?? "desktop",
-        proxyMode: body.proxyMode ?? "location",
+        proxyMode: body.proxyMode ?? DEFAULT_PROXY_MODE,
         proxyZip: body.proxyZip,
         debug: body.debug ?? false,
         serpOnly: body.serpOnly ?? false,