@enerlence/suntropy-cli 0.11.8 → 0.12.0

package/dist/bin/suntropy.js

@@ -69,7 +69,8 @@ var SERVICE_PATHS = {
   templates: "/templates",
   profiles: "/profiles",
   periods: "/periods",
-  notifications: "/notifications"
+  notifications: "/notifications",
+  satvolt: "/satvolt"
 };
 var LOCAL_PORTS = {
   security: 8080,
@@ -77,7 +78,8 @@ var LOCAL_PORTS = {
   templates: 8090,
   profiles: 8085,
   periods: 8084,
-  notifications: 8093
+  notifications: 8093,
+  satvolt: 8099
 };
 function getServiceUrl(baseServer, service) {
   if (baseServer.includes("localhost") || baseServer.match(/:\d+$/)) {
@@ -266,6 +268,7 @@ function outputError(err) {
     const apiErr = err;
     const out = { error: true, message: apiErr.message || "Unknown error" };
     if (apiErr.status) out.status = apiErr.status;
+    if (apiErr.code) out.code = apiErr.code;
     if (apiErr.details) out.details = apiErr.details;
     process.stderr.write(JSON.stringify(out) + "\n");
   } else {
@@ -1240,8 +1243,8 @@ function getGlobalOpts3(cmd) {
 function parseData(data) {
   if (!data) return void 0;
   if (data === "-") {
-    const { readFileSync: readFileSync6 } = __require("fs");
-    const input = readFileSync6(0, "utf-8");
+    const { readFileSync: readFileSync7 } = __require("fs");
+    const input = readFileSync7(0, "utf-8");
     return JSON.parse(input);
   }
   return JSON.parse(data);
@@ -1324,7 +1327,11 @@ function createResourceCommands(cfg) {
       const client = createServiceClient(service, global);
       const body = parseData(opts.data);
       if (cfg.putBodyOnly) {
-        const res = await client.put(cfg.basePath, { ...body, [cfg.idField]: id });
+        const numericId = Number(id);
+        const res = await client.put(cfg.basePath, {
+          ...body,
+          [cfg.idField]: Number.isFinite(numericId) ? numericId : id
+        });
         output(res.data, global);
       } else {
         const res = await client.put(`${cfg.basePath}/${id}`, body);
@@ -1386,8 +1393,8 @@ function getGlobalOpts4(cmd) {
 }
 function parseData2(data) {
   if (data === "-") {
-    const { readFileSync: readFileSync6 } = __require("fs");
-    return JSON.parse(readFileSync6(0, "utf-8"));
+    const { readFileSync: readFileSync7 } = __require("fs");
+    return JSON.parse(readFileSync7(0, "utf-8"));
   }
   return JSON.parse(data);
 }
@@ -2141,6 +2148,21 @@ function updateStudy(filePath, updater) {
     cascadeResets
   };
 }
+function distributePanels(surfaces, total) {
+  if (!surfaces.length) return [];
+  if (surfaces.length === 1) return [total];
+  const current = surfaces.map((s) => Number(s.panelNumber) || 0);
+  const currentTotal = current.reduce((a, b) => a + b, 0);
+  const weights = currentTotal > 0 ? current.map((n) => n / currentTotal) : surfaces.map(() => 1 / surfaces.length);
+  const counts = weights.map((w) => Math.floor(total * w));
+  let remainder = total - counts.reduce((a, b) => a + b, 0);
+  const order = counts.map((n, i) => ({ n, i })).sort((a, b) => b.n - a.n).map((x) => x.i);
+  for (let k = 0; remainder > 0; k = (k + 1) % order.length) {
+    counts[order[k]] += 1;
+    remainder -= 1;
+  }
+  return counts;
+}
 function deepMerge(target, source) {
   for (const key of Object.keys(source)) {
     const sv = source[key];
@@ -2559,26 +2581,45 @@ Examples:
     }
   });
   set.command("panel").description(
-    'Set solar panel for the study. Auto-sets peakPowerIntroductionMode to "solarPanel".\nFetches full panel data from inventory.\nExample: suntropy studies set panel --file study.json --panel-id 456 --panels-count 12'
-  ).option("--file <path>", "Study file path").requiredOption("--panel-id <n>", "Solar panel ID from inventory").option("--panels-count <n>", "Number of panels").action(async (opts) => {
+    'Set solar panel for the study. Auto-sets peakPowerIntroductionMode to "solarPanel".\nFetches full panel data from inventory.\n--panels-count is the TOTAL for the study: it is spread over the surfaces keeping\ntheir current proportion (use --surface-index to target a single surface).\nThe response lists the resulting panelNumber per surface.\nExample: suntropy studies set panel --file study.json --panel-id 456 --panels-count 12'
+  ).option("--file <path>", "Study file path").requiredOption("--panel-id <n>", "Solar panel ID from inventory").option("--panels-count <n>", "TOTAL number of panels of the study, spread over its surfaces keeping their current proportion").option("--surface-index <n>", "Apply --panels-count to this surface only (0-based) instead of spreading it").action(async (opts) => {
     try {
       const global = getGlobalOpts7(studies);
       const solarClient = createServiceClient("solar", global);
       const panelRes = await solarClient.get(`/solar-panels/${opts.panelId}`);
       const panel = panelRes.data;
+      let distribution = [];
       const result = updateStudy(resolveFile(opts), (study) => {
         study.solarPanel = panel;
         study.peakPowerIntroductionMode = "solarPanel";
         study.solarKit = void 0;
         if (opts.panelsCount) {
           const surfaces = study.surfaces;
+          const total = parseInt(opts.panelsCount);
           if (surfaces?.length) {
-            surfaces[0].panelNumber = parseInt(opts.panelsCount);
+            if (opts.surfaceIndex !== void 0) {
+              const idx = parseInt(opts.surfaceIndex);
+              if (!Number.isInteger(idx) || idx < 0 || idx >= surfaces.length) {
+                throw new Error(
+                  `--surface-index ${opts.surfaceIndex} is out of range: the study has ${surfaces.length} surface(s)`
+                );
+              }
+              surfaces[idx].panelNumber = total;
+            } else {
+              const counts = distributePanels(surfaces, total);
+              surfaces.forEach((surface, i) => {
+                surface.panelNumber = counts[i];
+              });
+            }
+            distribution = surfaces.map((surface, i) => ({
+              surfaceIndex: i,
+              panelNumber: Number(surface.panelNumber) || 0
+            }));
           }
         }
         return void 0;
       });
-      output(result, global);
+      output(distribution.length ? { ...result, surfaces: distribution } : result, global);
     } catch (err) {
       outputError(handleApiError(err));
     }
@@ -2610,7 +2651,7 @@ Examples:
     }
   });
   set.command("inverter").description(
-    "Set inverter(s) for the study (when using solarPanel mode).\nExample: suntropy studies set inverter --file study.json --inverter-id 789"
+    "Set inverter(s) for the study (when using solarPanel mode).\nREPLACES the whole list: pass every inverter of the installation, comma-separated,\nrepeating an id as many times as units there are. The response reports how many\nwere there before and how many are there now.\nExample: suntropy studies set inverter --file study.json --inverter-id 789,789"
   ).option("--file <path>", "Study file path").requiredOption("--inverter-id <ids>", "Inverter ID(s), comma-separated for multiple").action(async (opts) => {
     try {
       const global = getGlobalOpts7(studies);
@@ -2621,11 +2662,13 @@ Examples:
         const res = await solarClient.get(`/solar-inverter/${id}`);
         inverters.push(res.data);
       }
+      let previousCount = 0;
       const result = updateStudy(resolveFile(opts), (study) => {
+        previousCount = study.solarInverters?.length ?? 0;
         study.solarInverters = inverters;
         return void 0;
       });
-      output(result, global);
+      output({ ...result, inverters: { before: previousCount, after: inverters.length } }, global);
     } catch (err) {
       outputError(handleApiError(err));
     }
@@ -3752,13 +3795,13 @@ function getGlobalOpts9(cmd) {
   return root.opts();
 }
 function readStdin() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("end", () => resolve2(data));
     process.stdin.on("error", reject);
   });
 }
@@ -4051,13 +4094,13 @@ function getGlobalOpts11(cmd) {
   return root.opts();
 }
 function readStdin2() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("end", () => resolve2(data));
     process.stdin.on("error", reject);
   });
 }
@@ -4223,13 +4266,13 @@ function getGlobalOpts12(cmd) {
   return root.opts();
 }
 function readStdin3() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("end", () => resolve2(data));
     process.stdin.on("error", reject);
   });
 }
@@ -4324,13 +4367,13 @@ function getGlobalOpts13(cmd) {
   return root.opts();
 }
 function readStdin4() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("end", () => resolve2(data));
     process.stdin.on("error", reject);
   });
 }
@@ -4567,6 +4610,1152 @@ Examples:
   });
 }
 
+// src/commands/satvolt/api.ts
+import axios2 from "axios";
+import { readFileSync as readFileSync6 } from "fs";
+function getGlobalOpts17(cmd) {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  return root.opts();
+}
+var SATVOLT_DEV_BASE_URL = "https://api-dev.suntropy.domain.eu.axebow.cloud/satvolt";
+function resolveSatvoltBaseUrl(resolved) {
+  const override = process.env.SUNTROPY_SATVOLT_URL?.trim();
+  if (override) return override.replace(/\/+$/, "");
+  if (/^https?:\/\/(localhost|127\.0\.0\.1)([:/]|$)/.test(resolved)) return resolved;
+  return SATVOLT_DEV_BASE_URL;
+}
+function satvoltClient(global, timeout = 6e4) {
+  const client = createServiceClient("satvolt", global);
+  const base = resolveSatvoltBaseUrl(client.defaults.baseURL ?? "");
+  if (global.verbose && base !== client.defaults.baseURL) {
+    process.stderr.write(`\u2192 satvolt pinned to ${base} (preliminary testing phase)
+`);
+  }
+  client.defaults.baseURL = `${base}/api/v1`;
+  client.defaults.timeout = timeout;
+  return client;
+}
+async function call(client, method, path, options = {}) {
+  const res = await client.request({
+    method,
+    url: path,
+    params: dropEmpty(options.params),
+    data: options.data
+  });
+  return res.data?.data;
+}
+function dropEmpty(params) {
+  if (!params) return void 0;
+  return Object.fromEntries(
+    Object.entries(params).filter(([, v]) => v !== void 0 && v !== null && v !== "")
+  );
+}
+function satvoltError(err) {
+  if (axios2.isAxiosError(err)) {
+    let body = err.response?.data;
+    if (body instanceof ArrayBuffer || Buffer.isBuffer(body)) {
+      try {
+        body = JSON.parse(Buffer.from(body).toString("utf-8"));
+      } catch {
+        body = void 0;
+      }
+    }
+    const envelope = body;
+    if (envelope?.error) {
+      return {
+        error: true,
+        status: err.response?.status ?? 0,
+        code: envelope.error.code,
+        message: envelope.error.message || envelope.error.code || "Request failed",
+        details: envelope.error.details
+      };
+    }
+    return {
+      error: true,
+      status: err.response?.status ?? 0,
+      message: err.response?.status === 404 && !envelope ? "Endpoint not found: is the Satvolt public API deployed on this server?" : err.response?.statusText || err.message,
+      details: body
+    };
+  }
+  return { error: true, status: 0, message: err instanceof Error ? err.message : String(err) };
+}
+function readJsonArg(value, label) {
+  let raw;
+  if (value === "-") {
+    raw = readFileSync6(0, "utf-8");
+  } else if (value.startsWith("@")) {
+    raw = readFileSync6(value.slice(1), "utf-8");
+  } else {
+    raw = value;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${label} is not valid JSON: ${err.message}`);
+  }
+}
+function parseId(value, label = "id") {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${label} must be a positive integer, got "${value}"`);
+  }
+  return n;
+}
+function parseIntOption(value, label) {
+  if (value === void 0) return void 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`${label} must be a non-negative integer`);
+  return n;
+}
+function parseLatLng(value, label) {
+  const parts = value.split(",").map((p) => Number(p.trim()));
+  if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n))) {
+    throw new Error(`${label} must be "lat,lng", got "${value}"`);
+  }
+  return [parts[0], parts[1]];
+}
+
+// src/commands/satvolt/campaigns.ts
+import chalk2 from "chalk";
+var TERMINAL_CAMPAIGN_STATES = /* @__PURE__ */ new Set(["completed", "failed", "canceled"]);
+var CAMPAIGN_LIST_FIELDS = "idCampaign,name,state,source,totalLeads,maxLeads,leadsCompletionPercentage,creationTimestamp";
+function buildArea(opts) {
+  const given = ["circle", "polygon", "bounds"].filter((k) => opts[k] !== void 0);
+  if (given.length !== 1) {
+    throw new Error("Pass exactly one area: --circle <lat,lng> --radius <m> | --polygon <json|@file> | --bounds <nwLat,nwLng,seLat,seLng>");
+  }
+  if (opts.circle !== void 0) {
+    if (opts.radius === void 0) throw new Error("--circle requires --radius <meters>");
+    return {
+      type: "circle",
+      center: parseLatLng(opts.circle, "--circle"),
+      radiusMeters: Number(opts.radius)
+    };
+  }
+  if (opts.bounds !== void 0) {
+    const n = opts.bounds.split(",").map((p) => Number(p.trim()));
+    if (n.length !== 4 || n.some((x) => !Number.isFinite(x))) {
+      throw new Error('--bounds must be "nwLat,nwLng,seLat,seLng"');
+    }
+    return { type: "bounds", northWest: [n[0], n[1]], southEast: [n[2], n[3]] };
+  }
+  const parsed = readJsonArg(opts.polygon, "--polygon");
+  const geometry = parsed?.type === "Feature" ? parsed.geometry : parsed;
+  if (geometry?.type === "Polygon") {
+    const ring = geometry.coordinates?.[0];
+    if (!Array.isArray(ring)) throw new Error("GeoJSON Polygon has no outer ring");
+    return { type: "polygon", coordinates: ring.map(([lng, lat]) => [lat, lng]) };
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("--polygon must be an array of [lat,lng] points or a GeoJSON Polygon");
+  }
+  return { type: "polygon", coordinates: parsed };
+}
+function registerSatvoltCampaignCommands(satvolt) {
+  const campaigns = satvolt.command("campaigns").description("Satvolt campaigns: list, create from an area, start, reset, resume, usage, logs and funnel.");
+  campaigns.command("list").description(
+    'List campaigns, newest first.\nExamples:\n  suntropy satvolt campaigns list --state completed,inProgress\n  suntropy satvolt campaigns list --search "Alcobendas" --format human'
+  ).option("--limit <n>", "Max results (max 200)", "50").option("--offset <n>", "Skip results", "0").option("--search <text>", "Match name, region or input address").option("--state <states>", "Comma-separated campaign states (see: satvolt catalog states)").option("--source <source>", "maps | excel | campaign").action(async (opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const client = satvoltClient(global);
+      const page = await call(client, "get", "/campaigns", {
+        params: { limit: opts.limit, offset: opts.offset, search: opts.search, state: opts.state, source: opts.source }
+      });
+      const outOpts = { ...global, fields: global.fields ?? (global.format !== "json" ? CAMPAIGN_LIST_FIELDS : void 0) };
+      if (outOpts.format === "csv") output(page.items, outOpts);
+      else outputPaginated(page.items, page.total, page.limit, page.offset, outOpts);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("get <campaignId>").description("Campaign detail: area, lead counts by state and pipeline configuration.").action(async (campaignId) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await call(satvoltClient(global), "get", `/campaigns/${parseId(campaignId, "campaignId")}`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("create").summary("Create a Maps campaign over an area, optionally from a template or campaign.").description(
+    `Create a Maps campaign over an area. It stays queued unless --start is passed
+(same as the web app). Steps are the LEAD steps only: SECTORIZE, FIND_LEADS
+and COMPLETE are added by the backend, and missing dependencies are added too.
+
+Area (exactly one):
+  --circle <lat,lng> --radius <meters>   stored as a circle (100 m - 50 km)
+  --bounds <nwLat,nwLng,seLat,seLng>     rectangle
+  --polygon <json|@file|->               [[lat,lng],...] or GeoJSON; searched as its
+                                         bounding rectangle (a warning is returned)
+
+Examples:
+  suntropy satvolt campaigns create --name "Pol\xEDgono Cobo Calleja" \\
+    --circle 40.2597,-3.7545 --radius 1500 --max-leads 300 \\
+    --business-groups businesses --steps @steps.json
+  suntropy satvolt campaigns create --name "Test" --bounds 40.45,-3.70,40.44,-3.68 \\
+    --steps '[{"action":"FIND_ROOFTOP"},{"action":"SOLAR_ANALYSIS"}]' --start
+  suntropy satvolt campaigns create --data @campaign.json   (full request body)
+
+Base configuration (optional, one of them): steps, business groups, description,
+search query and lead limit come from it; any flag you pass wins.
+  --template <id|name>     a campaign template (see: satvolt templates list)
+  --from-campaign <id>     copy the pipeline of another Maps campaign
+  suntropy satvolt campaigns create --name "Sonda Hu\xE9var" --template "Greenvolt industria" \\
+    --circle 37.3509,-6.2757 --radius 5000 --max-leads 50`
+  ).option("--name <name>", "Campaign name").option("--template <idOrName>", "Base the campaign on a campaign template").option("--from-campaign <id>", "Base the campaign on the configuration of another Maps campaign").option("--description <text>", "Natural language description of the configuration").option("--circle <lat,lng>", "Circle center").option("--radius <meters>", "Circle radius in meters").option("--bounds <nwLat,nwLng,seLat,seLng>", "Rectangle corners").option("--polygon <json>", "Polygon points, GeoJSON, @file or - for stdin").option("--search-query <text>", "Use Places text search with this query instead of nearby search").option("--max-leads <n>", "Stop discovering leads after this many").option("--business-groups <ids>", "Comma-separated group ids (default: businesses). See: satvolt catalog business-groups").option("--steps <json>", "LEAD steps as JSON array, @file or -. See: satvolt catalog actions").option("--address <text>", "Reference address shown in the web app").option("--region <text>", "Region shown in the web app").option("--start", "Start the pipeline right after creating it (spends credits)").option("--data <json>", "Full request body (JSON, @file or -); flags override its fields").action(async (opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const body = opts.data ? readJsonArg(opts.data, "--data") : {};
+      if (opts.name) body.name = opts.name;
+      if (opts.circle !== void 0 || opts.polygon !== void 0 || opts.bounds !== void 0) {
+        body.area = buildArea(opts);
+      }
+      if (!body.name) throw new Error("--name is required");
+      if (!body.area) throw new Error("An area is required: --circle/--radius, --bounds or --polygon");
+      if (opts.template && opts.fromCampaign) throw new Error("Use either --template or --from-campaign, not both");
+      if (opts.template) body.templateId = opts.template;
+      if (opts.fromCampaign) body.fromCampaignId = parseId(opts.fromCampaign, "--from-campaign");
+      if (opts.description !== void 0) body.description = opts.description;
+      if (opts.searchQuery) body.searchQuery = opts.searchQuery;
+      if (opts.maxLeads !== void 0) body.maxLeads = parseIntOption(opts.maxLeads, "--max-leads");
+      if (opts.businessGroups) body.businessGroups = opts.businessGroups.split(",").map((s) => s.trim()).filter(Boolean);
+      if (opts.steps) body.steps = readJsonArg(opts.steps, "--steps");
+      if (opts.address) body.inputAddress = opts.address;
+      if (opts.region) body.region = opts.region;
+      if (opts.start) body.start = true;
+      const data = await call(satvoltClient(global), "post", "/campaigns", { data: body });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("delete <campaignId>").summary("Delete a campaign and everything it generated (irreversible, --yes).").description(
+    "Delete a campaign with its sectors, leads, step executions, pipeline configuration\nand queued jobs. Irreversible. Export tables of the campaign stop working.\nExample:\n  suntropy satvolt campaigns delete 63 --yes"
+  ).option("--yes", "Confirm the deletion (required)").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      if (!opts.yes) throw new Error("Deleting a campaign is irreversible. Re-run with --yes to confirm.");
+      const data = await call(satvoltClient(global), "delete", `/campaigns/${parseId(campaignId, "campaignId")}`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("start <campaignId>").description("Start the pipeline of a queued campaign (spends credits).").action(async (campaignId) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await call(satvoltClient(global), "post", `/campaigns/${parseId(campaignId, "campaignId")}/start`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("reset <campaignId>").summary("Relaunch a campaign from scratch: deletes its leads and results (--yes).").description(
+    "Relaunch a campaign from scratch: deletes its sectors, leads and processing data\nand returns it to queued, keeping the configuration. Excel/campaign-sourced\ncampaigns keep their imported leads. Irreversible.\nExample:\n  suntropy satvolt campaigns reset 59 --yes --start"
+  ).option("--start", "Start the pipeline again after resetting").option("--yes", "Confirm the reset (required)").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      if (!opts.yes) throw new Error("Reset deletes the campaign leads and results. Re-run with --yes to confirm.");
+      const data = await call(satvoltClient(global), "post", `/campaigns/${parseId(campaignId, "campaignId")}/reset`, {
+        params: { start: opts.start ? "true" : void 0 }
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("extend <campaignId>").summary("Get more leads from a finished Maps campaign without relaunching it.").description(
+    "Get more leads from a finished Maps campaign without relaunching it: raises (or\nremoves) its lead limit and searches again only in the sectors whose search was\ncut short. Existing leads are kept and only the new ones go through the pipeline\n(spends credits). `campaigns get` shows sectorSearch: incomplete + unknown > 0\nmeans more leads can still be found; 0 means the area is exhausted.\nCost: new leads x credits per lead (`campaigns usage` \u2192 avgCreditsPerLead). With\n--max-leads the new leads are at most the difference; with --no-limit estimate them\nfrom the leads found per sector so far.\nExamples:\n  suntropy satvolt campaigns extend 62 --max-leads 500\n  suntropy satvolt campaigns extend 62 --no-limit"
+  ).option("--max-leads <n>", "New lead limit (must be greater than the current number of leads)").option("--no-limit", "Remove the lead limit and search every pending sector fully").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const removeLimit = opts.limit === false;
+      if (removeLimit === (opts.maxLeads !== void 0)) {
+        throw new Error("Pass exactly one of --max-leads <n> or --no-limit.");
+      }
+      const maxLeads = removeLimit ? null : parseIntOption(opts.maxLeads, "--max-leads");
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/extend`, {
+        data: { maxLeads }
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("resume <campaignId>").summary("Append a new step at the end and run it over the existing leads.").description(
+    'Resume a finished campaign from a NEW step: appends it at the end of the pipeline\n(before COMPLETE) and runs it over the existing leads that reached the previous\nstep. Missing dependencies are added before it. If the step cannot run, the\nconfiguration change is rolled back. --config is only the config object of the step\n(see configSchema in `satvolt catalog actions`), not { action, config }.\nCost: leads that reached the last step (`campaigns funnel`) x creditCost of the action.\nExamples:\n  suntropy satvolt campaigns resume 59 --action ESTIMATE_CONSUMPTION --config \'{"tariffTemplate":"3.0TD"}\'\n  suntropy satvolt campaigns resume 59 --action AI_AGENT \\\n    --config \'{"customName":"Web corporativa","agentId":"<id from catalog ai-agents>","outputKey":"web"}\''
+  ).requiredOption("--action <ACTION>", "Action to add (see: satvolt catalog actions)").option("--config <json>", "Step config as JSON, @file or -").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const step = { action: String(opts.action).toUpperCase() };
+      if (opts.config) step.config = readJsonArg(opts.config, "--config");
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/resume`, {
+        data: { step }
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("usage <campaignId>").description(
+    "Credits consumed by the campaign, as shown in the Usage tab: total, per lead\naverage and per step. --by-lead adds the per-lead breakdown."
+  ).option("--by-lead", "Include the per-lead breakdown").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await call(satvoltClient(global, 12e4), "get", `/campaigns/${parseId(campaignId, "campaignId")}/usage`, {
+        params: { include: opts.byLead ? "leads" : void 0 }
+      });
+      if (global.format === "human" || global.format === "csv") {
+        if (global.format === "human") {
+          process.stderr.write(
+            chalk2.bold(`Total ${data.totalCredits} credits \xB7 ${data.totalLeads} leads \xB7 ${data.avgCreditsPerLead} per lead
+
+`)
+          );
+        }
+        output(data.byStep, global);
+        return;
+      }
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("funnel <campaignId>").summary("Leads per pipeline step, by execution or by success criteria").description(
+    "Funnel of the campaign: for each LEAD step, how many leads reached it and how many\nsucceeded, failed, were skipped, are processing (async) or still pending, plus\nthe lead counts by state.\n\n--mode success shows how many leads the step actually brought data for, which is\nnot the same thing: an agent can finish without error answering that it found\nnothing. It uses the `successIf` paths configured on each step, evaluated against\nthe lead's current data \u2014 change the criteria and the numbers change, with no\nre-run. Steps without criteria fall back to their successful executions.\nExamples:\n  suntropy satvolt campaigns funnel 62\n  suntropy satvolt campaigns funnel 62 --mode success"
+  ).option("--mode <mode>", "execution (default) | success", "execution").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const mode = String(opts.mode || "execution").toLowerCase();
+      if (mode !== "execution" && mode !== "success") {
+        outputError({ code: "INVALID_MODE", message: "--mode must be execution or success" });
+        return;
+      }
+      const data = await call(satvoltClient(global, 12e4), "get", `/campaigns/${parseId(campaignId, "campaignId")}/funnel`);
+      if (global.format === "human" || global.format === "csv") {
+        output(
+          (data.steps ?? []).map(
+            (s) => mode === "success" ? {
+              step: s.name,
+              action: s.action,
+              reached: s.reached,
+              withData: s.criteria ? s.criteria.met : s.success,
+              pctOfTotal: s.criteria ? s.criteria.metPct : s.reachedPct,
+              missingData: s.criteria ? s.criteria.unmet : "",
+              retries: s.criteria?.maxRetries || "",
+              successIf: s.criteria ? s.criteria.paths.join(", ") : "(no criteria)"
+            } : {
+              step: s.name,
+              action: s.action,
+              reached: s.reached,
+              pctOfTotal: s.reachedPct,
+              success: s.success,
+              failure: s.failure,
+              skipped: s.skipped,
+              processing: s.processing,
+              pending: s.pending
+            }
+          ),
+          global
+        );
+        return;
+      }
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("logs <campaignId>").description(
+    "Campaign processing logs (kept 30 days, last 5000 entries).\n--follow keeps polling and stops by itself when the campaign reaches a final state.\nExamples:\n  suntropy satvolt campaigns logs 59 --level error\n  suntropy satvolt campaigns logs 59 --follow --format human"
+  ).option("--limit <n>", "Max entries (max 5000)", "500").option("--since <ts>", "Only entries after this epoch-ms timestamp (use lastTs from a previous call)").option("--level <level>", "debug | log | warn | error").option("--follow", "Poll for new entries until the campaign finishes").option("--interval <seconds>", "Polling interval with --follow", "3").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const id = parseId(campaignId, "campaignId");
+      const client = satvoltClient(global);
+      const fetchLogs = (sinceTs) => call(client, "get", `/campaigns/${id}/logs`, {
+        params: { limit: opts.limit, sinceTs, level: opts.level }
+      });
+      const printEntries = (entries) => {
+        for (const e of entries) {
+          if (global.format === "human") {
+            const color = e.level === "error" ? chalk2.red : e.level === "warn" ? chalk2.yellow : chalk2.dim;
+            process.stdout.write(`${chalk2.dim(new Date(e.ts).toISOString())} ${color(e.level.padEnd(5))} ${e.source}: ${e.message}
+`);
+          } else {
+            process.stdout.write(JSON.stringify(e) + "\n");
+          }
+        }
+      };
+      const first = await fetchLogs(opts.since);
+      if (!opts.follow) {
+        if (global.format === "human") printEntries(first.entries);
+        else output(first, global);
+        return;
+      }
+      printEntries(first.entries);
+      let lastTs = first.lastTs;
+      const intervalMs = Math.max(1, Number(opts.interval) || 3) * 1e3;
+      for (; ; ) {
+        const campaign = await call(client, "get", `/campaigns/${id}`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+        const next = await fetchLogs(lastTs ?? void 0);
+        printEntries(next.entries);
+        lastTs = next.lastTs ?? lastTs;
+        if (TERMINAL_CAMPAIGN_STATES.has(campaign.state)) {
+          process.stderr.write(`Campaign ${id} is ${campaign.state}; stopped following.
+`);
+          return;
+        }
+      }
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+
+// src/commands/satvolt/pipeline.ts
+var STEP_LIST_FIELDS = "index,uid,action,name,disable,creditCost,executedLeads,runnable,reason";
+async function patchSteps(cmd, campaignId, steps) {
+  const global = getGlobalOpts17(cmd);
+  const data = await call(satvoltClient(global), "patch", `/campaigns/${parseId(campaignId, "campaignId")}/configuration`, {
+    data: { steps }
+  });
+  output(data, global);
+}
+function registerSatvoltPipelineCommands(satvolt) {
+  const config = satvolt.command("config").summary("Pipeline configuration of a campaign as JSON (get, update, patch).").description(
+    "Pipeline configuration of a campaign as JSON.\nWorkflow: config get > edit the JSON > config update (full) or config patch (partial)."
+  );
+  config.command("get <campaignId>").description(
+    "Get the configuration: source, businessGroups, description and steps\n(uid, action, target, disable, structural, config).\nExample:\n  suntropy satvolt config get 59 --save pipeline.json"
+  ).action(async (campaignId) => {
+    const global = getGlobalOpts17(config);
+    try {
+      const data = await call(satvoltClient(global), "get", `/campaigns/${parseId(campaignId, "campaignId")}/configuration`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  config.command("update <campaignId>").description(
+    "Replace the pipeline (PUT). The body is { steps, businessGroups?, description? } where\nsteps is the FULL list of editable steps in order. Structural steps (SECTORIZE,\nFIND_LEADS, IMPORT_LEADS, COMPLETE) are ignored in the input and kept by the backend,\nso the output of `config get` can be sent back as is. Steps without uid get one;\nconfig is validated against each action schema (satvolt catalog actions).\nExample:\n  suntropy satvolt config update 59 --data @pipeline.json"
+  ).requiredOption("--data <json>", "Configuration JSON, @file or -").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(config);
+    try {
+      const body = readJsonArg(opts.data, "--data");
+      const data = await call(satvoltClient(global), "put", `/campaigns/${parseId(campaignId, "campaignId")}/configuration`, {
+        data: body
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  config.command("patch <campaignId>").description(
+    `Partial change (PATCH). Body: { steps?, businessGroups?, description? }.
+Each item in steps:
+  { "uid": "<existing>", "config": {...} }   merge config (JSON Merge Patch: null resets a key to its default)
+  { "uid": "<existing>", "replaceConfig": true, "config": {...} }   replace config
+  { "uid": "<existing>", "disable": true }
+  { "uid": "<existing>", "after": "<uid>" }  move (also "before")
+  { "uid": "<existing>", "remove": true }
+  { "action": "QUALIFY", "config": {...} }   add (before COMPLETE, or before/after a uid)
+Example:
+  suntropy satvolt config patch 59 --data '{"steps":[{"uid":"d3f2849c52281f36","config":{"enableWebSearch":true}}]}'`
+  ).requiredOption("--data <json>", "Patch JSON, @file or -").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(config);
+    try {
+      const body = readJsonArg(opts.data, "--data");
+      const data = await call(satvoltClient(global), "patch", `/campaigns/${parseId(campaignId, "campaignId")}/configuration`, {
+        data: body
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  const steps = satvolt.command("steps").description("Steps of a campaign pipeline: list with run status, add, set, remove and run.");
+  steps.command("list <campaignId>").description(
+    "List the pipeline steps in order with catalog data (name, credits, async) and run\nstatus: executedLeads, and runnable/reason for steps no lead has executed yet."
+  ).action(async (campaignId) => {
+    const global = getGlobalOpts17(steps);
+    try {
+      const data = await call(satvoltClient(global), "get", `/campaigns/${parseId(campaignId, "campaignId")}/steps`);
+      if (global.format === "json" && !global.fields) {
+        output(data, global);
+      } else {
+        output(data.steps, { ...global, fields: global.fields ?? STEP_LIST_FIELDS });
+      }
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  steps.command("add <campaignId>").description(
+    `Add a step. Goes before COMPLETE unless --before/--after is given. Config defaults
+from the action schema are filled in and missing dependencies are added.
+Example:
+  suntropy satvolt steps add 59 --action QUALIFY --config '{"qualificationDefinition":"..."}'`
+  ).requiredOption("--action <ACTION>", "Action (see: satvolt catalog actions)").option("--config <json>", "Step config as JSON, @file or -").option("--uid <uid>", "Explicit uid for the new step").option("--before <uid>", "Insert before this step").option("--after <uid>", "Insert after this step").option("--disabled", "Add it disabled").action(async (campaignId, opts) => {
+    try {
+      const step = { action: String(opts.action).toUpperCase() };
+      if (opts.config) step.config = readJsonArg(opts.config, "--config");
+      if (opts.uid) step.uid = opts.uid;
+      if (opts.before) step.before = opts.before;
+      if (opts.after) step.after = opts.after;
+      if (opts.disabled) step.disable = true;
+      await patchSteps(steps, campaignId, [step]);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  steps.command("set <campaignId> <stepUid>").description(
+    `Change one step: merge --config into its config (null resets a key to its default), or replace it
+with --replace-config; enable/disable; move with --before/--after.
+
+Every step also takes two common config keys, whatever its action:
+  skipIfEmpty  path that, when empty, skips the step for that lead
+  successIf    paths the step must fill for its result to count as useful, relative
+               to what the step writes (an agent: relative to its response), or
+               absolute with fullData./lead.  Feeds \`campaigns funnel --mode success\`
+  maxRetries   0-5. Repeats the step while successIf is not met. Credits are charged
+               once per step, not per attempt; if the last attempt still has no data
+               the lead carries on to the next step.
+Examples:
+  suntropy satvolt steps set 59 95161b8b080180e4 --config '{"outputKey":"company"}'
+  suntropy satvolt steps set 62 7f3edaf055d60627 --config '{"successIf":["response.linkedinUrl"],"maxRetries":2}'`
+  ).option("--config <json>", "Config JSON, @file or -").option("--replace-config", "Replace the whole config instead of merging").option("--enable", "Enable the step").option("--disable", "Disable the step").option("--before <uid>", "Move before this step").option("--after <uid>", "Move after this step").action(async (campaignId, stepUid, opts) => {
+    try {
+      if (opts.enable && opts.disable) throw new Error("Use either --enable or --disable");
+      const step = { uid: stepUid };
+      if (opts.config) step.config = readJsonArg(opts.config, "--config");
+      if (opts.replaceConfig) step.replaceConfig = true;
+      if (opts.enable) step.disable = false;
+      if (opts.disable) step.disable = true;
+      if (opts.before) step.before = opts.before;
+      if (opts.after) step.after = opts.after;
+      if (Object.keys(step).length === 1) throw new Error("Nothing to change: pass --config, --enable/--disable or --before/--after");
+      await patchSteps(steps, campaignId, [step]);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  steps.command("remove <campaignId> <stepUid>").description("Remove a step from the pipeline (results already stored on leads are kept).").action(async (campaignId, stepUid) => {
+    try {
+      await patchSteps(steps, campaignId, [{ uid: stepUid, remove: true }]);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  steps.command("run <campaignId> <stepUid>").description(
+    "Run a step that no lead has executed yet over the existing leads, then continue the\npipeline to the end. Only the first never-executed step with nothing executed\nafter it is runnable (see runnable/reason in `steps list`). Spends credits."
+  ).action(async (campaignId, stepUid) => {
+    const global = getGlobalOpts17(steps);
+    try {
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/steps/${encodeURIComponent(stepUid)}/run`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+
+// src/commands/satvolt/fields.ts
+var pct = (v) => v === null || v === void 0 ? "-" : `${Math.round(v * 100)}%`;
+function flatten(catalog, onlyStep) {
+  const rows = [];
+  const push = (group, f, source = f.source) => rows.push({ group, path: f.path, label: f.label, type: f.type, source, coverage: pct(f.coverage), example: f.example ?? null });
+  if (!onlyStep) {
+    for (const f of catalog.lead) push("Lead", f, "lead");
+    for (const f of catalog.synthetic) push("Lead", f, "synthetic");
+  }
+  for (const step of catalog.steps) {
+    const group = `${step.name} [${step.action}]`;
+    for (const f of step.fields) push(group, f);
+    for (const d of step.dynamic) {
+      rows.push({
+        group,
+        path: `${d.path}.*`,
+        label: "-",
+        type: "-",
+        source: "dynamic",
+        coverage: "-",
+        example: d.inferredFrom ? `${d.description} Fields above inferred from campaign ${d.inferredFrom.campaignId}.` : d.description
+      });
+    }
+  }
+  if (!onlyStep) for (const f of catalog.other) push("Other (no current step)", f);
+  return rows;
+}
+function registerFieldsCommand(parent, note) {
+  parent.command("fields <campaignId>").summary("Fields for export table columns, grouped by pipeline step.").description(
+    "Data paths for export table columns, grouped by pipeline step. Each step lists the\nfields it declares (available before the campaign has data) plus the ones seen in a\nsample of leads, with column type, coverage and an example. AI agent responses depend\non the agent: until this campaign has answers they are inferred from another campaign\nof yours with the same agent (source: otherCampaign).\nsource: catalog (declared by the step) | observed (seen in leads) | otherCampaign |\n        dynamic (shape depends on the step config) | lead | synthetic\n--search matches path and label (labels are in English: consumption, email\u2026).\n" + (note ? `${note}
+` : "") + "Examples:\n  suntropy satvolt export-tables fields 59 --format human\n  suntropy satvolt export-tables fields 59 --step QUALIFY --format human\n  suntropy satvolt export-tables fields 59 --search cnae --format human"
+  ).option("--sample <n>", "Leads to sample (max 100)", "25").option("--step <step>", "Only this step: uid, ACTION (if unique), step name or fullData key").option("--search <text>", "Only paths or labels containing this text").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(parent);
+    try {
+      const catalog = await call(
+        satvoltClient(global, 12e4),
+        "get",
+        `/campaigns/${parseId(campaignId, "campaignId")}/fields`,
+        { params: { sample: opts.sample, step: opts.step } }
+      );
+      const search = typeof opts.search === "string" ? opts.search.toLowerCase() : void 0;
+      if (global.format === "json") {
+        if (search) {
+          const match = (f) => f.path.toLowerCase().includes(search) || f.label?.toLowerCase().includes(search);
+          catalog.lead = catalog.lead.filter(match);
+          catalog.synthetic = catalog.synthetic.filter(match);
+          catalog.other = catalog.other.filter(match);
+          catalog.steps = catalog.steps.map((s) => ({ ...s, fields: s.fields.filter(match) })).filter((s) => s.fields.length > 0);
+        }
+        output(catalog, global);
+        return;
+      }
+      let rows = flatten(catalog, Boolean(opts.step));
+      if (search) {
+        rows = rows.filter(
+          (r) => String(r.path).toLowerCase().includes(search) || String(r.label).toLowerCase().includes(search)
+        );
+      }
+      output(rows, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+
+// src/commands/satvolt/leads.ts
+var LEAD_LIST_FIELDS = "idLead,commercialName,state,stateError,lastAction,address,phone,url";
+function registerSatvoltLeadCommands(satvolt) {
+  const leads = satvolt.command("leads").description("Leads of a campaign: paginated list with state, filters by step, detail and available data fields.");
+  leads.command("list <campaignId>").description(
+    'List leads with their state (plus stateError, last action and QUALIFY verdicts).\n\nFilters:\n  --name <text>          commercial name contains (like the web table)\n  --search <text>        name, address, phone, place id or reference\n  --state <a,b>          lead states (see: satvolt catalog states)\n  --step <step>          pipeline step: uid, ACTION (if it appears once), step name\n                         ("Buscador de CIF") or fullData key (cif)\n  --step-status <s>      reached (default) | success | failure | skipped | processing | pending\n\nExamples:\n  suntropy satvolt leads list 59 --name "logistica" --limit 25\n  suntropy satvolt leads list 59 --step QUALIFY --step-status failure\n  suntropy satvolt leads list 59 --step 95161b8b080180e4 --step-status pending --format csv'
+  ).option("--limit <n>", "Page size (max 200)", "25").option("--offset <n>", "Skip results", "0").option("--page <n>", "Page number (1-based); overrides --offset").option("--name <text>", "Commercial name contains").option("--search <text>", "Broad search").option("--state <states>", "Comma-separated lead states").option("--step <step>", "Filter by pipeline step: uid, ACTION (if unique), step name or fullData key").option("--step-status <status>", "Status in that step").option("--with-steps", "Include the status of every LEAD step on each lead").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(leads);
+    try {
+      const limit = Number(opts.limit);
+      const offset = opts.page ? (Math.max(1, Number(opts.page)) - 1) * limit : Number(opts.offset);
+      const page = await call(satvoltClient(global), "get", `/campaigns/${parseId(campaignId, "campaignId")}/leads`, {
+        params: {
+          limit,
+          offset,
+          name: opts.name,
+          search: opts.search,
+          state: opts.state,
+          step: opts.step,
+          stepStatus: opts.stepStatus,
+          include: opts.withSteps ? "steps" : void 0
+        }
+      });
+      const outOpts = { ...global, fields: global.fields ?? (global.format !== "json" ? LEAD_LIST_FIELDS : void 0) };
+      if (outOpts.format === "csv") output(page.items, outOpts);
+      else outputPaginated(page.items, page.total, page.limit, page.offset, outOpts);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  leads.command("get <campaignId> <leadId>").description(
+    "Lead detail: columns, status of each pipeline step, state history and the list of\nfullData keys. --full-data adds the enriched data (all of it, or only some keys).\nExamples:\n  suntropy satvolt leads get 59 1216\n  suntropy satvolt leads get 59 1216 --full-data consumptionEstimate,solarPanelAnalysis"
+  ).option("--full-data [keys]", "Include fullData (optionally comma-separated top-level keys)").action(async (campaignId, leadId, opts) => {
+    const global = getGlobalOpts17(leads);
+    try {
+      const fullData = opts.fullData === true ? "true" : opts.fullData;
+      const data = await call(
+        satvoltClient(global),
+        "get",
+        `/campaigns/${parseId(campaignId, "campaignId")}/leads/${parseId(leadId, "leadId")}`,
+        { params: { fullData } }
+      );
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  leads.command("full-data <campaignId> <leadId>").summary("Only the enriched data of a lead (all, some keys or one path).").description(
+    "Print only the enriched data (fullData) of a lead, optionally a subset of keys or a\nsingle nested path.\nExamples:\n  suntropy satvolt leads full-data 62 2078\n  suntropy satvolt leads full-data 62 2078 --keys consumptionEstimate,cif\n  suntropy satvolt leads full-data 62 2078 --path cif.response.extras.cnae"
+  ).option("--keys <keys>", "Comma-separated top-level keys").option("--path <dotted.path>", "Return the value at this path inside fullData").action(async (campaignId, leadId, opts) => {
+    const global = getGlobalOpts17(leads);
+    try {
+      const topKey = opts.path ? String(opts.path).split(".")[0] : void 0;
+      const data = await call(
+        satvoltClient(global),
+        "get",
+        `/campaigns/${parseId(campaignId, "campaignId")}/leads/${parseId(leadId, "leadId")}`,
+        { params: { fullData: topKey ?? opts.keys ?? "true" } }
+      );
+      let value = data.fullData ?? {};
+      if (opts.path) {
+        for (const part of String(opts.path).split(".")) {
+          value = value && typeof value === "object" ? value[part] : void 0;
+        }
+        if (value === void 0) throw new Error(`Path "${opts.path}" not found in the fullData of lead ${leadId}`);
+      }
+      output(value, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  leads.command("run-step <campaignId> <leadId> <step>").summary("Run one pipeline step on a single lead (only that step, or --continue).").description(
+    "Run one pipeline step on a single lead, through the same queue as the pipeline.\nStep: uid, action if it appears once, step name or fullData key (e.g. cif).\nSpends the credits of that step (a failed or skipped run is free).\n  default       only that step: later steps are not queued and a completed or\n                unqualified lead keeps its state (except when re-running QUALIFY)\n  --continue    continue the pipeline from that step (later steps run again)\n  --force       skip the check that the lead completed the step dependencies\nExamples:\n  suntropy satvolt leads run-step 62 2034 ESTIMATE_CONSUMPTION\n  suntropy satvolt leads run-step 62 2081 f8771dae3f963702 --continue"
+  ).option("--continue", "Continue the pipeline after the step").option("--force", "Run even if the lead has not completed the step dependencies").action(async (campaignId, leadId, step, opts) => {
+    const global = getGlobalOpts17(leads);
+    try {
+      const data = await call(
+        satvoltClient(global),
+        "post",
+        `/campaigns/${parseId(campaignId, "campaignId")}/leads/${parseId(leadId, "leadId")}/steps/${encodeURIComponent(step)}/run`,
+        { data: { mode: opts.continue ? "continue" : "only", force: opts.force === true } }
+      );
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  registerFieldsCommand(leads, "Same as `satvolt export-tables fields`.");
+}
+
+// src/commands/satvolt/export-tables.ts
+import { writeFileSync as writeFileSync5 } from "fs";
+import { resolve } from "path";
+function parseColumns(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[") || trimmed.startsWith("@") || trimmed === "-") {
+    const parsed = readJsonArg(value, "--columns");
+    if (!Array.isArray(parsed)) throw new Error("--columns JSON must be an array");
+    return parsed;
+  }
+  return trimmed.split(";").map((part) => {
+    const m = /^(.+?)=([^:]+)(?::(string|number|boolean|date|url))?$/.exec(part.trim());
+    if (!m) throw new Error(`Invalid column "${part}". Use "Label=path[:type]" separated by ";" or a JSON array`);
+    return { label: m[1].trim(), path: m[2].trim(), ...m[3] ? { type: m[3] } : {} };
+  });
+}
+function registerSatvoltExportTableCommands(satvolt) {
+  const tables = satvolt.command("export-tables").summary("Export tables: column sets over lead data, paged reads and XLSX/CSV downloads.").description(
+    "Export tables of a campaign: named column sets over lead data, readable page by page\nand downloadable as XLSX or CSV. Column paths: lead.<column>, fullData.<path> and\nsynthetic.googleMapsUrl. `export-tables fields <campaignId>` lists them by pipeline step."
+  );
+  registerFieldsCommand(tables, "Same as `satvolt leads fields`.");
+  tables.command("list <campaignId>").description("List the export tables of a campaign.").action(async (campaignId) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const data = await call(satvoltClient(global), "get", `/campaigns/${parseId(campaignId, "campaignId")}/export-tables`);
+      output(global.format === "json" ? data : data.map((t) => ({ ...t, columns: t.columns.length })), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("get <tableId>").description("Get an export table with its columns.").action(async (tableId) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      output(await call(satvoltClient(global), "get", `/export-tables/${tableId}`), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("create <campaignId>").summary("Create an export table with its columns.").description(
+    'Create an export table. Column ids are generated when omitted. Without a type, the\ncolumn takes the one declared by the step that writes the path, or string.\nFind paths with: suntropy satvolt export-tables fields <campaignId>\nExamples:\n  suntropy satvolt export-tables create 59 --name "CRM" \\\n    --columns "Empresa=lead.commercialName;Web=lead.url;Consumo kWh=fullData.consumptionEstimate.annualKwh;Maps=synthetic.googleMapsUrl"\nfullData paths depend on the steps of each campaign (an AI agent with outputKey "cif"\nwrites fullData.cif.response.<field>): take them from `export-tables fields`.\nSynthetic paths: synthetic.googleMapsUrl (Google Maps link built from the coordinates).\nThe response is the table: { id, campaignId, name, description, columns, warnings }.\n  suntropy satvolt export-tables create 59 --data @table.json   ({ name, description?, columns })'
+  ).option("--name <name>", "Table name").option("--description <text>", "Description").option("--columns <spec>", '"Label=path[:type];..." or JSON array, @file or -').option("--data <json>", "Full body as JSON, @file or -; flags override its fields").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const body = opts.data ? readJsonArg(opts.data, "--data") : {};
+      if (opts.name) body.name = opts.name;
+      if (opts.description) body.description = opts.description;
+      if (opts.columns) body.columns = parseColumns(opts.columns);
+      if (!body.name) throw new Error("--name is required");
+      if (!Array.isArray(body.columns) || body.columns.length === 0) throw new Error("--columns is required");
+      const data = await call(satvoltClient(global), "post", `/campaigns/${parseId(campaignId, "campaignId")}/export-tables`, { data: body });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("update <tableId>").description(
+    "Replace a table (PUT): name and the full columns list are required. Keep column ids\nfrom `export-tables get` to preserve them.\nExample:\n  suntropy satvolt export-tables get 6650... --save table.json  # edit, then:\n  suntropy satvolt export-tables update 6650... --data @table.json"
+  ).requiredOption("--data <json>", "{ name, description?, columns } as JSON, @file or -").action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const body = readJsonArg(opts.data, "--data");
+      output(await call(satvoltClient(global), "put", `/export-tables/${tableId}`, { data: body }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("patch <tableId>").summary("Change the name, description or the whole column list.").description(
+    'Change the name, the description or the whole column list. To add, edit, move or\nremove single columns use `export-tables columns`.\nExample:\n  suntropy satvolt export-tables patch 6650... --name "CRM v2"'
+  ).option("--name <name>", "New name").option("--description <text>", "New description").option("--columns <spec>", 'Replace all columns: "Label=path[:type];..." or JSON').action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const body = {};
+      if (opts.name) body.name = opts.name;
+      if (opts.description !== void 0) body.description = opts.description;
+      if (opts.columns) body.columns = parseColumns(opts.columns);
+      if (Object.keys(body).length === 0) throw new Error("Nothing to change");
+      output(await call(satvoltClient(global), "patch", `/export-tables/${tableId}`, { data: body }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  registerColumnCommands(tables);
+  tables.command("delete <tableId>").description("Delete an export table.").action(async (tableId) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      output(await call(satvoltClient(global), "delete", `/export-tables/${tableId}`), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("duplicate <tableId>").description("Copy a table (its columns) into another campaign.").requiredOption("--campaign <campaignId>", "Target campaign").option("--name <name>", "Name of the copy (default: same name)").action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const data = await call(satvoltClient(global), "post", `/export-tables/${tableId}/duplicate`, {
+        data: { targetCampaignId: parseId(opts.campaign, "--campaign"), name: opts.name }
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("data <tableId>").description(
+    "Read table rows page by page, one object per lead keyed by column label.\nExample:\n  suntropy satvolt export-tables data 6650... --limit 100 --format csv"
+  ).option("--limit <n>", "Page size (max 500)", "50").option("--offset <n>", "Skip rows", "0").option("--search <text>", "Name, address or phone contains").action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const page = await call(satvoltClient(global), "get", `/export-tables/${tableId}/data`, {
+        params: { limit: opts.limit, offset: opts.offset, search: opts.search }
+      });
+      const columns = page.columns;
+      const rows = page.items.map((r) => {
+        const row = { "Lead ID": r.idLead };
+        for (const c of columns) row[c.label] = r.values[c.id] ?? null;
+        return row;
+      });
+      if (global.format === "csv") output(rows, global);
+      else outputPaginated(rows, page.total, page.limit, page.offset, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  tables.command("export <tableId>").description(
+    "Download every row of the table (up to 100k) as XLSX or CSV (UTF-8 with BOM).\nExample:\n  suntropy satvolt export-tables export 6650... --file-format csv --out leads.csv"
+  ).option("--file-format <format>", "xlsx | csv", "xlsx").option("--out <path>", "Output file (default: the name suggested by the server, in the current directory)").action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const format = String(opts.fileFormat).toLowerCase();
+      if (format !== "xlsx" && format !== "csv") throw new Error("--file-format must be xlsx or csv");
+      const client = satvoltClient(global, 3e5);
+      const res = await client.get(`/export-tables/${tableId}/export`, {
+        params: { format },
+        responseType: "arraybuffer"
+      });
+      const disposition = String(res.headers["content-disposition"] ?? "");
+      const suggested = /filename="([^"]+)"/.exec(disposition)?.[1] ?? `export-${tableId}.${format}`;
+      const path = resolve(opts.out ?? suggested);
+      const buffer = Buffer.from(res.data);
+      writeFileSync5(path, buffer);
+      output(
+        {
+          saved: path,
+          format,
+          bytes: buffer.length,
+          rows: res.headers["x-row-count"] !== void 0 ? Number(res.headers["x-row-count"]) : null
+        },
+        global
+      );
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+var normalizeLabel = (s) => s.normalize("NFD").replace(/[\u0300-\u036f]/g, "").trim().toLowerCase();
+function resolveColumn(columns, ref) {
+  const byId = columns.find((c) => c.id === ref);
+  if (byId) return byId;
+  const byLabel = columns.filter((c) => normalizeLabel(c.label) === normalizeLabel(ref));
+  if (byLabel.length === 1) return byLabel[0];
+  if (byLabel.length > 1) {
+    throw new Error(`Label "${ref}" matches several columns; use one of the ids: ${byLabel.map((c) => c.id).join(", ")}`);
+  }
+  throw new Error(
+    `No column "${ref}". Columns: ${columns.map((c) => `${c.id} (${c.label})`).join(", ") || "(none)"}`
+  );
+}
+function targetPosition(columns, opts, moving) {
+  const given = [opts.position, opts.before, opts.after].filter((v) => v !== void 0).length;
+  if (given > 1) throw new Error("Use only one of --position, --before or --after");
+  if (opts.position !== void 0) return parseIntOption(opts.position, "--position");
+  const anchorRef = opts.before ?? opts.after;
+  if (anchorRef === void 0) return void 0;
+  const others = columns.filter((c) => c.id !== moving?.id);
+  const anchor = resolveColumn(others, anchorRef);
+  const index = others.findIndex((c) => c.id === anchor.id);
+  return opts.before !== void 0 ? index : index + 1;
+}
+function registerColumnCommands(tables) {
+  const columns = tables.command("columns").summary("Add, edit, move, reorder or remove single columns of an export table.").description(
+    "Edit one column at a time without resending the whole list. Columns are referenced\nby id or by label (case and accents ignored; if two share a label, use the id).\nPositions are 0-based (0 = first column). Each change returns { table, column, warnings }.\nFind paths with: suntropy satvolt export-tables fields <campaignId>"
+  );
+  const list = async (client, tableId) => call(client, "get", `/export-tables/${tableId}/columns`);
+  columns.command("list <tableId>").description("List the columns of a table in order, with their position.").action(async (tableId) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const cols = await list(satvoltClient(global), tableId);
+      output(cols.map((c, position) => ({ position, ...c })), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  columns.command("add <tableId>").summary("Add one or more columns, optionally at a position.").description(
+    'Add a column (at the end unless --position, --before or --after). Without --type the\nserver uses the type the pipeline step declares for the path, or string. --columns adds\nseveral at once.\nExamples:\n  suntropy satvolt export-tables columns add 6650... --label "Consumo kWh" --path fullData.consumptionEstimate.annualKwh\n  suntropy satvolt export-tables columns add 6650... --label CIF --path fullData.cif.response.cif --after Empresa\n  suntropy satvolt export-tables columns add 6650... --columns "Web=lead.url:url;Tel\xE9fono=lead.phone"'
+  ).option("--label <label>", "Column header").option("--path <path>", "lead.<column>, fullData.<path> or synthetic.googleMapsUrl").option("--type <type>", "string | number | boolean | date | url").option("--id <id>", "Column id (letters, digits, _ or -); generated when omitted").option("--columns <spec>", 'Several columns: "Label=path[:type];..." or JSON array').option("--position <n>", "0-based position").option("--before <column>", "Insert before this column (id or label)").option("--after <column>", "Insert after this column (id or label)").action(async (tableId, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const client = satvoltClient(global);
+      const specs = opts.columns ? parseColumns(opts.columns) : [{ label: opts.label, path: opts.path, ...opts.type ? { type: opts.type } : {}, ...opts.id ? { id: opts.id } : {} }];
+      if (opts.columns && (opts.label || opts.path || opts.type || opts.id)) {
+        throw new Error("--columns cannot be combined with --label/--path/--type/--id");
+      }
+      if (specs.some((c) => !c.label || !c.path)) throw new Error("--label and --path are required (or --columns)");
+      let position = targetPosition(await list(client, tableId), opts);
+      let result;
+      const added = [];
+      const warnings = [];
+      for (const spec of specs) {
+        result = await call(client, "post", `/export-tables/${tableId}/columns`, {
+          data: { ...spec, ...position !== void 0 ? { position } : {} }
+        });
+        added.push(result.column);
+        warnings.push(...result.warnings ?? []);
+        if (position !== void 0) position++;
+      }
+      output(specs.length === 1 ? result : { table: result.table, columns: added, warnings }, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  columns.command("set <tableId> <column>").summary("Change the label, path, type or position of one column.").description(
+    'Change the label, path, type and/or position of one column (id or label). What is not\ngiven stays the same; changing the path keeps the type unless --type is given.\nExamples:\n  suntropy satvolt export-tables columns set 6650... "Consumo kWh" --label "Consumo anual (kWh)"\n  suntropy satvolt export-tables columns set 6650... c_1a2b3c4d --path fullData.cif.response.revenue.value --type number'
+  ).option("--label <label>", "New header").option("--path <path>", "New data path").option("--type <type>", "string | number | boolean | date | url").option("--position <n>", "Move to this 0-based position").option("--before <column>", "Move before this column").option("--after <column>", "Move after this column").action(async (tableId, columnRef, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const client = satvoltClient(global);
+      const cols = await list(client, tableId);
+      const column = resolveColumn(cols, columnRef);
+      const position = targetPosition(cols, opts, column);
+      const body = {};
+      if (opts.label !== void 0) body.label = opts.label;
+      if (opts.path !== void 0) body.path = opts.path;
+      if (opts.type !== void 0) body.type = opts.type;
+      if (position !== void 0) body.position = position;
+      if (Object.keys(body).length === 0) throw new Error("Nothing to change: give --label, --path, --type or a position");
+      output(await call(client, "patch", `/export-tables/${tableId}/columns/${encodeURIComponent(column.id)}`, { data: body }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  columns.command("move <tableId> <column>").summary("Move one column to a position, or before/after another.").description(
+    "Move one column to a 0-based position, or before/after another column.\nExamples:\n  suntropy satvolt export-tables columns move 6650... Maps --position 0\n  suntropy satvolt export-tables columns move 6650... CIF --after Empresa"
+  ).option("--position <n>", "0-based position").option("--before <column>", "Move before this column").option("--after <column>", "Move after this column").action(async (tableId, columnRef, opts) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const client = satvoltClient(global);
+      const cols = await list(client, tableId);
+      const column = resolveColumn(cols, columnRef);
+      const position = targetPosition(cols, opts, column);
+      if (position === void 0) throw new Error("Give --position, --before or --after");
+      output(
+        await call(client, "patch", `/export-tables/${tableId}/columns/${encodeURIComponent(column.id)}`, { data: { position } }),
+        global
+      );
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  columns.command("reorder <tableId> <columns...>").description(
+    "Set the order of all columns at once (ids or labels, every column exactly once).\nExample:\n  suntropy satvolt export-tables columns reorder 6650... Empresa CIF Tel\xE9fono Maps"
+  ).action(async (tableId, refs) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const client = satvoltClient(global);
+      const cols = await list(client, tableId);
+      const columnIds = refs.map((ref) => resolveColumn(cols, ref).id);
+      output(await call(client, "put", `/export-tables/${tableId}/columns/order`, { data: { columnIds } }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  columns.command("remove <tableId> <columns...>").summary("Remove one or more columns (ids or labels).").description(
+    "Remove one or more columns (ids or labels).\nExample:\n  suntropy satvolt export-tables columns remove 6650... Maps c_1a2b3c4d"
+  ).action(async (tableId, refs) => {
+    const global = getGlobalOpts17(tables);
+    try {
+      const client = satvoltClient(global);
+      const cols = await list(client, tableId);
+      const targets = [...new Map(refs.map((ref) => resolveColumn(cols, ref)).map((c) => [c.id, c])).values()];
+      let result;
+      for (const column of targets) {
+        result = await call(client, "delete", `/export-tables/${tableId}/columns/${encodeURIComponent(column.id)}`);
+      }
+      output({ table: result.table, removed: targets }, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+
+// src/commands/satvolt/templates.ts
+var TEMPLATE_LIST_FIELDS = "id,name,description,steps,businessGroups,searchQuery,maxLeads,sourceCampaignId";
+var splitList = (value) => value.split(",").map((s) => s.trim()).filter(Boolean);
+var templatePath = (idOrName) => `/campaign-templates/${encodeURIComponent(idOrName)}`;
+function registerSatvoltTemplateCommands(satvolt) {
+  const templates = satvolt.command("templates").summary("Campaign templates: reuse a pipeline for probes, final campaigns or new areas.").description(
+    'Campaign templates keep everything that defines a campaign except its name and area:\npipeline steps (with their uids), business groups, configuration description, search\nquery and lead limit. Reference them by id or by exact name.\nTypical flow:\n  satvolt templates create --name "Greenvolt industria" --from-campaign 62\n  satvolt campaigns create --name "Sonda Elche" --template "Greenvolt industria" \\\n    --circle 38.29,-0.61 --radius 3000 --max-leads 50'
+  );
+  templates.command("list").description("List the campaign templates of your company.").option("--search <text>", "Filter by name").action(async (opts) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      const data = await call(satvoltClient(global), "get", "/campaign-templates", {
+        params: { search: opts.search }
+      });
+      if (global.format === "human" && !global.fields) {
+        output(
+          data.map((t) => ({ ...t, steps: t.steps.map((s) => s.action).join(" \u2192 "), businessGroups: t.businessGroups.join(",") })),
+          { ...global, fields: TEMPLATE_LIST_FIELDS }
+        );
+        return;
+      }
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  templates.command("get <idOrName>").description("Template detail, with its full steps and config.").action(async (idOrName) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      output(await call(satvoltClient(global), "get", templatePath(idOrName)), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  templates.command("create").summary("Create a template from a campaign or from JSON steps.").description(
+    'Create a template from a campaign (--from-campaign) or from JSON steps.\nSteps are LEAD steps, validated like `campaigns create` (defaults filled, missing\ndependencies added). Business groups default to "businesses".\nExamples:\n  suntropy satvolt templates create --name "Greenvolt industria" --from-campaign 62\n  suntropy satvolt templates create --name "Solo tejados" --steps \'[{"action":"FIND_ROOFTOP"}]\' --max-leads 100\n  suntropy satvolt templates create --data @template.json'
+  ).option("--name <name>", "Template name (unique in your company)").option("--description <text>", "What the template is for").option("--from-campaign <id>", "Copy the configuration of this Maps campaign").option("--steps <json>", "LEAD steps as JSON array, @file or -").option("--business-groups <ids>", "Comma-separated business group ids").option("--configuration-description <text>", "Natural language description copied to campaigns").option("--search-query <text>", "Places text search query").option("--max-leads <n>", "Default lead limit of campaigns created from it").option("--data <json>", "Full request body (JSON, @file or -); flags override its fields").action(async (opts) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      const body = opts.data ? readJsonArg(opts.data, "--data") : {};
+      if (opts.name) body.name = opts.name;
+      if (opts.description !== void 0) body.description = opts.description;
+      if (opts.fromCampaign) body.fromCampaignId = parseId(opts.fromCampaign, "--from-campaign");
+      if (opts.steps) body.steps = readJsonArg(opts.steps, "--steps");
+      if (opts.businessGroups) body.businessGroups = splitList(opts.businessGroups);
+      if (opts.configurationDescription !== void 0) body.configurationDescription = opts.configurationDescription;
+      if (opts.searchQuery) body.searchQuery = opts.searchQuery;
+      if (opts.maxLeads !== void 0) body.maxLeads = parseIntOption(opts.maxLeads, "--max-leads");
+      if (!body.name) throw new Error("--name is required");
+      if (body.fromCampaignId === void 0 && body.steps === void 0) {
+        throw new Error("Pass --from-campaign <id> or --steps <json>");
+      }
+      output(await call(satvoltClient(global), "post", "/campaign-templates", { data: body }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  templates.command("update <idOrName>").summary("Replace a whole template (PUT).").description(
+    "Replace a template (PUT). The body is the whole template: steps are required and\nomitted fields are cleared. Tip: `templates get <id> --save t.json`, edit, update."
+  ).requiredOption("--data <json>", "Template body (JSON, @file or -)").action(async (idOrName, opts) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      output(
+        await call(satvoltClient(global), "put", templatePath(idOrName), { data: readJsonArg(opts.data, "--data") }),
+        global
+      );
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  templates.command("patch <idOrName>").summary("Change some fields or steps of a template.").description(
+    'Change some fields of a template. --steps takes step patches by uid, like\n`config patch`: {uid, config} merges (null resets a key to its default),\n{uid, remove: true} deletes, {action, config} without uid adds a step.\nExamples:\n  suntropy satvolt templates patch "Greenvolt industria" --max-leads 500\n  suntropy satvolt templates patch "Greenvolt industria" --no-max-leads --business-groups businesses\n  suntropy satvolt templates patch <id> --steps \'[{"uid":"8771dae3f9637027","config":{"tariffTemplate":"6.1TD"}}]\''
+  ).option("--name <name>", "Rename the template").option("--description <text>", "New description").option("--steps <json>", "Step patches as JSON array, @file or -").option("--business-groups <ids>", "Comma-separated business group ids (empty string: no filter)").option("--configuration-description <text>", "Natural language description copied to campaigns").option("--search-query <text>", "Places text search query (empty string removes it)").option("--max-leads <n>", "Default lead limit").option("--no-max-leads", "Remove the default lead limit").option("--data <json>", "Patch body (JSON, @file or -); flags override its fields").action(async (idOrName, opts) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      const body = opts.data ? readJsonArg(opts.data, "--data") : {};
+      if (opts.name) body.name = opts.name;
+      if (opts.description !== void 0) body.description = opts.description;
+      if (opts.steps) body.steps = readJsonArg(opts.steps, "--steps");
+      if (opts.businessGroups !== void 0) body.businessGroups = splitList(opts.businessGroups);
+      if (opts.configurationDescription !== void 0) body.configurationDescription = opts.configurationDescription;
+      if (opts.searchQuery !== void 0) body.searchQuery = opts.searchQuery === "" ? null : opts.searchQuery;
+      if (opts.maxLeads === false) body.maxLeads = null;
+      else if (opts.maxLeads !== void 0 && opts.maxLeads !== true) body.maxLeads = parseIntOption(opts.maxLeads, "--max-leads");
+      if (Object.keys(body).length === 0) throw new Error("Nothing to change: pass at least one option");
+      output(await call(satvoltClient(global), "patch", templatePath(idOrName), { data: body }), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  templates.command("delete <idOrName>").description("Delete a template. Campaigns created from it are not affected.").option("--yes", "Confirm the deletion (required)").action(async (idOrName, opts) => {
+    const global = getGlobalOpts17(templates);
+    try {
+      if (!opts.yes) throw new Error("Re-run with --yes to delete the template.");
+      output(await call(satvoltClient(global), "delete", templatePath(idOrName)), global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+}
+
+// src/commands/satvolt/index.ts
+function registerSatvoltCommands(program2) {
+  const satvolt = program2.command("satvolt").description(
+    `Satvolt lead-generation campaigns (public API /satvolt/api/v1), with the same auth token.
+Preliminary testing phase: every call is pinned to the dev cluster (${SATVOLT_DEV_BASE_URL}),
+whatever the active profile says. Override with SUNTROPY_SATVOLT_URL, or use a localhost server.
+Typical flow:
+  satvolt catalog actions                      actions and their config schema
+  satvolt campaigns create --circle ... --steps @steps.json
+  satvolt campaigns start <id>   \xB7   satvolt campaigns logs <id> --follow
+  satvolt campaigns funnel <id>  \xB7   satvolt leads list <id> --step QUALIFY
+  satvolt export-tables create <id> ... \xB7 satvolt export-tables export <tableId>
+  satvolt campaigns resume <id> --action AI_AGENT --config @step.json
+  satvolt templates create --name <n> --from-campaign <id> \xB7 campaigns create --template <n>
+  satvolt campaigns extend <id> --max-leads N \xB7 leads run-step <id> <leadId> <step>`
+  );
+  registerSatvoltCampaignCommands(satvolt);
+  registerSatvoltPipelineCommands(satvolt);
+  registerSatvoltLeadCommands(satvolt);
+  registerSatvoltExportTableCommands(satvolt);
+  registerSatvoltTemplateCommands(satvolt);
+  const catalog = satvolt.command("catalog").description("Reference data for building campaigns and pipelines.");
+  const catalogEntries = [
+    ["actions", "/catalog/actions", "Pipeline actions: credits per lead (fixed per action; failed or skipped runs are free), dependencies, multiple, and the JSON Schema of their config (the input). The data each step writes: satvolt export-tables fields <campaignId>."],
+    ["ai-agents", "/catalog/ai-agents", "AI agents allowed in AI_AGENT config.agentId: id, name and description. Every agent costs the AI_AGENT credits."],
+    ["business-groups", "/catalog/business-groups", "Business category groups for --business-groups."],
+    ["states", "/catalog/states", "Campaign and lead states."]
+  ];
+  for (const [name, path, description] of catalogEntries) {
+    catalog.command(name).description(description).action(async () => {
+      const global = getGlobalOpts17(catalog);
+      try {
+        output(await call(satvoltClient(global), "get", path), global);
+      } catch (err) {
+        outputError(satvoltError(err));
+      }
+    });
+  }
+  addSummaries(satvolt);
+}
+function addSummaries(cmd) {
+  for (const sub of cmd.commands) {
+    const description = sub.description();
+    if (!sub.summary() && description.includes("\n")) {
+      const first = description.split("\n")[0].trim();
+      sub.summary(/[.:)]$/.test(first) ? first.replace(/:$/, ".") : `${first}\u2026`);
+    }
+    addSummaries(sub);
+  }
+}
+
 // src/access.ts
 var COMMAND_TIERS = ["read", "write", "delete"];
 var TIER_VALUE = { read: 0, write: 1, delete: 2 };
@@ -4602,7 +5791,7 @@ function setStoredCommandProfile(tier) {
   else cfg.commandProfile = tier;
   saveConfig(cfg);
 }
-var DELETE_VERBS = /* @__PURE__ */ new Set(["delete", "delete-batch", "archive"]);
+var DELETE_VERBS = /* @__PURE__ */ new Set(["delete", "delete-batch", "archive", "reset"]);
 var WRITE_VERBS = /* @__PURE__ */ new Set([
   "create",
   "update",
@@ -4619,7 +5808,17 @@ var WRITE_VERBS = /* @__PURE__ */ new Set([
   "comment",
   "send",
   "calculate-results",
-  "optimize-peakpower"
+  "optimize-peakpower",
+  // satvolt: these launch pipeline work (spending credits) or change configuration.
+  "patch",
+  "start",
+  "resume",
+  "run",
+  "run-step",
+  "duplicate",
+  "extend",
+  "move",
+  "reorder"
 ]);
 var PATH_OVERRIDES = {
   "studies calculate production": "write"
@@ -4666,7 +5865,7 @@ function keepCommand(cmd, segs, max) {
 }
 
 // src/commands/command-profile.ts
-function getGlobalOpts17(cmd) {
+function getGlobalOpts18(cmd) {
   let root = cmd;
   while (root.parent) root = root.parent;
   return root.opts();
@@ -4674,7 +5873,7 @@ function getGlobalOpts17(cmd) {
 function registerCommandProfileCommand(program2) {
   program2.command("command-profile [tier]", { hidden: true }).description("Admin: get/set the command access profile (read | write | delete | reset)").action((tier) => {
     try {
-      const global = getGlobalOpts17(program2);
+      const global = getGlobalOpts18(program2);
       if (!tier) {
         const resolved = getActiveCommandProfile();
         output(
@@ -4729,7 +5928,7 @@ function registerCommandProfileCommand(program2) {
 }
 
 // src/index.ts
-var CLI_VERSION = true ? "0.11.8" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.12.0" : "0.0.0-dev";
 function createProgram() {
   const program2 = new Command4();
   program2.name("suntropy").description("Agent-first CLI for Suntropy solar platform. Optimized for programmatic data manipulation and progressive exploration.").version(CLI_VERSION).option("--format <format>", "Output format: json (default), human, csv", "json").option("--fields <fields>", "Comma-separated fields to include in output").option("--server <url>", "Override API server URL").option("--token <jwt>", "Override authentication token").option("--profile <name>", "Use a specific config profile").option("--verbose", "Show HTTP request/response details on stderr").option("--quiet", "Suppress non-data output").option("--save <file>", "Save output to file (also writes to stdout)");
@@ -4745,6 +5944,7 @@ function createProgram() {
   registerTemplatesCommands(program2);
   registerGeocodeCommands(program2);
   registerNotificationsCommands(program2);
+  registerSatvoltCommands(program2);
   registerCommandProfileCommand(program2);
   applyCommandProfile(program2);
   return program2;