deepline 0.1.186 → 0.1.187

package/dist/cli/index.mjs

@@ -608,10 +608,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.187",
   apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.186",
+    latest: "0.1.187",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -8305,13 +8305,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`
     );
   }
@@ -8319,7 +8461,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.` : "")
     );
@@ -9528,7 +9670,25 @@ function renderPlayBootstrapError(error) {
   console.error(errorMessage2(error));
   return error instanceof PlayBootstrapError ? error.exitCode : 1;
 }
+function writeBootstrapSource(source, out) {
+  if (out) {
+    writeFileSync8(resolve7(out), source, "utf-8");
+    process.stdout.write(`Wrote ${resolve7(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);
@@ -9538,20 +9698,15 @@ async function runPlayBootstrap(args) {
     ...contracts,
     ...csvContext
   });
-  if (options.out) {
-    writeFileSync8(resolve7(options.out), source, "utf-8");
-    process.stdout.write(`Wrote ${resolve7(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:
@@ -9575,6 +9730,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
@@ -9604,6 +9766,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>",
@@ -9620,7 +9785,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] : [],
@@ -9630,6 +9801,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] : []
     ]);
   });
@@ -13554,6 +13727,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)) {
@@ -13686,16 +13942,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;
@@ -21797,44 +22064,455 @@ Examples:
 }
 
 // src/cli/commands/monitors.ts
+import { readFileSync as readFileSync9 } from "fs";
+import { createInterface } from "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) => readFileSync9(path, "utf-8"));
+  const readStdin = input2.readStdin ?? (() => readFileSync9(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 }
@@ -21843,26 +22521,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)}`,
@@ -21870,10 +22559,58 @@ async function handleDeployedGet(key, options) {
   );
   printCommandEnvelope(payload, { json: options.json });
 }
-async function handleDeployedDelete(key, options) {
+async function confirmMonitorDelete(key, options) {
+  const rl = 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}` : ""}`,
@@ -21881,17 +22618,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 }
@@ -21899,116 +22656,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
@@ -23033,7 +23914,7 @@ Examples:
 }
 
 // src/cli/commands/switch.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync9, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir9 } from "os";
 import { dirname as dirname9, join as join9 } from "path";
 function hostSlugFromBaseUrl(baseUrl) {
@@ -23068,7 +23949,7 @@ function activeFamilyPath() {
 function readActiveFamily() {
   const path = activeFamilyPath();
   try {
-    return readFileSync9(path, "utf-8").trim() || "sdk";
+    return readFileSync10(path, "utf-8").trim() || "sdk";
   } catch {
     return "sdk";
   }
@@ -23197,7 +24078,7 @@ import {
   chmodSync,
   existsSync as existsSync10,
   mkdtempSync,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   writeFileSync as writeFileSync13
 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
@@ -24600,7 +25481,7 @@ function readJsonArgument(raw, flagName) {
     throw new Error(`Invalid ${flagName} value: empty @file path.`);
   }
   try {
-    return readFileSync10(resolveAtFilePath(filePath), "utf8").replace(
+    return readFileSync11(resolveAtFilePath(filePath), "utf8").replace(
       /^\uFEFF/,
       ""
     );
@@ -25270,9 +26151,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",
@@ -25297,6 +26179,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}
 `
   );
 }
@@ -25530,7 +26413,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",
     `
@@ -25542,9 +26425,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",
@@ -25561,48 +26448,48 @@ 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);
 }
@@ -25613,7 +26500,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   realpathSync as realpathSync3,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
   unlinkSync,
@@ -25624,7 +26511,7 @@ import { dirname as dirname13, isAbsolute as isAbsolute2, join as join14, relati
 
 // src/cli/skills-sync.ts
 import { spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
 import { dirname as dirname12, join as join13 } from "path";
 
 // ../shared_libs/cli/install-commands.json
@@ -25753,7 +26640,7 @@ function readPluginSkillsVersion() {
   const dir = activePluginSkillsDir();
   if (!dir) return "";
   try {
-    return readFileSync11(join13(dir, ".version"), "utf-8").trim();
+    return readFileSync12(join13(dir, ".version"), "utf-8").trim();
   } catch {
     return "";
   }
@@ -25770,7 +26657,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
   const path = existsSync11(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
   if (!existsSync11(path)) return "";
   try {
-    return readFileSync11(path, "utf-8").trim();
+    return readFileSync12(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -26065,7 +26952,7 @@ function sidecarStateDir(input2) {
 }
 function readOptionalText(path) {
   try {
-    return readFileSync12(path, "utf8").trim();
+    return readFileSync13(path, "utf8").trim();
   } catch {
     return "";
   }
@@ -26200,7 +27087,7 @@ function readAutoUpdateFailure(plan) {
   if (!path) return null;
   try {
     const parsed = JSON.parse(
-      readFileSync12(path, "utf8")
+      readFileSync13(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;
@@ -26284,7 +27171,7 @@ function installedPackageVersion(versionDir) {
     "package.json"
   );
   try {
-    const parsed = JSON.parse(readFileSync12(packageJsonPath, "utf8"));
+    const parsed = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
     return typeof parsed.version === "string" ? safeVersionSegment(parsed.version) : "";
   } catch {
     return "";