deepline 0.1.186 → 0.1.188

package/dist/cli/index.js

@@ -181,7 +181,7 @@ function configureProxyFromEnv() {
 configureProxyFromEnv();
 
 // src/cli/index.ts
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 var import_node_path20 = require("path");
 var import_node_os15 = require("os");
 var import_commander3 = require("commander");
@@ -623,10 +623,10 @@ var SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: "0.1.186",
+  version: "0.1.188",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.186",
+    latest: "0.1.188",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -8278,13 +8278,155 @@ var PLAY_BOOTSTRAP_STAGE_NAMES = [
   "email",
   "phone"
 ];
+var MONITOR_BOOTSTRAP_TEMPLATE = "monitor-triggered";
+var MONITOR_BOOTSTRAP_DEFAULT_TOOL = "instantly.campaign_events";
+var MONITOR_BOOTSTRAP_DEFAULT_STREAM = "webhook_events";
+function isMonitorBootstrapTemplate(value) {
+  return value === MONITOR_BOOTSTRAP_TEMPLATE;
+}
+function hasMonitorBootstrapForbiddenChar(value) {
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < 32 || code === 127) return true;
+    if (char === "'" || char === '"' || char === "`" || char === "\\") {
+      return true;
+    }
+  }
+  return false;
+}
+function validateMonitorBootstrapFlagValue(flag, value) {
+  if (hasMonitorBootstrapForbiddenChar(value)) {
+    throw new PlayBootstrapUsageError(
+      `${flag} may not contain line breaks, control characters, quotes, or backticks. It is interpolated into the generated play source (including comments); use a plain monitor tool id / stream key / name.`
+    );
+  }
+  return value;
+}
+function parseMonitorBootstrapOptions(args) {
+  const [, ...rest] = args;
+  const options = {
+    name: MONITOR_BOOTSTRAP_TEMPLATE,
+    tool: MONITOR_BOOTSTRAP_DEFAULT_TOOL,
+    stream: MONITOR_BOOTSTRAP_DEFAULT_STREAM,
+    out: null
+  };
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const value = () => nextFlagValue(rest, index, arg);
+    switch (arg) {
+      case "--name":
+        options.name = validateMonitorBootstrapFlagValue("--name", value());
+        index += 1;
+        break;
+      case "--tool":
+        options.tool = validateMonitorBootstrapFlagValue("--tool", value());
+        index += 1;
+        break;
+      case "--stream":
+        options.stream = validateMonitorBootstrapFlagValue("--stream", value());
+        index += 1;
+        break;
+      case "--out":
+        options.out = value();
+        index += 1;
+        break;
+      default:
+        throw new PlayBootstrapUsageError(
+          `Unknown plays bootstrap option for ${MONITOR_BOOTSTRAP_TEMPLATE}: ${arg}
+Usage: deepline plays bootstrap ${MONITOR_BOOTSTRAP_TEMPLATE} [--tool <monitor-tool-id>] [--stream <stream-key>] [--name NAME] [--out monitor.play.ts]`
+        );
+    }
+  }
+  if (!options.tool) {
+    throw new PlayBootstrapUsageError(
+      `${MONITOR_BOOTSTRAP_TEMPLATE} needs a non-empty --tool.`
+    );
+  }
+  if (!options.stream) {
+    throw new PlayBootstrapUsageError(
+      `${MONITOR_BOOTSTRAP_TEMPLATE} needs a non-empty --stream.`
+    );
+  }
+  return options;
+}
+function generateMonitorTriggeredPlaySource(options) {
+  return `import { definePlay } from 'deepline';
+import type { SqlListenerEvent } from 'deepline';
+
+// Row shape delivered by ${options.tool} / ${options.stream}. This is a starting
+// point only: inspect the real columns with
+//   deepline monitors available ${options.tool}
+// and tighten this type to the fields you read below.
+//
+// Before deploying a NEW monitor, run \`deepline monitors list\` \u2014 if one
+// already feeds this stream for your scope, this play will already react to its
+// rows (a play binds to the shared stream), so you may not need to deploy at all.
+type MonitorRow = Record<string, unknown>;
+
+export default definePlay(
+  ${jsString(options.name)},
+  async (ctx, event: SqlListenerEvent<MonitorRow>) => {
+    // The monitor delivers the changed row as event.after. It is null for
+    // DELETE operations, so guard before reading fields.
+    const row = event.after;
+    if (!row) {
+      ctx.log(\`Monitor \${event.tool}/\${event.stream} \${event.operation} with no row; nothing to do.\`);
+      return { handled: false, operation: event.operation };
+    }
+
+    ctx.log(
+      \`Monitor \${event.tool}/\${event.stream} \${event.operation}: \${JSON.stringify(row).slice(0, 200)}\`,
+    );
+
+    // Capture the changed row into a durable dataset so the run has inspectable,
+    // exportable output. ctx.dataset is a CALLABLE: ctx.dataset(key, rows) where
+    // key is a compile-time string LITERAL and rows is an array of row objects.
+    // It returns a builder; add per-row columns with .withColumn(name, resolver)
+    // and finish with .run(). There is no .push/.add \u2014 pass all rows up front.
+    // TODO: replace this plain persist with your real per-row work \u2014 enrich each
+    // row via .withColumn('...', (row, rowCtx) => rowCtx.tools.execute(...)),
+    // notify, write to another table, or fan out with rowCtx.runPlay.
+    const captured = await ctx.dataset('monitor_events', [row]).run({
+      description: \`Captured \${event.tool}/\${event.stream} \${event.operation} rows.\`,
+    });
+
+    return {
+      handled: true,
+      tool: event.tool,
+      stream: event.stream,
+      operation: event.operation,
+      changedAt: event.changedAt,
+      capturedRows: await captured.count(),
+    };
+  },
+  {
+    description: ${jsString(`Run whenever ${options.tool} writes a new ${options.stream} row.`)},
+    // A monitor trigger: this play wakes on row changes written by the bound
+    // monitor tool + stream. Discover a tool's streams and columns with:
+    //   deepline monitors available ${options.tool}
+    // To bind a different monitor, swap tool/stream (and re-check operations)
+    // for one of its (tool, stream) pairs.
+    sqlListeners: [
+      {
+        id: 'events',
+        tool: ${jsString(options.tool)},
+        stream: ${jsString(options.stream)},
+        operations: ['INSERT'],
+        // Optional: only wake on some rows \u2014 add a where filter to the binding above:
+        //   where: { after: { <column>: { eq: 'value' } } }  // operators: eq, neq, in, notIn, isNull, isNotNull, ilike
+      },
+    ],
+  },
+);
+`;
+}
 function playBootstrapUsageLine() {
   return `Usage: deepline plays bootstrap <${formatPlayBootstrapTemplates()}> --from <csv:PATH|play:REF|provider:ID|providers:ID,ID> [--using <play:REF|providers:ID,ID>] [--people play:REF] [--email <play:REF|providers:ID,ID>] [--phone <play:REF|providers:ID,ID>] [--limit 5] [--out flow.play.ts]`;
 }
 function requireBootstrapTemplate(rawTemplate) {
   if (!rawTemplate) {
     throw new PlayBootstrapUsageError(
-      `plays bootstrap needs a route template: ${formatPlayBootstrapTemplates()}.
+      `plays bootstrap needs a route template: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}.
 Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --out email-flow.play.ts`
     );
   }
@@ -8292,7 +8434,7 @@ Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using
     const looksLikePlayReference = rawTemplate.includes("/") || rawTemplate.endsWith(".play.ts");
     throw new PlayBootstrapUsageError(
       `Unknown plays bootstrap template: ${rawTemplate}
-Supported templates: ${formatPlayBootstrapTemplates()}` + (looksLikePlayReference ? `
+Supported templates: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}` + (looksLikePlayReference ? `
 
 "${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}' --watch" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
@@ -9501,7 +9643,25 @@ function renderPlayBootstrapError(error) {
   console.error(errorMessage2(error));
   return error instanceof PlayBootstrapError ? error.exitCode : 1;
 }
+function writeBootstrapSource(source, out) {
+  if (out) {
+    (0, import_node_fs9.writeFileSync)((0, import_node_path10.resolve)(out), source, "utf-8");
+    process.stdout.write(`Wrote ${(0, import_node_path10.resolve)(out)}
+`);
+    return 0;
+  }
+  process.stdout.write(source);
+  return 0;
+}
+function runMonitorBootstrap(args) {
+  const options = parseMonitorBootstrapOptions(args);
+  const source = generateMonitorTriggeredPlaySource(options);
+  return writeBootstrapSource(source, options.out);
+}
 async function runPlayBootstrap(args) {
+  if (isMonitorBootstrapTemplate(args[0])) {
+    return runMonitorBootstrap(args);
+  }
   const options = parsePlayBootstrapOptions(args);
   const client2 = new DeeplineClient();
   const contracts = await loadBootstrapContracts(client2, options);
@@ -9511,20 +9671,15 @@ async function runPlayBootstrap(args) {
     ...contracts,
     ...csvContext
   });
-  if (options.out) {
-    (0, import_node_fs9.writeFileSync)((0, import_node_path10.resolve)(options.out), source, "utf-8");
-    process.stdout.write(`Wrote ${(0, import_node_path10.resolve)(options.out)}
-`);
-    return 0;
-  }
-  process.stdout.write(source);
-  return 0;
+  return writeBootstrapSource(source, options.out);
 }
 async function handlePlayBootstrap(args) {
   return runPlayBootstrap(args).catch(renderPlayBootstrapError);
 }
 function registerPlayBootstrapCommand(play) {
-  play.command("bootstrap <template>").description("Print a scratchpad play for a GTM route template.").addHelpText(
+  play.command("bootstrap <template>").description(
+    "Print a scratchpad play for a GTM route or monitor-triggered template."
+  ).addHelpText(
     "after",
     `
 Notes:
@@ -9548,6 +9703,13 @@ Notes:
     company-people          company/account rows -> people play
     company-people-email    company/account rows -> people play -> email finder
     company-people-phone    company/account rows -> people play -> phone finder
+    monitor-triggered       run a play whenever a monitor writes a new row
+                            (definePlay with sqlListeners; no --from/stage flags)
+
+  Monitor-triggered options (only for the monitor-triggered template):
+    --tool <monitor-tool-id>   monitor tool to bind (default instantly.campaign_events)
+    --stream <stream-key>      output stream to listen on (default webhook_events)
+    Discover a tool's streams/columns with: deepline monitors available <id>
 
   Resource refs:
     csv:./contacts.csv
@@ -9577,6 +9739,9 @@ Examples:
   deepline plays bootstrap people-email --from provider:dropleads_search_people --using providers:hunter_email_finder,leadmagic_email_finder --limit 5 --out prospecting.play.ts
   deepline plays bootstrap company-people-email --from provider:crustdata_companydb_search --people play:prebuilt/company-to-contact --email play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out account-contacts.play.ts
   deepline plays bootstrap company-list --from provider:crustdata_companydb_search --limit 5 --out companies.play.ts
+
+  deepline plays bootstrap monitor-triggered --out on-new-row.play.ts
+  deepline plays bootstrap monitor-triggered --tool tamradar.company_radar --stream company_job_openings --out on-new-job.play.ts
 `
   ).option("--name <name>", "Generated play name").option(
     "--from <ref>",
@@ -9593,7 +9758,13 @@ Examples:
   ).option(
     "--phone <ref>",
     "Phone finder stage: play:REF, provider:ID, or providers:ID,ID"
-  ).option("--limit <n>", "Maximum rows to fan out in the generated play").option("--out <path>", "Write generated play source to a file").action(async (template, options) => {
+  ).option("--limit <n>", "Maximum rows to fan out in the generated play").option(
+    "--tool <id>",
+    "monitor-triggered only: monitor tool id to bind (e.g. instantly.campaign_events)"
+  ).option(
+    "--stream <key>",
+    "monitor-triggered only: monitor output stream to listen on (e.g. webhook_events)"
+  ).option("--out <path>", "Write generated play source to a file").action(async (template, options) => {
     process.exitCode = await handlePlayBootstrap([
       template,
       ...options.name ? ["--name", options.name] : [],
@@ -9603,6 +9774,8 @@ Examples:
       ...options.email ? ["--email", options.email] : [],
       ...options.phone ? ["--phone", options.phone] : [],
       ...options.limit ? ["--limit", options.limit] : [],
+      ...options.tool ? ["--tool", options.tool] : [],
+      ...options.stream ? ["--stream", options.stream] : [],
       ...options.out ? ["--out", options.out] : []
     ]);
   });
@@ -13527,6 +13700,89 @@ function printToolGetterHints(hints) {
     if (hint.unavailable) console.log(`      - warning: ${hint.unavailable}`);
   }
 }
+function printPlayTriggers(triggers) {
+  if (!triggers) return;
+  const hasAny = (triggers.sqlListeners?.length ?? 0) > 0 || Boolean(triggers.cron) || triggers.webhook === true;
+  if (!hasAny) return;
+  console.log("  triggers:");
+  for (const listener of triggers.sqlListeners ?? []) {
+    const target = listener.tool && listener.stream ? `${listener.tool}/${listener.stream}` : listener.tool ?? listener.stream ?? listener.id;
+    const operations = listener.operations.length ? listener.operations.join(", ") : "INSERT, UPDATE";
+    const whereNote = listener.where ? " (with where filter)" : "";
+    console.log(`    sqlListeners \u2192 ${target} on ${operations}${whereNote}`);
+  }
+  if (triggers.cron) {
+    const timezone = triggers.cron.timezone ? ` (${triggers.cron.timezone})` : "";
+    console.log(`    cron \u2192 ${triggers.cron.schedule}${timezone}`);
+  }
+  if (triggers.webhook === true) {
+    console.log("    webhook \u2192 enabled");
+  }
+}
+function printRecognizedSummary(recognized) {
+  if (!recognized) return;
+  if (recognized.tools?.length) {
+    console.log(`  tools: ${recognized.tools.join(", ")}`);
+  }
+  for (const dataset of recognized.datasets ?? []) {
+    const columns = dataset.columns?.length ? ` (${dataset.columns.length} col${dataset.columns.length === 1 ? "" : "s"}: ${dataset.columns.join(", ")})` : "";
+    console.log(`  dataset ${dataset.name}${columns}`);
+  }
+  if (recognized.inputs?.length) {
+    console.log(`  inputs: ${recognized.inputs.join(", ")}`);
+  }
+  if (recognized.outputs?.length) {
+    console.log(`  outputs: ${recognized.outputs.join(", ")}`);
+  }
+}
+function formatPlayCheckIssueLines(issue) {
+  const lines = [`  - ${issue.message}`];
+  if (issue.path) {
+    lines.push(`      at ${issue.path}`);
+  }
+  if (issue.validOptions?.length) {
+    lines.push(`      \u2192 valid: [${issue.validOptions.join(", ")}]`);
+  }
+  if (issue.hint?.trim()) {
+    lines.push(`      hint: ${issue.hint.trim()}`);
+  }
+  if (issue.docsHint?.trim()) {
+    lines.push(`      next: ${issue.docsHint.trim()}`);
+  }
+  return lines;
+}
+function printPlayCheckIssues(issues, writer) {
+  if (!issues?.length) return;
+  const errorIssues = issues.filter((issue) => issue.severity === "error");
+  const warningIssues = issues.filter((issue) => issue.severity === "warning");
+  if (errorIssues.length) {
+    writer("  issues:");
+    for (const issue of errorIssues) {
+      for (const line of formatPlayCheckIssueLines(issue)) writer(line);
+    }
+  }
+  if (warningIssues.length) {
+    writer("  warnings:");
+    for (const issue of warningIssues) {
+      for (const line of formatPlayCheckIssueLines(issue)) writer(line);
+    }
+  }
+}
+function partitionMirroredErrors(errors, issues) {
+  const errorMessages = (issues ?? []).filter((issue) => issue.severity === "error").map((issue) => issue.message.trim()).filter((message) => message.length > 0);
+  if (errorMessages.length === 0) {
+    return { unstructuredErrors: errors ?? [] };
+  }
+  const isMirror = (error) => {
+    const trimmed = error.trim();
+    return errorMessages.some(
+      (message) => trimmed === message || trimmed.startsWith(message)
+    );
+  };
+  return {
+    unstructuredErrors: (errors ?? []).filter((error) => !isMirror(error))
+  };
+}
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
@@ -13659,16 +13915,27 @@ async function handlePlayCheck(args) {
 `
     );
   } else if (enrichedResult.valid) {
-    console.log(`\u2713 ${playName} passed cloud play check`);
+    const summary = enrichedResult.summary?.trim();
+    console.log(
+      summary ? `\u2713 ${playName} valid \u2014 ${summary}` : `\u2713 ${playName} passed cloud play check`
+    );
     if (enrichedResult.artifactHash) {
       console.log(`  artifact: ${enrichedResult.artifactHash.slice(0, 12)}`);
     }
+    printPlayTriggers(enrichedResult.triggers);
+    printRecognizedSummary(enrichedResult.recognized);
+    printPlayCheckIssues(enrichedResult.issues, (line) => console.log(line));
     printToolGetterHints(enrichedResult.toolGetterHints);
   } else {
     console.error(`\u2717 ${playName} failed cloud play check`);
-    for (const error of enrichedResult.errors) {
+    const { unstructuredErrors } = partitionMirroredErrors(
+      enrichedResult.errors,
+      enrichedResult.issues
+    );
+    for (const error of unstructuredErrors) {
       console.error(`  ${error}`);
     }
+    printPlayCheckIssues(enrichedResult.issues, (line) => console.error(line));
     printToolGetterHints(enrichedResult.toolGetterHints);
   }
   return enrichedResult.valid ? 0 : 1;
@@ -17320,11 +17587,12 @@ function helperSource() {
 
 // src/cli/commands/enrich.ts
 var ENRICH_EXPORT_PAGE_SIZE = 5e3;
-var ENRICH_AUTO_BATCH_ROWS = 250;
+var ENRICH_AUTO_BATCH_ROWS = 200;
 var ENRICH_HEAVY_PLAY_AUTO_BATCH_ROWS = 25;
 var ENRICH_NESTED_PROVIDER_AUTO_BATCH_ROWS = 50;
 var ENRICH_EXPORT_BACKING_ROWS_WAIT_MS = 6e4;
 var ENRICH_EXPORT_BACKING_ROWS_POLL_MS = 1e3;
+var ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS = [1e3, 3e3, 7e3];
 var ENRICH_SOURCE_ROW_INDEX_COLUMN = "__deeplineSourceRowIndex";
 var ENRICH_ORIGINAL_SOURCE_ROW_INDEX_COLUMN = "__deeplineOriginalSourceRowIndex";
 var ENRICH_CELL_META_FIELD = "__deeplineCellMeta";
@@ -17475,6 +17743,13 @@ function enrichExportBackingRowsWaitMs() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : ENRICH_EXPORT_BACKING_ROWS_WAIT_MS;
 }
+function enrichCustomerDbFailureLookupRetryDelaysMs() {
+  const raw = process.env.DEEPLINE_ENRICH_CUSTOMER_DB_LOOKUP_RETRY_DELAYS_MS?.trim();
+  if (!raw) {
+    return ENRICH_CUSTOMER_DB_FAILURE_LOOKUP_RETRY_DELAYS_MS;
+  }
+  return raw.split(",").map((part) => Number.parseInt(part.trim(), 10)).filter((value) => Number.isFinite(value) && value >= 0);
+}
 function emitEnrichDebugValidationLines(config) {
   for (const line of buildEnrichDebugValidationLines(config)) {
     emitEnrichDebug(line);
@@ -18415,13 +18690,71 @@ function failureAliasFromCellMeta(cellMeta) {
   }
   return null;
 }
+function formatEnrichDiagnosticError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode ? `HTTP ${error.statusCode}: ` : "";
+    const code = error.code && error.code !== "API_ERROR" ? ` [${error.code}]` : "";
+    return `${status}${error.message}${code}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function isRetryableCustomerDbLookupError(error) {
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode;
+    if (status === 408 || status === 425 || status === 429 || status === 503 || typeof status === "number" && status >= 500) {
+      return true;
+    }
+    if (error.code === "NETWORK_TIMEOUT" || error.code === "NETWORK_ABORTED" || error.code === "NETWORK_ERROR" || error.code === "42P01") {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /Internal Server Error|fetch failed|ECONNRESET|ETIMEDOUT|timed out after \d+ms while waiting for a response|Unable to connect|relation .* does not exist|Neon API request failed \(404\)|ingestion plane .*not ready/i.test(
+    message
+  );
+}
+function customerDbLookupUnavailableIssue(input2) {
+  const command = input2.customerDb.command ?? (input2.customerDb.sql ? `deepline db query --sql ${shellSingleQuote2(input2.customerDb.sql)} --json` : void 0);
+  return {
+    issue_id: `customer-db-failure-lookup-${input2.customerDb.runId ?? "run"}`,
+    kind: "customer_db_lookup_unavailable",
+    severity: "needs_attention",
+    message: "Enrich completed, but Deepline could not inspect the Customer DB backing table for failed row details yet.",
+    next_steps: [
+      "Use the Customer DB query command below to inspect the durable rows after the data plane settles.",
+      "If the command keeps failing, inspect the run output and runtime sheet export instead of rerunning provider enrichments blindly."
+    ],
+    follow_up_commands: command ? [
+      {
+        label: "query customer db",
+        command,
+        path: input2.customerDb.datasetPath
+      }
+    ] : [],
+    ...input2.customerDb.runId ? { run_id: input2.customerDb.runId } : {},
+    error: formatEnrichDiagnosticError(input2.error),
+    attempts: input2.attempts
+  };
+}
+function emitCustomerDbLookupUnavailableWarning(issue) {
+  process.stderr.write(`Warning: ${issue.message}
+`);
+  if (issue.error) {
+    process.stderr.write(`Warning detail: ${issue.error}
+`);
+  }
+  for (const command of issue.follow_up_commands) {
+    process.stderr.write(`Command: ${command.label}: ${command.command}
+`);
+  }
+}
 async function collectCustomerDbFailureJobs(input2) {
   const customerDb = enrichCustomerDbJson({
     status: input2.status,
     client: input2.client
   });
   if (!customerDb?.runId || !customerDb.sqlQualifiedTableName) {
-    return [];
+    return { jobs: [], issue: null };
   }
   const fallbackAliases = collectHardFailureAliasSpecs(input2.config);
   const fallbackAlias = fallbackAliases[0]?.alias ?? "enrich";
@@ -18429,16 +18762,49 @@ async function collectCustomerDbFailureJobs(input2) {
     fallbackAliases.map((spec, index) => [normalizeAlias2(spec.alias), index])
   );
   const sql = `select _input_index, _status, _error, _cell_meta from ${customerDb.sqlQualifiedTableName} where _run_id = ${sqlStringLiteral(customerDb.runId)} and (_error is not null or lower(coalesce(_status, '')) in ('failed', 'error')) order by _input_index limit 1000`;
-  const result = await input2.client.queryCustomerDb({
-    sql,
-    maxRows: 1e3
-  });
+  const retryDelays = enrichCustomerDbFailureLookupRetryDelaysMs();
+  let lastError = null;
+  let attempts = 0;
+  let result = null;
+  for (let attempt = 0; attempt <= retryDelays.length; attempt += 1) {
+    try {
+      attempts = attempt + 1;
+      result = await input2.client.queryCustomerDb({
+        sql,
+        maxRows: 1e3
+      });
+      lastError = null;
+      break;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retryDelays.length || !isRetryableCustomerDbLookupError(error)) {
+        break;
+      }
+      const delayMs = retryDelays[attempt] ?? 0;
+      emitEnrichDebug(
+        `customer_db failure lookup retrying after ${delayMs}ms: ${formatEnrichDiagnosticError(error)}`
+      );
+      if (delayMs > 0) {
+        await sleep6(delayMs);
+      }
+    }
+  }
+  if (!result) {
+    return {
+      jobs: [],
+      issue: customerDbLookupUnavailableIssue({
+        customerDb,
+        error: lastError,
+        attempts
+      })
+    };
+  }
   const rows = Array.isArray(result.rows) ? result.rows : [];
   const failedRows = rows.filter((row) => {
     const status = typeof row._status === "string" ? row._status.trim().toLowerCase() : "";
     return typeof row._error === "string" && row._error.trim() || status === "failed" || status === "error";
   });
-  return failedRows.map((row, index) => {
+  const jobs = failedRows.map((row, index) => {
     const metaFailure = failureAliasFromCellMeta(row._cell_meta);
     const alias = metaFailure?.alias ?? fallbackAlias;
     const normalizedAlias = normalizeAlias2(alias);
@@ -18462,6 +18828,7 @@ async function collectCustomerDbFailureJobs(input2) {
       ...metaFailure?.provider ? { provider: metaFailure.provider } : {}
     };
   });
+  return { jobs, issue: null };
 }
 async function buildEnrichFailureReport(input2) {
   const fallbackRowsInfo = input2.exportResult ? null : extractCanonicalRowsInfo(input2.status);
@@ -18989,9 +19356,7 @@ function collectWaterfallAliasSpecs(config) {
       alias,
       childAliases: activeChildren.map((child) => child.alias).filter(Boolean),
       childRunIfJsByAlias: new Map(
-        activeChildren.map(
-          (child) => [child.alias, child.run_if_js]
-        )
+        activeChildren.map((child) => [child.alias, child.run_if_js])
       ),
       childToolsByAlias: new Map(
         activeChildren.map(
@@ -19767,21 +20132,26 @@ async function maybeEmitEnrichFailureReport(input2) {
     status: input2.status,
     rowRange: input2.statusRowRange ?? input2.rowRange
   });
-  const customerDbJobs = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? [] : await collectCustomerDbFailureJobs({
+  const customerDbDiagnostics = input2.status === void 0 || rowJobs.length > 0 || statusJobs.length > 0 ? { jobs: [], issue: null } : await collectCustomerDbFailureJobs({
     client: input2.client,
     status: input2.status,
     config: input2.config
   });
+  const customerDbJobs = customerDbDiagnostics.jobs;
+  if (customerDbDiagnostics.issue) {
+    emitCustomerDbLookupUnavailableWarning(customerDbDiagnostics.issue);
+  }
+  const allEnrichIssues = enrichIssues;
   const jobs = rowJobs.length > 0 || statusJobs.length > 0 || customerDbJobs.length > 0 || input2.status === void 0 ? mergeEnrichFailureJobs(
     mergeEnrichFailureJobs(rowJobs, statusJobs),
     customerDbJobs
   ) : [];
-  if (jobs.length === 0 && enrichIssues.length === 0) {
+  if (jobs.length === 0 && allEnrichIssues.length === 0) {
     return null;
   }
   const reportPath = await persistEnrichFailureReport({
     jobs,
-    issues: enrichIssues,
+    issues: allEnrichIssues,
     apiUrl: input2.client.baseUrl,
     outputPath: input2.outputPath,
     rows: input2.rowRange
@@ -19801,13 +20171,13 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
     }
   }
-  if (enrichIssues.length > 0) {
+  if (allEnrichIssues.length > 0) {
     process.stderr.write("Enrichment needs attention.\n");
     process.stderr.write("Issue preview (up to 5 enrichment issues):\n");
     process.stderr.write(
       "issue_id	column	severity	selected_rows	rows_with_value	message\n"
     );
-    for (const issue of enrichIssues.slice(0, 5)) {
+    for (const issue of allEnrichIssues.slice(0, 5)) {
       process.stderr.write(
         `${issue.issue_id}	${issue.column}	${issue.severity}	${issue.selected_rows}	${issue.rows_with_value}	${issue.message}
 `
@@ -19821,9 +20191,9 @@ async function maybeEmitEnrichFailureReport(input2) {
 `);
       }
     }
-    if (enrichIssues.length > 5) {
+    if (allEnrichIssues.length > 5) {
       process.stderr.write(
-        `Showing 5 of ${enrichIssues.length} enrichment issues.
+        `Showing 5 of ${allEnrichIssues.length} enrichment issues.
 `
       );
     }
@@ -19841,12 +20211,12 @@ async function maybeEmitEnrichFailureReport(input2) {
     process.stderr.write(
       jobs.length > 0 ? "Enrichment failed. See report above.\n" : "Enrichment produced no values for at least one requested waterfall. See issue preview above.\n"
     );
-    return { path: reportPath, jobs, issues: enrichIssues };
+    return { path: reportPath, jobs, issues: allEnrichIssues };
   }
   process.stderr.write(
     jobs.length > 0 ? "Enrichment failed.\n" : "Enrichment needs attention.\n"
   );
-  return { path: "", jobs, issues: enrichIssues };
+  return { path: "", jobs, issues: allEnrichIssues };
 }
 function mergePreferredColumns(preferredColumns, rows) {
   const columns = [];
@@ -21763,44 +22133,455 @@ Examples:
 }
 
 // src/cli/commands/monitors.ts
+var import_node_fs12 = require("fs");
+var import_promises4 = require("readline/promises");
 var FORBIDDEN_AS_API_ERROR = { forbiddenAsApiError: true };
+var JSON_OPTION_DESCRIPTION = "Emit JSON output. Also automatic when stdout is piped";
+function withJsonOption(command) {
+  return command.option("--json", JSON_OPTION_DESCRIPTION);
+}
+var COMPACT_OPTION_DESCRIPTION = "Ask the server for high-signal fields only (smaller output for agent loops)";
 function buildHttpClient() {
   return new HttpClient(resolveConfig());
 }
-function parseJsonObjectArg(raw, flag) {
+var MonitorsUsageError = class extends Error {
+  code = "MONITORS_USAGE_ERROR";
+  constructor(message) {
+    super(message);
+    this.name = "MonitorsUsageError";
+  }
+};
+var MonitorDryRunUnsupportedError = class extends Error {
+  code = "MONITOR_DRY_RUN_UNSUPPORTED";
+  constructor(message) {
+    super(message);
+    this.name = "MonitorDryRunUnsupportedError";
+  }
+};
+function monitorsErrorExitCode(error) {
+  if (error instanceof MonitorsUsageError) return 2;
+  if (error instanceof AuthError) return 3;
+  if (error instanceof DeeplineError) {
+    const status = error.statusCode;
+    if (status === 401 || status === 403) return 3;
+    if (status === 404) return 4;
+    if (status === 400 || status === 422) return 7;
+    return 5;
+  }
+  return 5;
+}
+function monitorsFailureNextCommand(error, exitCode) {
+  if (error instanceof DeeplineError && error.code === "monitor_access_required") {
+    return "deepline monitors status";
+  }
+  if (exitCode === 3) return "deepline auth status --json";
+  if (exitCode === 4) return "deepline monitors list --status all --json";
+  return void 0;
+}
+function readValidationIssues(error) {
+  if (!(error instanceof DeeplineError)) return [];
+  const response = asRecord(asRecord(error.details)?.response);
+  const issues = Array.isArray(response?.issues) ? response.issues : [];
+  return issues.flatMap((raw) => {
+    const issue = asRecord(raw);
+    if (!issue) return [];
+    return [
+      {
+        ...asString(issue.path) ? { path: asString(issue.path) } : {},
+        ...asString(issue.message) ? { message: asString(issue.message) } : {}
+      }
+    ];
+  });
+}
+function reportMonitorsFailure(error) {
+  const exitCode = monitorsErrorExitCode(error);
+  const next = monitorsFailureNextCommand(error, exitCode);
+  const wantsJson = shouldEmitJson(process.argv.includes("--json"));
+  if (wantsJson) {
+    const payload = errorToJsonPayload(error);
+    printJson({
+      ok: false,
+      exitCode,
+      ...next ? { next } : {},
+      error: payload.error
+    });
+  } else {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    for (const issue of readValidationIssues(error)) {
+      process.stderr.write(
+        `  - ${issue.path ? `${issue.path}: ` : ""}${issue.message ?? ""}
+`
+      );
+    }
+    if (next) process.stderr.write(`Next: ${next}
+`);
+  }
+  process.exitCode = exitCode;
+}
+function monitorsAction(handler) {
+  return async (...args) => {
+    try {
+      await handler(...args);
+    } catch (error) {
+      reportMonitorsFailure(error);
+    }
+  };
+}
+function parseJsonObjectArg(raw, argLabel) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (error) {
-    throw new Error(
-      `${flag} must be a JSON object. ${error instanceof Error ? error.message : String(error)}`
+    throw new MonitorsUsageError(
+      `${argLabel} must be a JSON object. ${error instanceof Error ? error.message : String(error)}`
     );
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${flag} must be a JSON object.`);
+    throw new MonitorsUsageError(`${argLabel} must be a JSON object.`);
   }
   return parsed;
 }
+function resolveMonitorJsonBody(input2) {
+  const readFile3 = input2.readFile ?? ((path) => (0, import_node_fs12.readFileSync)(path, "utf-8"));
+  const readStdin = input2.readStdin ?? (() => (0, import_node_fs12.readFileSync)(0, "utf-8"));
+  if (input2.positional !== void 0 && input2.file !== void 0) {
+    throw new MonitorsUsageError(
+      `Pass exactly one source for ${input2.argLabel}: the positional JSON or --file, not both.`
+    );
+  }
+  if (input2.positional !== void 0) {
+    return parseJsonObjectArg(input2.positional, input2.argLabel);
+  }
+  if (input2.file !== void 0) {
+    if (input2.file === "-") {
+      return parseJsonObjectArg(readStdin(), `${input2.argLabel} (stdin)`);
+    }
+    let raw;
+    try {
+      raw = readFile3(input2.file);
+    } catch (error) {
+      throw new MonitorsUsageError(
+        `Could not read --file ${input2.file}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return parseJsonObjectArg(raw, `${input2.argLabel} (--file ${input2.file})`);
+  }
+  throw new MonitorsUsageError(
+    `${input2.command} needs ${input2.argLabel} (a JSON object). Pass it positionally:
+  ${input2.command} '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+or from a file / stdin:
+  ${input2.command} --file monitor.json
+  cat monitor.json | ${input2.command} --file -`
+  );
+}
 function encodeKey(key) {
   return encodeURIComponent(key);
 }
-async function handleMonitorsTools(options) {
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function asFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function yesNo(value) {
+  if (value === true) return "yes";
+  if (value === false) return "no";
+  return "unknown";
+}
+function readDeployOutputContract(payload) {
+  const contract = asRecord(payload.output_contract);
+  if (!contract) return { streams: [] };
+  const rawOutputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+  const streams = rawOutputs.flatMap((raw) => {
+    const output2 = asRecord(raw);
+    const stream = output2 ? asString(output2.stream) : void 0;
+    const table = output2 ? asString(output2.table) : void 0;
+    if (!output2 || !stream || !table) return [];
+    const columns = Array.isArray(output2.columns) ? output2.columns.flatMap((rawColumn) => {
+      const column = asRecord(rawColumn);
+      const name = column ? asString(column.name) : void 0;
+      return name ? [name] : [];
+    }) : [];
+    return [
+      {
+        stream,
+        table,
+        columns,
+        isEvent: output2.is_event_stream === true,
+        matchesPayload: output2.matches_payload === true
+      }
+    ];
+  });
+  return { tool: asString(contract.tool), streams };
+}
+function renderMonitorDeployCompletion(payload) {
+  const monitor = asRecord(payload.monitor);
+  const key = monitor ? asString(monitor.key) : void 0;
+  const { tool, streams } = readDeployOutputContract(payload);
+  if (!key || streams.length === 0) return void 0;
+  const toolId = tool ?? (monitor ? asString(monitor.tool) : void 0) ?? "<tool>";
+  const name = monitor ? asString(monitor.name) : void 0;
+  const status = monitor ? asString(monitor.status) : void 0;
+  const eventStreams = streams.filter((stream) => stream.isEvent);
+  const matched = eventStreams.filter((stream) => stream.matchesPayload);
+  const shown = matched.length ? matched : eventStreams.length ? eventStreams : streams;
+  const primary = shown[0];
+  const lines = [
+    `\u2713 Deployed monitor "${key}"${name ? ` (${name})` : ""} \u2014 tool ${toolId}${status ? `, status ${status}` : ""}`,
+    "",
+    "Output \u2192 Customer DB:"
+  ];
+  for (const stream of shown) {
+    lines.push(`  ${stream.table}  (stream: ${stream.stream})`);
+    lines.push(
+      `    columns: ${stream.columns.length ? stream.columns.join(", ") : "(promoted dynamically as events arrive)"}`
+    );
+  }
+  lines.push(
+    "",
+    "This monitor streams new rows into your Customer DB \u2014 there is no manual run.",
+    "Next:",
+    "  \u2022 Query the table above directly, or",
+    "  \u2022 Run a play on each new row (third arg to definePlay in your .play.ts):",
+    `      sqlListeners: [{ id: '${primary.stream}', tool: '${toolId}', stream: '${primary.stream}', operations: ['INSERT'] }]`,
+    "    The changed row arrives to your handler as the sqlListener event's `after`.",
+    "",
+    "Reuse: many plays can bind to this one stream \u2014 you do NOT need a separate",
+    "monitor per play. Before deploying another monitor on this tool, run",
+    "`deepline monitors list` and reuse an existing one that covers your scope."
+  );
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorDeployPlan(payload) {
+  const valid = payload.valid !== false;
+  const lines = [
+    "DRY RUN \u2014 nothing was deployed.",
+    valid ? "Definition: valid" : "Definition: INVALID"
+  ];
+  if (!valid) {
+    const issues = Array.isArray(payload.issues) ? payload.issues : [];
+    for (const raw of issues) {
+      const issue = asRecord(raw);
+      const path = issue ? asString(issue.path) : void 0;
+      const message = issue ? asString(issue.message) : void 0;
+      if (message) lines.push(`  - ${path ? `${path}: ` : ""}${message}`);
+    }
+  }
+  const estimate = asRecord(payload.deploy_cost_estimate);
+  const credits = estimate ? asFiniteNumber(estimate.credits) : void 0;
+  if (credits !== void 0) {
+    const note = estimate ? asString(estimate.note) : void 0;
+    lines.push(
+      `Deploy cost: would cost ${credits} Deepline credits${note ? ` \u2014 ${note}` : ""}.`
+    );
+  } else {
+    lines.push(
+      "Deploy cost: estimate unavailable from this server (validation only)."
+    );
+  }
+  const candidates = Array.isArray(payload.reuse_candidates) ? payload.reuse_candidates : [];
+  const candidateLines = candidates.flatMap((raw) => {
+    const candidate = asRecord(raw);
+    const key = candidate ? asString(candidate.key) : void 0;
+    if (!candidate || !key) return [];
+    const name = asString(candidate.name);
+    const status = asString(candidate.status);
+    const covers = asString(candidate.covers);
+    return [
+      `  ${key}${name ? ` (${name})` : ""}${status ? ` \u2014 ${status}` : ""}${covers ? `; covers ${covers}` : ""}`
+    ];
+  });
+  if (candidateLines.length > 0) {
+    lines.push(
+      "",
+      "You may already have a monitor covering this \u2014 check before deploying:",
+      ...candidateLines,
+      "  Inspect: deepline monitors get <key> --json"
+    );
+  }
+  lines.push(
+    "",
+    valid ? "Deploy for real: re-run this command without --dry-run." : "Fix the definition, then re-run this command."
+  );
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorDeletePlan(payload, fallbackKey) {
+  const plan = asRecord(payload.plan);
+  const key = (plan ? asString(plan.monitor_key) : void 0) ?? fallbackKey;
+  const lines = [
+    "DRY RUN \u2014 nothing was deleted.",
+    `Delete plan for monitor "${key}":`,
+    `  delete Deepline record: ${yesNo(plan?.would_delete_record)}`,
+    `  deprovision upstream provider resource: ${yesNo(plan?.would_deprovision_upstream)}`,
+    "",
+    `Delete for real: deepline monitors delete ${key} --yes`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function renderMonitorReactivatePlan(payload, key) {
+  const estimate = asRecord(payload.cost_estimate);
+  const credits = estimate ? asFiniteNumber(estimate.credits) : void 0;
+  const lines = [
+    "DRY RUN \u2014 nothing was reactivated.",
+    credits !== void 0 ? `Reactivate cost: would cost ${credits} Deepline credits.` : "Reactivate cost: estimate unavailable from this server.",
+    "",
+    `Reactivate for real: deepline monitors reactivate ${key}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function assertMonitorDryRunAcknowledged(payload, context) {
+  if (payload.dry_run === true) return;
+  throw new MonitorDryRunUnsupportedError(
+    `${context.command} --dry-run: the server response did not acknowledge dry-run mode (missing "dry_run": true). This Deepline server may not support --dry-run for ${context.mutation}, so the response cannot be trusted as a plan. Nothing was rendered as a plan. Verify current state with \`deepline monitors get <key> --json\`, and re-run without --dry-run only when you intend the real ${context.mutation}.`
+  );
+}
+function monitorDeleteRequiresYesError(key, options = {}) {
+  const flags = options.localOnly ? " --local-only" : "";
+  return new MonitorsUsageError(
+    `monitors delete is destructive: it deletes monitor "${key}"${options.localOnly ? " (Deepline record only)" : " and deprovisions its upstream provider resource"}. Non-interactive runs must confirm with --yes:
+  deepline monitors delete ${key}${flags} --yes
+Preview the plan first with:
+  deepline monitors delete ${key}${flags} --dry-run`
+  );
+}
+async function handleMonitorsStatus(options) {
+  const http = buildHttpClient();
+  const payload = await http.request(
+    "/api/v2/monitors/access",
+    { method: "GET" }
+  );
+  const hasAccess = payload.has_access === true;
+  const reason = typeof payload.reason === "string" && payload.reason.trim() ? payload.reason.trim() : void 0;
+  const text = hasAccess ? `\u2713 You have access to Deepline Monitors${reason ? `
+  ${reason}` : ""}
+` : `\u2717 No access to Deepline Monitors${reason ? ` \u2014 ${reason}` : ""}
+`;
+  printCommandEnvelope(
+    { has_access: hasAccess, ...reason ? { reason } : {} },
+    { json: options.json, text }
+  );
+  if (!hasAccess) {
+    process.exitCode = 1;
+  }
+}
+function renderAvailableToolsText(payload) {
+  const tools = Array.isArray(payload.tools) ? payload.tools : null;
+  if (!tools) return void 0;
+  const returned = asFiniteNumber(payload.returned) ?? tools.length;
+  const total = asFiniteNumber(payload.total);
+  const lines = [
+    total !== void 0 ? `Monitor tools you can deploy (${returned} of ${total}):` : "Monitor tools you can deploy:"
+  ];
+  for (const raw of tools) {
+    const entry = asRecord(raw);
+    const id = entry ? asString(entry.tool) : void 0;
+    if (!entry || !id) continue;
+    const name = asString(entry.name) ?? asString(entry.display_name);
+    const deployedCount = asFiniteNumber(entry.deployed_count);
+    lines.push(
+      `  ${id}${name ? ` \u2014 ${name}` : ""}${deployedCount !== void 0 ? `  (deployed: ${deployedCount})` : ""}`
+    );
+  }
+  if (payload.is_truncated === true) {
+    lines.push("List truncated; raise --limit to see more.");
+  }
+  lines.push(
+    "",
+    "Describe one (payload schema + output streams): deepline monitors available <tool-id> --json"
+  );
+  return `${lines.join("\n")}
+`;
+}
+async function handleMonitorsAvailable(toolId, options) {
+  if (toolId !== void 0 && options.tool !== void 0) {
+    if (toolId !== options.tool) {
+      throw new MonitorsUsageError(
+        `Pass the tool id once: got positional "${toolId}" and --tool "${options.tool}". Use: deepline monitors available ${toolId}`
+      );
+    }
+  }
+  const tool = toolId ?? options.tool;
   const http = buildHttpClient();
   const params = new URLSearchParams();
   if (options.provider) params.set("provider", options.provider);
-  if (options.tool) params.set("tool", options.tool);
+  if (tool) params.set("tool", tool);
   if (options.search) params.set("search", options.search);
   if (options.limit) params.set("limit", options.limit);
+  const compactList = !tool && !options.full;
+  if (compactList || options.compact) params.set("compact", "true");
   const query = params.toString();
   const payload = await http.request(
     `/api/v2/monitors/tools${query ? `?${query}` : ""}`,
     { method: "GET", ...FORBIDDEN_AS_API_ERROR }
   );
-  printCommandEnvelope(payload, { json: options.json });
+  printCommandEnvelope(payload, {
+    json: options.json,
+    // Human list view shows id + name + deployed_count ("deployed: N") so
+    // can-deploy vs already-deployed is visible in one view. Describing a
+    // single tool keeps the full JSON contract (payload schema, streams).
+    text: tool ? void 0 : renderAvailableToolsText(payload)
+  });
+}
+function renderDeployedListText(payload, requestedStatus) {
+  const monitors = Array.isArray(payload.monitors) ? payload.monitors : null;
+  if (!monitors) return void 0;
+  const lines = [
+    monitors.length === 0 ? "No deployed monitors matched." : `Deployed monitors (${monitors.length}):`
+  ];
+  for (const raw of monitors) {
+    const entry = asRecord(raw);
+    const key = entry ? asString(entry.key) ?? asString(entry.monitor_key) : void 0;
+    if (!entry || !key) continue;
+    const status = asString(entry.status);
+    const tool = asString(entry.tool);
+    const name = asString(entry.name);
+    lines.push(
+      `  ${key}${status ? `  ${status}` : ""}${tool ? `  ${tool}` : ""}${name ? `  (${name})` : ""}`
+    );
+  }
+  const applied = asString(payload.status_filter_applied) ?? requestedStatus ?? "active";
+  lines.push(
+    `Status filter: ${applied}${requestedStatus === void 0 && applied === "active" ? " (default)" : ""} \u2014 use --status all to include disabled monitors.`
+  );
+  if (monitors.length > 0) {
+    lines.push("", "Inspect one: deepline monitors get <key> --json");
+  }
+  return `${lines.join("\n")}
+`;
+}
+async function handleMonitorsList(options) {
+  const http = buildHttpClient();
+  const params = new URLSearchParams();
+  if (options.status) params.set("status", options.status);
+  if (options.limit) params.set("limit", options.limit);
+  if (options.compact) params.set("compact", "true");
+  const query = params.toString();
+  const payload = await http.request(
+    `/api/v2/monitors/deployed${query ? `?${query}` : ""}`,
+    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, {
+    json: options.json,
+    text: renderDeployedListText(payload, options.status)
+  });
 }
 async function handleMonitorsCheck(definition, options) {
   const http = buildHttpClient();
-  const body = parseJsonObjectArg(definition, "--definition");
+  const body = resolveMonitorJsonBody({
+    positional: definition,
+    file: options.file,
+    argLabel: "<definition>",
+    command: "deepline monitors check"
+  });
   const payload = await http.request(
     "/api/v2/monitors/check",
     { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
@@ -21809,26 +22590,37 @@ async function handleMonitorsCheck(definition, options) {
 }
 async function handleMonitorsDeploy(definition, options) {
   const http = buildHttpClient();
-  const body = parseJsonObjectArg(definition, "--definition");
+  const body = resolveMonitorJsonBody({
+    positional: definition,
+    file: options.file,
+    argLabel: "<definition>",
+    command: "deepline monitors deploy"
+  });
+  if (options.dryRun) {
+    const payload2 = await http.request(
+      "/api/v2/monitors/check",
+      { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+    );
+    const valid = payload2.valid !== false;
+    printCommandEnvelope(
+      { dry_run: true, ...payload2 },
+      { json: options.json, text: renderMonitorDeployPlan(payload2) }
+    );
+    if (!valid) {
+      process.exitCode = 7;
+    }
+    return;
+  }
   const payload = await http.request(
     "/api/v2/monitors/deploy",
     { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
   );
-  printCommandEnvelope(payload, { json: options.json });
-}
-async function handleDeployedList(options) {
-  const http = buildHttpClient();
-  const params = new URLSearchParams();
-  if (options.status) params.set("status", options.status);
-  if (options.limit) params.set("limit", options.limit);
-  const query = params.toString();
-  const payload = await http.request(
-    `/api/v2/monitors/deployed${query ? `?${query}` : ""}`,
-    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
-  );
-  printCommandEnvelope(payload, { json: options.json });
+  printCommandEnvelope(payload, {
+    json: options.json,
+    text: renderMonitorDeployCompletion(payload)
+  });
 }
-async function handleDeployedGet(key, options) {
+async function handleMonitorsGet(key, options) {
   const http = buildHttpClient();
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}`,
@@ -21836,10 +22628,58 @@ async function handleDeployedGet(key, options) {
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedDelete(key, options) {
+async function confirmMonitorDelete(key, options) {
+  const rl = (0, import_promises4.createInterface)({
+    input: process.stdin,
+    output: process.stderr
+  });
+  try {
+    const consequence = options.localOnly ? "This removes the Deepline record only (the upstream provider resource is left in place)." : "This deprovisions the upstream provider resource.";
+    const answer = await rl.question(
+      `Delete monitor "${key}"? ${consequence} [y/N] `
+    );
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function handleMonitorsDelete(key, options) {
   const http = buildHttpClient();
   const params = new URLSearchParams();
   if (options.localOnly) params.set("local_only", "true");
+  if (options.dryRun) {
+    params.set("dry_run", "true");
+    const payload2 = await http.request(
+      `/api/v2/monitors/deployed/${encodeKey(key)}?${params.toString()}`,
+      { method: "DELETE", ...FORBIDDEN_AS_API_ERROR }
+    );
+    assertMonitorDryRunAcknowledged(payload2, {
+      command: "deepline monitors delete",
+      mutation: "delete"
+    });
+    printCommandEnvelope(payload2, {
+      json: options.json,
+      text: renderMonitorDeletePlan(payload2, key)
+    });
+    return;
+  }
+  if (!options.yes) {
+    const interactive = process.stdout.isTTY === true && process.stdin.isTTY === true;
+    if (!interactive) {
+      throw monitorDeleteRequiresYesError(key, {
+        localOnly: options.localOnly
+      });
+    }
+    const confirmed = await confirmMonitorDelete(key, {
+      localOnly: options.localOnly
+    });
+    if (!confirmed) {
+      process.stderr.write(`Aborted. Monitor "${key}" was not deleted.
+`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   const query = params.toString();
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}${query ? `?${query}` : ""}`,
@@ -21847,17 +22687,37 @@ async function handleDeployedDelete(key, options) {
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedUpdate(key, patch, options) {
+async function handleMonitorsUpdate(key, patch, options) {
   const http = buildHttpClient();
-  const body = parseJsonObjectArg(patch, "<patch>");
+  const body = resolveMonitorJsonBody({
+    positional: patch,
+    file: options.file,
+    argLabel: "<patch>",
+    command: `deepline monitors update ${key}`
+  });
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}`,
     { method: "PATCH", body, ...FORBIDDEN_AS_API_ERROR }
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleReactivate(key, options) {
+async function handleMonitorsReactivate(key, options) {
   const http = buildHttpClient();
+  if (options.dryRun) {
+    const payload2 = await http.request(
+      `/api/v2/monitors/deployed/${encodeKey(key)}/reactivate?dry_run=true`,
+      { method: "POST", body: {}, ...FORBIDDEN_AS_API_ERROR }
+    );
+    assertMonitorDryRunAcknowledged(payload2, {
+      command: "deepline monitors reactivate",
+      mutation: "reactivate"
+    });
+    printCommandEnvelope(payload2, {
+      json: options.json,
+      text: renderMonitorReactivatePlan(payload2, key)
+    });
+    return;
+  }
   const payload = await http.request(
     `/api/v2/monitors/deployed/${encodeKey(key)}/reactivate`,
     { method: "POST", body: {}, ...FORBIDDEN_AS_API_ERROR }
@@ -21865,116 +22725,240 @@ async function handleReactivate(key, options) {
   printCommandEnvelope(payload, { json: options.json });
 }
 function registerMonitorsCommands(program) {
-  const monitors = program.command("monitors").description("Discover, deploy, and manage Deepline monitors.").addHelpText(
+  const monitors = program.command("monitors").description("Discover, deploy, and manage Deepline monitors.").showSuggestionAfterError(true).addHelpText(
     "after",
     `
 Notes:
-  Monitors are provider-backed signal feeds that deliver events into your
-  workspace. Access is granted by a Deepline admin via Admin -> Rollouts; until
-  then these commands return a clear monitor_access_required error.
+  Deepline monitors are provider-backed signal feeds: a monitor writes provider
+  events into a Customer DB table; a play reacts to each new row via a
+  sqlListeners trigger \u2014 see \`deepline plays bootstrap monitor-triggered\`.
+  Access is granted by a Deepline admin via Admin -> Rollouts; until then these
+  commands return a clear monitor_access_required error.
+
+Exit codes:
+  0 success; 2 usage/local input; 3 auth or permission; 4 not found;
+  5 server failure; 7 validation failed.
+  \`monitors status\` exits 1 when you lack monitor access (documented contract).
 
 Examples:
-  deepline monitors tools --json
-  deepline monitors check '{"key":"my-monitor","tool":"...","payload":{}}'
-  deepline monitors deploy '{"key":"my-monitor","tool":"...","payload":{}}'
-  deepline monitors deployed --json
-  deepline monitors deployed get my-monitor --json
-  deepline monitors reactivate my-monitor --json
+  deepline monitors status --json
+  deepline monitors available --json          # compact list by default
+  deepline monitors available --full --json   # complete catalog
+  deepline monitors available theirstack.saved_search_webhook --json
+  deepline monitors check '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors deploy --dry-run --file monitor.json
+  deepline monitors deploy --file monitor.json
+  deepline monitors list --status all --json
+  deepline monitors get my-monitor --json
+  deepline monitors update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors delete my-monitor --dry-run
+  deepline monitors reactivate my-monitor --dry-run
 `
   );
-  monitors.command("tools").description("List or describe the monitor tools available to your org.").addHelpText(
-    "after",
-    `
+  withJsonOption(
+    monitors.command("status").description("Check whether you have access to Deepline monitors.").addHelpText(
+      "after",
+      `
 Notes:
-  Read-only. Filter the catalog with --provider, --tool, --search, or --limit.
-  Pass --tool to describe a single monitor tool.
+  Read-only access check. Requires authentication but NOT monitor access, so it
+  is safe to run first to confirm whether you can use the monitor commands. Exits
+  0 when you have access and 1 when you do not, so agents can branch on it (this
+  exit-1 denial contract predates the typed monitor exit codes and is kept).
 
 Examples:
-  deepline monitors tools
-  deepline monitors tools --provider theirstack --json
-  deepline monitors tools --tool theirstack_jobs --json
+  deepline monitors status
+  deepline monitors status --json
 `
-  ).option("--provider <provider>", "Filter by provider").option("--tool <tool>", "Describe a single monitor tool by id").option("--search <query>", "Search monitor tools by text").option("--limit <n>", "Limit the number of monitor tools returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsTools);
-  monitors.command("check <definition>").description("Validate a monitor definition without deploying it.").addHelpText(
-    "after",
-    `
+    )
+  ).action(monitorsAction(handleMonitorsStatus));
+  withJsonOption(
+    monitors.command("available [tool-id]").alias("tools").description(
+      "List the monitor types you can deploy, or describe one by tool id."
+    ).addHelpText(
+      "after",
+      `
 Notes:
-  Read-only validation. <definition> is a JSON object with key, tool, payload,
-  and optional controls. Does not deploy or spend credits.
+  Read-only catalog of deployable monitor types. Pass a tool id positionally to
+  describe one (payload schema + output streams). Filter the list with
+  --provider, --search, or --limit. List entries include how many monitors you
+  already have deployed on each tool ("deployed: N") when the server reports it.
+  The list is compact by default (id + name + deployed count); pass --full to
+  get the complete catalog (payload schemas + output streams for every tool).
+  Describing a single tool by id always returns the full contract.
 
 Examples:
-  deepline monitors check '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+  deepline monitors available
+  deepline monitors available --full --json
+  deepline monitors available --provider theirstack --json
+  deepline monitors available theirstack.saved_search_webhook --json
+  deepline monitors available --search jobs --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsCheck);
-  monitors.command("deploy <definition>").description("Deploy a monitor from a definition.").addHelpText(
-    "after",
-    `
+    ).option("--provider <provider>", "Filter by provider").option(
+      "--tool <tool>",
+      "Describe a single monitor tool by id (same as the positional tool-id)"
+    ).option("--search <query>", "Search monitor tools by text").option("--limit <n>", "Limit the number of monitor tools returned").option(
+      "--full",
+      "Return the complete monitor catalog (payload schemas + output streams). The list is compact by default."
+    ).option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsAvailable));
+  withJsonOption(
+    monitors.command("list").description("List the monitors you have deployed.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state and may spend Deepline credits. <definition> is a JSON
-  object with key, tool, payload, and optional controls.
+  Read-only. --status filters by monitor status: active (default), disabled, or
+  all. The output echoes the status filter that was applied. --compact returns
+  high-signal fields only.
 
 Examples:
-  deepline monitors deploy '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+  deepline monitors list
+  deepline monitors list --status all --json
+  deepline monitors list --compact --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsDeploy);
-  monitors.command("reactivate <key>").description("Reactivate a previously disabled deployed monitor.").addHelpText(
-    "after",
-    `
+    ).option(
+      "--status <status>",
+      "Filter by monitor status: active (default), disabled, or all"
+    ).option("--limit <n>", "Limit the number of deployed monitors returned").option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsList));
+  withJsonOption(
+    monitors.command("get <key>").description("Show a single deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state and may spend Deepline credits.
+  Read-only.
 
 Examples:
-  deepline monitors reactivate my-monitor --json
+  deepline monitors get my-monitor --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleReactivate);
-  const deployed = monitors.command("deployed").description("List and manage your deployed monitors.").addHelpText(
-    "after",
-    `
+    )
+  ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    monitors.command("check [definition]").description("Validate a monitor definition without deploying it.").addHelpText(
+      "after",
+      `
 Notes:
-  With no subcommand, lists deployed monitors. Use get/update/delete to manage a
-  single monitor by its public key.
+  Read-only validation. <definition> is a JSON object with key, tool, payload,
+  and optional controls (Deepline lifecycle metadata, e.g.
+  "controls":{"enabled":false}). Pass it positionally, via --file <path>, or
+  from stdin with --file -. Does not deploy or spend credits.
 
 Examples:
-  deepline monitors deployed --json
-  deepline monitors deployed --status all --json
-  deepline monitors deployed get my-monitor --json
+  deepline monitors check '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors check --file monitor.json
+  cat monitor.json | deepline monitors check --file -
 `
-  ).option("--status <status>", 'Filter by monitor status (or "all")').option("--limit <n>", "Limit the number of deployed monitors returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedList);
-  deployed.command("get <key>").description("Show a single deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the definition JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsCheck));
+  withJsonOption(
+    monitors.command("deploy [definition]").description("Deploy a monitor from a definition.").addHelpText(
+      "after",
+      `
 Notes:
-  Read-only.
+  Mutates workspace state and may spend Deepline credits. <definition> is a JSON
+  object with key, tool, payload, and optional controls (e.g.
+  "controls":{"enabled":false}). Pass it positionally, via --file <path>, or
+  from stdin with --file -.
+  --dry-run validates the definition and shows the plan (deploy cost in Deepline
+  credits when the server reports it, plus any existing monitors that may
+  already cover this scope) WITHOUT deploying. Exits 0 when valid, 7 when not.
 
 Examples:
-  deepline monitors deployed get my-monitor --json
+  deepline monitors deploy '{"key":"my-monitor","tool":"theirstack.saved_search_webhook","payload":{}}'
+  deepline monitors deploy --dry-run --file monitor.json
+  deepline monitors deploy --file monitor.json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedGet);
-  deployed.command("update <key> <patch>").description("Update a deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the definition JSON from a file, or - for stdin"
+    ).option(
+      "--dry-run",
+      "Validate and show the deploy plan (cost, reuse candidates) without deploying"
+    )
+  ).action(monitorsAction(handleMonitorsDeploy));
+  withJsonOption(
+    monitors.command("update <key> [patch]").description("Update a deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state. <patch> is a JSON object of fields to update.
+  Mutates workspace state. <patch> is a JSON object of fields to update, e.g.
+  '{"controls":{"enabled":false}}' to disable a monitor. Pass it positionally,
+  via --file <path>, or from stdin with --file -.
 
 Examples:
-  deepline monitors deployed update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors update my-monitor '{"controls":{"enabled":false}}' --json
+  deepline monitors update my-monitor --file patch.json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedUpdate);
-  deployed.command("delete <key>").description("Delete a deployed monitor by its public key.").addHelpText(
-    "after",
-    `
+    ).option(
+      "-f, --file <path>",
+      "Read the patch JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsUpdate));
+  withJsonOption(
+    monitors.command("delete <key>").description("Delete a deployed monitor by its public key.").addHelpText(
+      "after",
+      `
 Notes:
-  Mutates workspace state. By default deprovisions the upstream provider
-  resource; pass --local-only to remove only the Deepline-managed record.
+  DESTRUCTIVE. By default deprovisions the upstream provider resource; pass
+  --local-only to remove only the Deepline-managed record.
+  --dry-run shows the delete plan without deleting anything.
+  Interactive terminals get a y/N confirmation; non-interactive runs (agents,
+  scripts, pipes) must pass --yes.
 
 Examples:
-  deepline monitors deployed delete my-monitor --json
-  deepline monitors deployed delete my-monitor --local-only --json
+  deepline monitors delete my-monitor --dry-run
+  deepline monitors delete my-monitor --yes --json
+  deepline monitors delete my-monitor --local-only --yes --json
 `
-  ).option(
-    "--local-only",
-    "Remove only the Deepline-managed record, leaving the upstream resource"
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedDelete);
+    ).option(
+      "--local-only",
+      "Remove only the Deepline-managed record, leaving the upstream resource"
+    ).option("--dry-run", "Show the delete plan without deleting anything").option(
+      "--yes",
+      "Skip the confirmation prompt (required non-interactively)"
+    )
+  ).action(monitorsAction(handleMonitorsDelete));
+  withJsonOption(
+    monitors.command("reactivate <key>").description("Reactivate a previously disabled deployed monitor.").addHelpText(
+      "after",
+      `
+Notes:
+  Mutates workspace state and may spend Deepline credits.
+  --dry-run shows the reactivation cost (in Deepline credits) without changing
+  anything.
+
+Examples:
+  deepline monitors reactivate my-monitor --dry-run
+  deepline monitors reactivate my-monitor --json
+`
+    ).option("--dry-run", "Show the reactivation cost without reactivating")
+  ).action(monitorsAction(handleMonitorsReactivate));
+  const deployed = withJsonOption(
+    monitors.command("deployed", { hidden: true }).description("Alias of `monitors list` (plus get/update/delete aliases).").option(
+      "--status <status>",
+      "Filter by monitor status: active (default), disabled, or all"
+    ).option("--limit <n>", "Limit the number of deployed monitors returned").option("--compact", COMPACT_OPTION_DESCRIPTION)
+  ).action(monitorsAction(handleMonitorsList));
+  withJsonOption(
+    deployed.command("get <key>").description("Alias of `monitors get <key>`.")
+  ).action(monitorsAction(handleMonitorsGet));
+  withJsonOption(
+    deployed.command("update <key> [patch]").description("Alias of `monitors update <key>`.").option(
+      "-f, --file <path>",
+      "Read the patch JSON from a file, or - for stdin"
+    )
+  ).action(monitorsAction(handleMonitorsUpdate));
+  withJsonOption(
+    deployed.command("delete <key>").description("Alias of `monitors delete <key>`.").option(
+      "--local-only",
+      "Remove only the Deepline-managed record, leaving the upstream resource"
+    ).option("--dry-run", "Show the delete plan without deleting anything").option(
+      "--yes",
+      "Skip the confirmation prompt (required non-interactively)"
+    )
+  ).action(monitorsAction(handleMonitorsDelete));
 }
 
 // src/cli/commands/org.ts
@@ -22999,7 +23983,7 @@ Examples:
 }
 
 // src/cli/commands/switch.ts
-var import_node_fs12 = require("fs");
+var import_node_fs13 = require("fs");
 var import_node_os10 = require("os");
 var import_node_path14 = require("path");
 function hostSlugFromBaseUrl(baseUrl) {
@@ -23034,15 +24018,15 @@ function activeFamilyPath() {
 function readActiveFamily() {
   const path = activeFamilyPath();
   try {
-    return (0, import_node_fs12.readFileSync)(path, "utf-8").trim() || "sdk";
+    return (0, import_node_fs13.readFileSync)(path, "utf-8").trim() || "sdk";
   } catch {
     return "sdk";
   }
 }
 function writeActiveFamily(family) {
   const path = activeFamilyPath();
-  (0, import_node_fs12.mkdirSync)((0, import_node_path14.dirname)(path), { recursive: true });
-  (0, import_node_fs12.writeFileSync)(path, `${family}
+  (0, import_node_fs13.mkdirSync)((0, import_node_path14.dirname)(path), { recursive: true });
+  (0, import_node_fs13.writeFileSync)(path, `${family}
 `, "utf-8");
   return path;
 }
@@ -23059,7 +24043,7 @@ function handleSwitch(action, options) {
         ok: true,
         active_family: activeFamily,
         active_family_path: path,
-        active_family_file_exists: (0, import_node_fs12.existsSync)(path),
+        active_family_file_exists: (0, import_node_fs13.existsSync)(path),
         render: {
           sections: [
             {
@@ -23159,12 +24143,12 @@ Examples:
 
 // src/cli/commands/tools.ts
 var import_commander2 = require("commander");
-var import_node_fs14 = require("fs");
+var import_node_fs15 = require("fs");
 var import_node_os12 = require("os");
 var import_node_path16 = require("path");
 
 // src/tool-output.ts
-var import_node_fs13 = require("fs");
+var import_node_fs14 = require("fs");
 var import_node_os11 = require("os");
 var import_node_path15 = require("path");
 function isPlainObject(value) {
@@ -23294,18 +24278,18 @@ function projectRowOutput(conversion) {
 }
 function ensureOutputDir() {
   const outputDir = (0, import_node_path15.join)((0, import_node_os11.homedir)(), ".local", "share", "deepline", "data");
-  (0, import_node_fs13.mkdirSync)(outputDir, { recursive: true });
+  (0, import_node_fs14.mkdirSync)(outputDir, { recursive: true });
   return outputDir;
 }
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
   const outputPath = (0, import_node_path15.join)(outputDir, `${stem}_${Date.now()}.json`);
-  (0, import_node_fs13.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
+  (0, import_node_fs14.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem, options) {
   const outputPath = options?.outPath ? options.outPath : (0, import_node_path15.join)(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
-  (0, import_node_fs13.mkdirSync)((0, import_node_path15.dirname)(outputPath), { recursive: true });
+  (0, import_node_fs14.mkdirSync)((0, import_node_path15.dirname)(outputPath), { recursive: true });
   const columns = columnsForRows(rows);
   const escapeCell = (value) => {
     const normalized = value == null ? "" : typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value);
@@ -23314,19 +24298,19 @@ function writeCsvOutputFile(rows, stem, options) {
     }
     return normalized;
   };
-  const fd = (0, import_node_fs13.openSync)(outputPath, "w");
+  const fd = (0, import_node_fs14.openSync)(outputPath, "w");
   try {
-    (0, import_node_fs13.writeSync)(fd, `${columns.map(escapeCell).join(",")}
+    (0, import_node_fs14.writeSync)(fd, `${columns.map(escapeCell).join(",")}
 `);
     for (const row of rows) {
-      (0, import_node_fs13.writeSync)(
+      (0, import_node_fs14.writeSync)(
         fd,
         `${columns.map((column) => escapeCell(row[column])).join(",")}
 `
       );
     }
   } finally {
-    (0, import_node_fs13.closeSync)(fd);
+    (0, import_node_fs14.closeSync)(fd);
   }
   const previewRows = rows.slice(0, 5);
   const previewColumns = columns.slice(0, 5);
@@ -24540,10 +25524,10 @@ function normalizeOutputFormat(raw) {
 function resolveAtFilePath(rawPath) {
   const trimmed = rawPath.trim();
   const resolved = (0, import_node_path16.resolve)(trimmed);
-  if ((0, import_node_fs14.existsSync)(resolved)) return resolved;
+  if ((0, import_node_fs15.existsSync)(resolved)) return resolved;
   if (process.platform !== "win32" && trimmed.includes("\\")) {
     const normalized = (0, import_node_path16.resolve)(trimmed.replace(/\\/g, "/"));
-    if ((0, import_node_fs14.existsSync)(normalized)) return normalized;
+    if ((0, import_node_fs15.existsSync)(normalized)) return normalized;
   }
   return resolved;
 }
@@ -24554,7 +25538,7 @@ function readJsonArgument(raw, flagName) {
     throw new Error(`Invalid ${flagName} value: empty @file path.`);
   }
   try {
-    return (0, import_node_fs14.readFileSync)(resolveAtFilePath(filePath), "utf8").replace(
+    return (0, import_node_fs15.readFileSync)(resolveAtFilePath(filePath), "utf8").replace(
       /^\uFEFF/,
       ""
     );
@@ -24661,8 +25645,8 @@ function starterScriptJson(script) {
 function seedToolListScript(input2) {
   const stem = safeFileStem(input2.toolId);
   const fileName = `${stem}-workflow-seed-${Date.now()}.play.ts`;
-  const scriptDir = (0, import_node_fs14.mkdtempSync)((0, import_node_path16.join)((0, import_node_os12.tmpdir)(), "deepline-workflow-seed-"));
-  (0, import_node_fs14.chmodSync)(scriptDir, 448);
+  const scriptDir = (0, import_node_fs15.mkdtempSync)((0, import_node_path16.join)((0, import_node_os12.tmpdir)(), "deepline-workflow-seed-"));
+  (0, import_node_fs15.chmodSync)(scriptDir, 448);
   const scriptPath = (0, import_node_path16.join)(scriptDir, fileName);
   const projectDir = `deepline/projects/${stem}-workflow`;
   const playName = `${stem}-workflow`;
@@ -24706,7 +25690,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   description: ${JSON.stringify(`Seed ${input2.toolId} rows into a Deepline workflow-ready dataset.`)},
 });
 `;
-  (0, import_node_fs14.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
+  (0, import_node_fs15.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
     sourceCode: script,
@@ -25036,7 +26020,7 @@ async function executeTool(args) {
 }
 
 // src/cli/commands/workflow.ts
-var import_promises4 = require("fs/promises");
+var import_promises5 = require("fs/promises");
 var import_node_path17 = require("path");
 
 // src/cli/workflow-to-play.ts
@@ -25224,9 +26208,10 @@ var PLAY_EQUIVALENT = {
   delete: "deepline plays delete <name>"
 };
 var MIGRATE_HINT = "deepline workflows transform <id>";
-var JSON_OPTION_DESCRIPTION = "Emit JSON output. Also automatic when stdout is piped";
-function withJsonOption(command) {
-  return command.option("--json", JSON_OPTION_DESCRIPTION);
+var TRIGGER_REDIRECT = "Looking to trigger a play automatically? Use a trigger binding in definePlay \u2014 `cron`/`webhook`, or `sqlListeners` to run on a monitor\u2019s output (see `deepline monitors available <id>` for a monitor\u2019s streams and the deepline-monitors skill). `workflows` only manages prebuilt plays and is deprecated in favor of `plays`.";
+var JSON_OPTION_DESCRIPTION2 = "Emit JSON output. Also automatic when stdout is piped";
+function withJsonOption2(command) {
+  return command.option("--json", JSON_OPTION_DESCRIPTION2);
 }
 var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
   "completed",
@@ -25251,6 +26236,7 @@ function noticeToStderr(command) {
     `note: \`deepline workflows ${command}\` is a legacy surface \u2014 workflows are becoming plays.
       equivalent: \`${deprecation.use}\`
       migrate this workflow: \`${MIGRATE_HINT}\`
+      ${TRIGGER_REDIRECT}
 `
   );
 }
@@ -25281,7 +26267,7 @@ function readStatus(payload) {
 }
 async function readJsonOption(payload, file) {
   if (file) {
-    const raw = await (0, import_promises4.readFile)((0, import_node_path17.resolve)(file), "utf8");
+    const raw = await (0, import_promises5.readFile)((0, import_node_path17.resolve)(file), "utf8");
     return JSON.parse(raw);
   }
   if (payload) {
@@ -25316,8 +26302,8 @@ async function transformOne(api, workflowId, outDir, publish) {
       { workflowName: workflow.name, version: revision.version }
     );
     const file = (0, import_node_path17.join)((0, import_node_path17.resolve)(outDir), `${compiled.playName}.play.ts`);
-    await (0, import_promises4.mkdir)((0, import_node_path17.dirname)(file), { recursive: true });
-    await (0, import_promises4.writeFile)(file, compiled.sourceCode, "utf8");
+    await (0, import_promises5.mkdir)((0, import_node_path17.dirname)(file), { recursive: true });
+    await (0, import_promises5.writeFile)(file, compiled.sourceCode, "utf8");
     let published = false;
     if (publish) {
       const code = await handlePlayPublish([file]);
@@ -25484,7 +26470,7 @@ async function handleTail(id, runId, options) {
 }
 function registerWorkflowCommands(program) {
   const workflows = program.command("workflows").description(
-    "Legacy cloud workflows (now becoming plays). Commands still work; use `workflows transform` to migrate one to a play."
+    "Legacy cloud workflows (now becoming plays). Commands still work; use `workflows transform` to migrate one to a play. " + TRIGGER_REDIRECT
   ).addHelpText(
     "after",
     `
@@ -25496,9 +26482,13 @@ keep working, but new work belongs in plays. Migrate a workflow with:
 
 Equivalents: list\u2192plays list \xB7 call\u2192plays run \xB7 apply\u2192plays publish \xB7
 lint\u2192plays check \xB7 runs\u2192runs list.
+
+${TRIGGER_REDIRECT}
+Add the binding as the third arg to definePlay in your .play.ts; the
+deepline-monitors skill has a monitor-triggered example.
 `
   );
-  withJsonOption(
+  withJsonOption2(
     workflows.command("transform [id]").description("Compile a workflow into a reviewable V2 play (.play.ts).").option("--all", "Transform every workflow in the workspace").option("--out <dir>", "Output directory for generated plays", "./plays").option("--publish", "Publish each clean play immediately")
   ).addHelpText(
     "after",
@@ -25515,61 +26505,61 @@ Notes:
   ).action(async (id, options) => {
     process.exitCode = await handleTransform(id, options);
   });
-  withJsonOption(
+  withJsonOption2(
     workflows.command("list").description("List workspace workflows.").option("--limit <n>", "Max workflows to return")
   ).action(handleList2);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("get <id>").description(
       "Fetch a workflow, including its published-revision config."
     )
   ).action(handleGet);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("disable <id>").description("Turn a workflow off.")
   ).action(handleDisable);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("enable <id>").description("Turn a workflow back on.")
   ).action(handleEnable);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("delete <id>").description("Delete a workflow and its revisions/runs.")
   ).action(handleDelete);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("apply").description("Create or update a workflow from config.").option("--payload <json>", "Inline config JSON").option("--file <path>", "Path to a config JSON file")
   ).action(handleApply);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("lint").description("Validate a workflow config without saving.").option("--payload <json>", "Inline config JSON").option("--file <path>", "Path to a config JSON file")
   ).action(handleLint);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("schema").description("Fetch live workflow request schemas.").option(
       "--subject <subject>",
       "Schema subject (apply|call|trigger|all|\u2026)"
     )
   ).action(handleSchema);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("call").description("Queue a workflow run.").option("--workflow-id <id>", "Workflow id").option("--workflow-name <name>", "Workflow name").option("--payload <json>", "Run input JSON").option("--mode <mode>", "live | dry_run | smoke_test")
   ).action(handleCall);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("runs <id>").description("List a workflow\u2019s runs.").option("--limit <n>", "Max runs to return")
   ).action(handleRuns);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("run <id> <runId>").description("Fetch a single workflow run.")
   ).action(handleRun);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("tail <id> <runId>").description("Poll a workflow run until it reaches a terminal status.").option("--interval-ms <n>", "Poll interval in ms (default 2000)")
   ).action(handleTail);
-  withJsonOption(
+  withJsonOption2(
     workflows.command("cancel <id> <runId>").description("Cancel a running workflow run.")
   ).action(handleCancel);
 }
 
 // src/cli/commands/update.ts
 var import_node_child_process4 = require("child_process");
-var import_node_fs16 = require("fs");
+var import_node_fs17 = require("fs");
 var import_node_os13 = require("os");
 var import_node_path19 = require("path");
 
 // src/cli/skills-sync.ts
 var import_node_child_process3 = require("child_process");
-var import_node_fs15 = require("fs");
+var import_node_fs16 = require("fs");
 var import_node_path18 = require("path");
 
 // ../shared_libs/cli/install-commands.json
@@ -25692,13 +26682,13 @@ function activePluginSkillsDir() {
     return "";
   }
   const dir = process.env.DEEPLINE_PLUGIN_SKILLS_DIR?.trim() ?? "";
-  return dir && (0, import_node_fs15.existsSync)(dir) ? dir : "";
+  return dir && (0, import_node_fs16.existsSync)(dir) ? dir : "";
 }
 function readPluginSkillsVersion() {
   const dir = activePluginSkillsDir();
   if (!dir) return "";
   try {
-    return (0, import_node_fs15.readFileSync)((0, import_node_path18.join)(dir, ".version"), "utf-8").trim();
+    return (0, import_node_fs16.readFileSync)((0, import_node_path18.join)(dir, ".version"), "utf-8").trim();
   } catch {
     return "";
   }
@@ -25712,18 +26702,18 @@ function legacySdkSkillsVersionPath(baseUrl) {
 function readSdkSkillsLocalVersion(baseUrl) {
   const pluginVersion = readPluginSkillsVersion();
   if (pluginVersion) return pluginVersion;
-  const path = (0, import_node_fs15.existsSync)(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
-  if (!(0, import_node_fs15.existsSync)(path)) return "";
+  const path = (0, import_node_fs16.existsSync)(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
+  if (!(0, import_node_fs16.existsSync)(path)) return "";
   try {
-    return (0, import_node_fs15.readFileSync)(path, "utf-8").trim();
+    return (0, import_node_fs16.readFileSync)(path, "utf-8").trim();
   } catch {
     return "";
   }
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  (0, import_node_fs15.mkdirSync)((0, import_node_path18.dirname)(path), { recursive: true });
-  (0, import_node_fs15.writeFileSync)(path, `${version}
+  (0, import_node_fs16.mkdirSync)((0, import_node_path18.dirname)(path), { recursive: true });
+  (0, import_node_fs16.writeFileSync)(path, `${version}
 `, "utf-8");
 }
 function sortedUniqueSkillNames(names) {
@@ -26010,7 +27000,7 @@ function sidecarStateDir(input2) {
 }
 function readOptionalText(path) {
   try {
-    return (0, import_node_fs16.readFileSync)(path, "utf8").trim();
+    return (0, import_node_fs17.readFileSync)(path, "utf8").trim();
   } catch {
     return "";
   }
@@ -26054,7 +27044,7 @@ function resolvePythonSidecarUpdatePlan(options) {
 function findRepoBackedSdkRoot(startPath) {
   let current = (0, import_node_path19.resolve)(startPath);
   while (true) {
-    if ((0, import_node_fs16.existsSync)((0, import_node_path19.join)(current, "sdk", "package.json")) && (0, import_node_fs16.existsSync)((0, import_node_path19.join)(current, "sdk", "bin", "deepline-dev.ts"))) {
+    if ((0, import_node_fs17.existsSync)((0, import_node_path19.join)(current, "sdk", "package.json")) && (0, import_node_fs17.existsSync)((0, import_node_path19.join)(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
     }
     const parent = (0, import_node_path19.dirname)(current);
@@ -26065,7 +27055,7 @@ function findRepoBackedSdkRoot(startPath) {
 function inferNpmGlobalPrefixFromEntrypoint(entrypoint) {
   const normalized = (() => {
     try {
-      return (0, import_node_fs16.realpathSync)(entrypoint);
+      return (0, import_node_fs17.realpathSync)(entrypoint);
     } catch {
       return (0, import_node_path19.resolve)(entrypoint);
     }
@@ -26145,7 +27135,7 @@ function readAutoUpdateFailure(plan) {
   if (!path) return null;
   try {
     const parsed = JSON.parse(
-      (0, import_node_fs16.readFileSync)(path, "utf8")
+      (0, import_node_fs17.readFileSync)(path, "utf8")
     );
     if ((parsed.kind === "npm-global" || parsed.kind === "python-sidecar") && typeof parsed.packageSpec === "string" && typeof parsed.failedAt === "string" && typeof parsed.exitCode === "number" && typeof parsed.manualCommand === "string") {
       return parsed;
@@ -26166,8 +27156,8 @@ function writeAutoUpdateFailure(plan, exitCode) {
     manualCommand: plan.manualCommand
   };
   try {
-    (0, import_node_fs16.mkdirSync)((0, import_node_path19.dirname)(path), { recursive: true });
-    (0, import_node_fs16.writeFileSync)(path, `${JSON.stringify(marker, null, 2)}
+    (0, import_node_fs17.mkdirSync)((0, import_node_path19.dirname)(path), { recursive: true });
+    (0, import_node_fs17.writeFileSync)(path, `${JSON.stringify(marker, null, 2)}
 `, "utf8");
   } catch {
   }
@@ -26176,7 +27166,7 @@ function clearAutoUpdateFailure(plan) {
   const path = autoUpdateFailurePath(plan);
   if (!path) return;
   try {
-    (0, import_node_fs16.unlinkSync)(path);
+    (0, import_node_fs17.unlinkSync)(path);
   } catch {
   }
 }
@@ -26229,7 +27219,7 @@ function installedPackageVersion(versionDir) {
     "package.json"
   );
   try {
-    const parsed = JSON.parse((0, import_node_fs16.readFileSync)(packageJsonPath, "utf8"));
+    const parsed = JSON.parse((0, import_node_fs17.readFileSync)(packageJsonPath, "utf8"));
     return typeof parsed.version === "string" ? safeVersionSegment(parsed.version) : "";
   } catch {
     return "";
@@ -26261,9 +27251,9 @@ function runCommand(command, args, env = process.env, options = {}) {
   });
 }
 function writeSidecarLauncher(input2) {
-  (0, import_node_fs16.mkdirSync)((0, import_node_path19.dirname)(input2.path), { recursive: true });
+  (0, import_node_fs17.mkdirSync)((0, import_node_path19.dirname)(input2.path), { recursive: true });
   if (process.platform === "win32") {
-    (0, import_node_fs16.writeFileSync)(
+    (0, import_node_fs17.writeFileSync)(
       input2.path,
       [
         `@set DEEPLINE_HOST_URL=${input2.hostUrl.replace(/\r?\n/g, "")}`,
@@ -26275,7 +27265,7 @@ function writeSidecarLauncher(input2) {
     );
     return;
   }
-  (0, import_node_fs16.writeFileSync)(
+  (0, import_node_fs17.writeFileSync)(
     input2.path,
     [
       "#!/usr/bin/env sh",
@@ -26293,9 +27283,9 @@ async function runPythonSidecarUpdatePlan(plan, options = {}) {
     versionsDir,
     `.tmp-sdk-update-${process.pid}-${Date.now()}`
   );
-  (0, import_node_fs16.rmSync)(tempDir, { recursive: true, force: true });
-  (0, import_node_fs16.mkdirSync)(tempDir, { recursive: true });
-  (0, import_node_fs16.writeFileSync)((0, import_node_path19.join)(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
+  (0, import_node_fs17.rmSync)(tempDir, { recursive: true, force: true });
+  (0, import_node_fs17.mkdirSync)(tempDir, { recursive: true });
+  (0, import_node_fs17.writeFileSync)((0, import_node_path19.join)(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
   const env = {
     ...process.env,
     PATH: `${(0, import_node_path19.dirname)(plan.nodeBin)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
@@ -26313,7 +27303,7 @@ async function runPythonSidecarUpdatePlan(plan, options = {}) {
     options
   );
   if (installExitCode !== 0) {
-    (0, import_node_fs16.rmSync)(tempDir, { recursive: true, force: true });
+    (0, import_node_fs17.rmSync)(tempDir, { recursive: true, force: true });
     return installExitCode;
   }
   const installedVersion = installedPackageVersion(tempDir);
@@ -26321,19 +27311,19 @@ async function runPythonSidecarUpdatePlan(plan, options = {}) {
     process.stderr.write(
       "Updated Deepline SDK package did not report a version.\n"
     );
-    (0, import_node_fs16.rmSync)(tempDir, { recursive: true, force: true });
+    (0, import_node_fs17.rmSync)(tempDir, { recursive: true, force: true });
     return 1;
   }
   const finalDir = (0, import_node_path19.join)(versionsDir, installedVersion);
   const finalEntryPath = entryPathInVersionDir(finalDir);
-  if ((0, import_node_fs16.existsSync)(finalEntryPath)) {
-    (0, import_node_fs16.rmSync)(tempDir, { recursive: true, force: true });
+  if ((0, import_node_fs17.existsSync)(finalEntryPath)) {
+    (0, import_node_fs17.rmSync)(tempDir, { recursive: true, force: true });
   } else {
-    (0, import_node_fs16.rmSync)(finalDir, { recursive: true, force: true });
+    (0, import_node_fs17.rmSync)(finalDir, { recursive: true, force: true });
     try {
-      (0, import_node_fs16.renameSync)(tempDir, finalDir);
+      (0, import_node_fs17.renameSync)(tempDir, finalDir);
     } catch (error) {
-      (0, import_node_fs16.rmSync)(tempDir, { recursive: true, force: true });
+      (0, import_node_fs17.rmSync)(tempDir, { recursive: true, force: true });
       process.stderr.write(
         `Failed to publish Deepline SDK sidecar update: ${error.message}
 `
@@ -26341,7 +27331,7 @@ async function runPythonSidecarUpdatePlan(plan, options = {}) {
       return 1;
     }
   }
-  if (!(0, import_node_fs16.existsSync)(finalEntryPath)) {
+  if (!(0, import_node_fs17.existsSync)(finalEntryPath)) {
     process.stderr.write(
       `Updated Deepline SDK CLI entrypoint missing: ${finalEntryPath}
 `
@@ -26355,27 +27345,27 @@ async function runPythonSidecarUpdatePlan(plan, options = {}) {
     nodeBin: plan.nodeBin,
     entryPath: finalEntryPath
   });
-  (0, import_node_fs16.writeFileSync)(
+  (0, import_node_fs17.writeFileSync)(
     (0, import_node_path19.join)(plan.stateDir, ".version"),
     `${installedVersion}
 `,
     "utf8"
   );
-  (0, import_node_fs16.writeFileSync)(
+  (0, import_node_fs17.writeFileSync)(
     (0, import_node_path19.join)(plan.stateDir, ".install-method"),
     "python-sidecar\n",
     "utf8"
   );
-  (0, import_node_fs16.writeFileSync)(
+  (0, import_node_fs17.writeFileSync)(
     (0, import_node_path19.join)(plan.stateDir, ".command-path"),
     `${plan.sidecarPath}
 `,
     "utf8"
   );
-  (0, import_node_fs16.writeFileSync)((0, import_node_path19.join)(plan.stateDir, ".runner"), "node\n", "utf8");
-  (0, import_node_fs16.writeFileSync)((0, import_node_path19.join)(plan.stateDir, ".node-bin"), `${plan.nodeBin}
+  (0, import_node_fs17.writeFileSync)((0, import_node_path19.join)(plan.stateDir, ".runner"), "node\n", "utf8");
+  (0, import_node_fs17.writeFileSync)((0, import_node_path19.join)(plan.stateDir, ".node-bin"), `${plan.nodeBin}
 `, "utf8");
-  (0, import_node_fs16.writeFileSync)(
+  (0, import_node_fs17.writeFileSync)(
     (0, import_node_path19.join)(plan.stateDir, ".entry-path"),
     `${finalEntryPath}
 `,
@@ -26979,10 +27969,10 @@ function topLevelCommandKnown(program, commandName) {
   );
 }
 async function runPlayRunnerHealthCheck() {
-  const dir = await (0, import_promises5.mkdtemp)((0, import_node_path20.join)((0, import_node_os15.tmpdir)(), "deepline-health-play-"));
+  const dir = await (0, import_promises6.mkdtemp)((0, import_node_path20.join)((0, import_node_os15.tmpdir)(), "deepline-health-play-"));
   const file = (0, import_node_path20.join)(dir, "health-check.play.ts");
   try {
-    await (0, import_promises5.writeFile)(
+    await (0, import_promises6.writeFile)(
       file,
       [
         "import { definePlay } from 'deepline';",
@@ -27032,7 +28022,7 @@ async function runPlayRunnerHealthCheck() {
       }
     };
   } finally {
-    await (0, import_promises5.rm)(dir, { recursive: true, force: true });
+    await (0, import_promises6.rm)(dir, { recursive: true, force: true });
   }
 }
 function pickString(value, ...keys) {