deepline 0.1.23 → 0.1.25

package/dist/cli/index.js

@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/index.ts
-var import_commander = require("commander");
+var import_commander2 = require("commander");
 
 // src/config.ts
 var import_node_fs = require("fs");
@@ -266,7 +266,7 @@ function saveProjectDeeplineEnvValues(baseUrl, values, startDir = projectEnvStar
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.23";
+var SDK_VERSION = "0.1.25";
 var SDK_API_CONTRACT = "2026-05-runs-v2";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
@@ -548,7 +548,7 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 
 // src/client.ts
@@ -556,7 +556,7 @@ var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "ca
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -2041,7 +2041,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep3(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -2348,18 +2348,48 @@ function registerAuthCommands(program) {
     `
 Common commands:
   deepline auth register
+  deepline auth register --no-wait
+  deepline auth wait --timeout 300
   deepline auth status
   deepline auth status --json
+
+Notes:
+  Registration opens a browser approval page by default. Use --no-wait in CI
+  or agent runs, then finish with deepline auth wait.
+  Auth status shows the target host and active workspace without printing secrets.
 `
   );
-  auth.command("register").description("Register this device and open the approval page in your browser.").option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--no-wait", "Return immediately after opening the approval page").action(async (options) => {
+  auth.command("register").description("Register this device and open the approval page in your browser.").addHelpText(
+    "after",
+    `
+Notes:
+  Opens a browser approval page and waits for approval unless --no-wait is set.
+  The saved API key is scoped to the selected workspace and host.
+
+Examples:
+  deepline auth register
+  deepline auth register --org-name Acme --agent-name local-cli
+  deepline auth register --no-wait
+`
+  ).option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--no-wait", "Return immediately after opening the approval page").action(async (options) => {
     process.exitCode = await handleRegister([
       ...options.orgName ? ["--org-name", options.orgName] : [],
       ...options.agentName ? ["--agent-name", options.agentName] : [],
       ...options.noWait || options.wait === false ? ["--no-wait"] : []
     ]);
   });
-  auth.command("wait").description("Wait for a pending browser approval and save the API key.").option("--timeout <seconds>", "Maximum seconds to wait", "300").action(async (options) => {
+  auth.command("wait").description("Wait for a pending browser approval and save the API key.").addHelpText(
+    "after",
+    `
+Notes:
+  Completes a previous deepline auth register --no-wait flow.
+  Saves the approved API key into the host auth file.
+
+Examples:
+  deepline auth wait
+  deepline auth wait --timeout 120
+`
+  ).option("--timeout <seconds>", "Maximum seconds to wait", "300").action(async (options) => {
     process.exitCode = await handleWait([
       ...options.timeout ? ["--timeout", options.timeout] : []
     ]);
@@ -2385,6 +2415,10 @@ Examples:
 }
 
 // src/cli/commands/billing.ts
+var import_commander = require("commander");
+var import_promises2 = require("fs/promises");
+var import_node_path4 = require("path");
+var import_sync3 = require("csv-stringify/sync");
 function humanize(value) {
   return String(value || "").split("_").filter(Boolean).map((token) => token[0]?.toUpperCase() + token.slice(1)).join(" ") || "Unknown";
 }
@@ -2402,6 +2436,54 @@ function printRecentUsage(entries) {
 `);
   }
 }
+function summarizeLedgerRows(summary, rows) {
+  const netDelta = rows.reduce((sum, row) => {
+    const value = Number.parseFloat(String(row.delta_credits ?? "").trim());
+    return Number.isFinite(value) ? sum + value : sum;
+  }, summary.net_delta_credits);
+  return {
+    row_count: summary.row_count + rows.length,
+    net_delta_credits: Math.round((netDelta + Number.EPSILON) * 100) / 100
+  };
+}
+function ledgerApiEntryToRow(entry) {
+  const metadata = typeof entry.metadata === "object" && entry.metadata !== null ? entry.metadata : {};
+  return {
+    created_at: entry.created_at ?? "",
+    delta_credits: entry.delta ?? "",
+    reason: entry.reason ?? "",
+    provider: metadata.provider ?? "",
+    operation: metadata.operation ?? "",
+    request_id: metadata.requestId ?? metadata.request_id ?? "",
+    run_id: metadata.runId ?? metadata.run_id ?? "",
+    api_key_id: entry.api_key_id ?? "",
+    stripe_session_id: entry.stripe_session_id ?? ""
+  };
+}
+function ledgerRowsToCsv(rows, header) {
+  return (0, import_sync3.stringify)(rows, {
+    header,
+    columns: [
+      "created_at",
+      "delta_credits",
+      "reason",
+      "provider",
+      "operation",
+      "request_id",
+      "run_id",
+      "api_key_id",
+      "stripe_session_id"
+    ]
+  });
+}
+function defaultLedgerExportPath() {
+  return (0, import_node_path4.resolve)(
+    process.cwd(),
+    "deepline",
+    "data",
+    `billing-ledger-all-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.csv`
+  );
+}
 async function handleBalance(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.get("/api/v2/billing/balance");
@@ -2490,6 +2572,51 @@ async function handleHistory(options) {
   process.stdout.write(`${rows.length} row(s) exported.
 `);
 }
+async function handleLedgerExportAll(options) {
+  const { http } = getAuthedHttpClient();
+  const outputPath = options.output ? (0, import_node_path4.resolve)(String(options.output)) : defaultLedgerExportPath();
+  let summary = { row_count: 0, net_delta_credits: 0 };
+  let cursor = null;
+  let initializedOutput = false;
+  for (; ; ) {
+    const params = new URLSearchParams({ limit: "5000" });
+    if (cursor !== null) params.set("cursor", cursor);
+    const payload = await http.get(
+      `/api/v2/billing/ledger?${params.toString()}`
+    );
+    const entries = Array.isArray(payload.entries) ? payload.entries : [];
+    const rows = entries.map(ledgerApiEntryToRow);
+    if (!initializedOutput) {
+      await (0, import_promises2.mkdir)((0, import_node_path4.dirname)(outputPath), { recursive: true });
+      await (0, import_promises2.writeFile)(outputPath, ledgerRowsToCsv([], true), "utf-8");
+      initializedOutput = true;
+    }
+    if (rows.length > 0) {
+      await (0, import_promises2.appendFile)(outputPath, ledgerRowsToCsv(rows, false), "utf-8");
+      summary = summarizeLedgerRows(summary, rows);
+    }
+    const nextCursor = typeof payload.next_cursor === "string" && payload.next_cursor.length > 0 ? payload.next_cursor : null;
+    if (rows.length === 0 || payload.has_more !== true || nextCursor === null) {
+      break;
+    }
+    if (nextCursor === cursor) break;
+    cursor = nextCursor;
+  }
+  if (shouldEmitJson(options.json)) {
+    return printJson({
+      output_path: outputPath,
+      row_count: summary.row_count,
+      net_delta_credits: summary.net_delta_credits,
+      scope: "current_auth_context"
+    });
+  }
+  process.stdout.write(`Billing ledger written to ${outputPath}
+`);
+  process.stdout.write(`${summary.row_count} row(s) exported for the current auth context.
+`);
+  process.stdout.write(`Net ledger delta: ${summary.net_delta_credits} Deepline Credits
+`);
+}
 async function handleCheckout(options) {
   const { http } = getAuthedHttpClient();
   const payload = await http.post("/api/v2/billing/checkout", {
@@ -2513,20 +2640,156 @@ async function handleRedeemCode(code, options) {
 `);
 }
 function registerBillingCommands(program) {
-  const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.");
-  billing.command("balance").description("Show current billing balance.").option("--json", "Emit JSON output").action(handleBalance);
-  billing.command("usage").description("Show current usage plus recent calls.").option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option("--json", "Emit JSON output").action(handleUsage);
-  billing.command("limit").description("Show configured monthly limit state.").option("--json", "Emit JSON output").action(handleLimit);
-  billing.command("set-limit").description("Set monthly credit cap.").argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output").action(handleSetLimit);
-  billing.command("off").description("Disable monthly credit cap.").option("--json", "Emit JSON output").action(handleLimitOff);
-  billing.command("history").description("Export billing ledger history to CSV.").requiredOption("--time <window>", "Rolling time window: 1d, 1w, 1m, or 1y").option("--json", "Emit JSON output").action(handleHistory);
-  billing.command("checkout").description("Create a checkout session and optionally open it in your browser.").option("--tier <tierId>", "Named pricing tier").option("--credits <credits>", "Custom credit amount").option("--discount-code <code>", "Apply a discount code").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output").action(handleCheckout);
-  billing.command("redeem-code").description("Redeem a billing code.").requiredOption("--code <code>", "Code to redeem").option("--no-open", "Do not open a browser").option("--json", "Emit JSON output").action(({ code, ...options }) => handleRedeemCode(code, options));
+  const billing = program.command("billing").description("Inspect balance, usage, limits, and checkout flows.").addHelpText(
+    "after",
+    `
+Concepts:
+  Billing commands show Deepline credits, not raw provider spend.
+  set-limit/off mutate the monthly workspace cap. checkout/redeem-code can open
+  a browser unless --no-open is set.
+
+Examples:
+  deepline billing balance --json
+  deepline billing usage --limit 20 --json
+  deepline billing set-limit 500 --json
+  deepline billing checkout --credits 1000 --no-open --json
+`
+  );
+  billing.command("balance").description("Show current billing balance.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows the current Deepline credit balance for the active workspace.
+
+Examples:
+  deepline billing balance
+  deepline billing balance --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleBalance);
+  billing.command("usage").description("Show current usage plus recent calls.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows last-30-day Deepline credit usage plus a bounded recent-call
+  page. Use --limit/--offset to paginate the recent-call section.
+
+Examples:
+  deepline billing usage
+  deepline billing usage --limit 50 --offset 50 --json
+`
+  ).option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
+  billing.command("limit").description("Show configured monthly limit state.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Shows whether the monthly workspace cap is enabled and how many
+  Deepline credits remain before the cap.
+
+Examples:
+  deepline billing limit
+  deepline billing limit --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimit);
+  billing.command("set-limit").description("Set monthly credit cap.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace billing settings. The argument is a Deepline credit amount,
+  not dollars and not provider credits.
+
+Examples:
+  deepline billing set-limit 500
+  deepline billing set-limit 500 --json
+`
+  ).argument("<credits>", "Monthly credits limit").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleSetLimit);
+  billing.command("off").description("Disable monthly credit cap.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace billing settings by removing the monthly Deepline credit cap.
+
+Examples:
+  deepline billing off
+  deepline billing off --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLimitOff);
+  billing.command("ledger").description("Inspect and export billing ledger rows.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Exports ledger rows for the current auth context. API-key auth is
+  scoped by the server to that API key; session auth is scoped to the active
+  workspace.
+
+Examples:
+  deepline billing ledger export all
+  deepline billing ledger export all --output ./ledger.csv
+  deepline billing ledger export all --json
+`
+  ).addCommand(
+    new import_commander.Command("export").description("Export billing ledger rows.").addHelpText(
+      "after",
+      `
+Examples:
+  deepline billing ledger export all
+`
+    ).addCommand(
+      new import_commander.Command("all").description("Export all available billing ledger rows to CSV.").addHelpText(
+        "after",
+        `
+Notes:
+  Pages through the ledger for the current auth context, writes CSV locally,
+  then reports the row count and the net delta computed from delta_credits.
+
+Examples:
+  deepline billing ledger export all
+  deepline billing ledger export all --json
+`
+      ).option("--output <path>", "Write CSV to an explicit path").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleLedgerExportAll)
+    )
+  );
+  billing.command("history").description("Export billing ledger history to CSV.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only server query that writes a local CSV file. With --json, stdout is a
+  summary containing the output path and row count.
+
+Examples:
+  deepline billing history --time 1m
+  deepline billing history --time 1y --json
+`
+  ).requiredOption("--time <window>", "Rolling time window: 1d, 1w, 1m, or 1y").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleHistory);
+  billing.command("checkout").description("Create a checkout session and optionally open it in your browser.").addHelpText(
+    "after",
+    `
+Notes:
+  Creates a payment checkout session. Opens the checkout URL in a browser unless
+  --no-open is set. Use --json for automation.
+
+Examples:
+  deepline billing checkout --tier pro
+  deepline billing checkout --credits 1000 --no-open --json
+  deepline billing checkout --credits 1000 --discount-code LAUNCH --no-open
+`
+  ).option("--tier <tierId>", "Named pricing tier").option("--credits <credits>", "Custom credit amount").option("--discount-code <code>", "Apply a discount code").option("--no-open", "Print the checkout URL without opening a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleCheckout);
+  billing.command("redeem-code").description("Redeem a billing code.").addHelpText(
+    "after",
+    `
+Notes:
+  Redeems a workspace billing code and may open a browser for completion unless
+  --no-open is set.
+
+Examples:
+  deepline billing redeem-code --code ABC123
+  deepline billing redeem-code --code ABC123 --no-open --json
+`
+  ).requiredOption("--code <code>", "Code to redeem").option("--no-open", "Do not open a browser").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(({ code, ...options }) => handleRedeemCode(code, options));
 }
 
 // src/cli/dataset-stats.ts
 var import_node_fs4 = require("fs");
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 var CSV_PROJECTED_FIELDS_KEY = "__deeplineCsvProjectedFields";
 function csvProjectedFields(row) {
   const serialized = row[CSV_PROJECTED_FIELDS_KEY];
@@ -2856,7 +3119,7 @@ function writeCanonicalRowsCsv(rowsInfo, outPath) {
     rows: rowsInfo.rows,
     columns: rowsInfo.columns
   });
-  const resolved = (0, import_node_path4.resolve)(outPath);
+  const resolved = (0, import_node_path5.resolve)(outPath);
   (0, import_node_fs4.writeFileSync)(
     resolved,
     csvStringFromRows(sanitized.rows, sanitized.columns),
@@ -2952,8 +3215,31 @@ async function handleCsvShow(options) {
 `);
 }
 function registerCsvCommands(program) {
-  const csv = program.command("csv").description("Inspect local CSV files.");
-  csv.command("show").description("Display rows from a CSV file in json, csv, or table form.").requiredOption("--csv <path>", "Input CSV path").option("--format <format>", "Output format: json, csv, or table", "json").option("--rows <range>", "Row range start:end", "0:19").option("--columns <names>", "Comma-separated column names to include").option("--summary", "Print a summary payload instead of row output").option("--verbose", "Do not truncate long values in table output").action(handleCsvShow);
+  const csv = program.command("csv").description("Inspect local CSV files.").addHelpText(
+    "after",
+    `
+Notes:
+  Local-only inspection helpers. These commands do not upload CSV files or call
+  Deepline APIs.
+
+Examples:
+  deepline csv show --csv leads.csv --rows 0:10 --format table
+  deepline csv show --csv leads.csv --summary
+`
+  );
+  csv.command("show").description("Display rows from a CSV file in json, csv, or table form.").addHelpText(
+    "after",
+    `
+Notes:
+  Reads a local CSV path and prints a bounded row range. --rows uses inclusive
+  start:end indexes, so 0:19 prints the first 20 rows. JSON is the default format.
+
+Examples:
+  deepline csv show --csv leads.csv
+  deepline csv show --csv leads.csv --rows 20:39 --columns name,email --format table
+  deepline csv show --csv leads.csv --summary
+`
+  ).requiredOption("--csv <path>", "Input CSV path").option("--format <format>", "Output format: json, csv, or table", "json").option("--rows <range>", "Row range start:end", "0:19").option("--columns <names>", "Comma-separated column names to include").option("--summary", "Print a summary payload instead of row output").option("--verbose", "Do not truncate long values in table output").action(handleCsvShow);
 }
 
 // src/cli/commands/db.ts
@@ -3033,8 +3319,32 @@ async function handleDbQuery(args) {
   return 0;
 }
 function registerDbCommands(program) {
-  const db = program.command("db").alias("customer-db").description("Query the tenant customer database.");
-  db.command("query").alias("psql").description("Run SQL against the tenant customer database.").requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--json", "Emit raw JSON response").action(async (options) => {
+  const db = program.command("db").alias("customer-db").description("Query the tenant customer database.").addHelpText(
+    "after",
+    `
+Notes:
+  Runs SQL against the active workspace customer database through Deepline APIs.
+  Results are bounded by the server and --max-rows. Use --json for stable output.
+
+Examples:
+  deepline db query --sql "select * from companies limit 20"
+  deepline db query --sql "select domain, name from companies limit 20" --json
+  deepline db query --sql "select * from contacts" --max-rows 100 --json
+`
+  );
+  db.command("query").alias("psql").description("Run SQL against the tenant customer database.").addHelpText(
+    "after",
+    `
+Notes:
+  Requires --sql. Output is a compact table in a terminal and raw JSON with
+  --json or when stdout is piped. The active auth workspace determines scope.
+
+Examples:
+  deepline db query --sql "select * from companies limit 20"
+  deepline db query --sql "select domain, name from companies limit 20" --json
+  deepline db psql --sql "select count(*) from contacts" --json
+`
+  ).requiredOption("--sql <sql>", "SQL statement").option("--max-rows <n>", "Maximum returned rows").option("--json", "Emit raw JSON response. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleDbQuery([
       "--sql",
       options.sql,
@@ -3060,9 +3370,29 @@ async function handleFeedback(text, options) {
   process.stdout.write("Feedback submitted. Thank you.\n");
 }
 function registerFeedbackCommands(program) {
-  const feedback = program.command("feedback").description("Submit CLI feedback to Deepline.");
+  const feedback = program.command("feedback").description("Submit CLI feedback to Deepline.").addHelpText(
+    "after",
+    `
+Notes:
+  Sends the feedback text plus local CLI environment info to Deepline support.
+  Use --command and --payload to attach a reproducible command shape.
+
+Examples:
+  deepline feedback "plays run failed after upload" --command "deepline plays run my.play.ts --watch"
+  deepline feedback "unexpected billing output" --payload '{"command":"billing usage"}' --json
+`
+  );
   feedback.argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
-  program.command("provide-feedback").description("Legacy alias for `deepline feedback`.").argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
+  program.command("provide-feedback").description("Legacy alias for `deepline feedback`.").addHelpText(
+    "after",
+    `
+Notes:
+  Compatibility alias. Prefer deepline feedback in new scripts and docs.
+
+Examples:
+  deepline feedback "tools search returned stale results" --json
+`
+  ).argument("<text>", "Feedback text").option("--command <command>", "Command that reproduced the issue").option("--payload <payload>", "JSON or plain-text payload for the repro").option("--json", "Emit JSON output").action(handleFeedback);
 }
 
 // src/cli/commands/org.ts
@@ -3142,27 +3472,61 @@ async function handleOrgSwitch(selection, options) {
 `);
 }
 function registerOrgCommands(program) {
-  const org = program.command("org").description("List and switch organizations.");
-  org.command("list").description("List your organizations.").option("--json", "Emit JSON output").action(handleOrgList);
-  org.command("switch [selection]").description("Switch to another organization and save the new API key in the host auth file.").option("--org-id <id>", "Switch using an explicit organization id").option("--json", "Emit JSON output").action(handleOrgSwitch);
+  const org = program.command("org").description("List and switch organizations.").addHelpText(
+    "after",
+    `
+Notes:
+  Organizations are workspaces. Switching organizations mutates the saved host
+  auth file so later CLI commands target the selected workspace.
+
+Examples:
+  deepline org list --json
+  deepline org switch 2
+  deepline org switch --org-id org_123 --json
+`
+  );
+  org.command("list").description("List your organizations.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Marks the active organization when the server returns that metadata.
+
+Examples:
+  deepline org list
+  deepline org list --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleOrgList);
+  org.command("switch [selection]").description("Switch to another organization and save the new API key in the host auth file.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates the saved host auth file. Selection can be a list number, exact
+  organization name, or organization id. Without a selection, prints choices.
+
+Examples:
+  deepline org switch
+  deepline org switch 2
+  deepline org switch --org-id org_123 --json
+`
+  ).option("--org-id <id>", "Switch using an explicit organization id").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleOrgSwitch);
 }
 
 // src/cli/commands/play.ts
 var import_node_crypto3 = require("crypto");
 var import_node_fs6 = require("fs");
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 
 // src/plays/bundle-play-file.ts
 var import_node_os5 = require("os");
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 var import_node_url = require("url");
 var import_node_fs5 = require("fs");
 
 // ../shared_libs/plays/bundling/index.ts
 var import_node_crypto = require("crypto");
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_node_os4 = require("os");
-var import_node_path5 = require("path");
+var import_node_path6 = require("path");
 var import_node_module = require("module");
 var import_esbuild = require("esbuild");
 
@@ -3223,7 +3587,7 @@ var playArtifactRequire = (0, import_node_module.createRequire)(import_meta.url)
 var PLAY_BUNDLE_CACHE_VERSION = 24;
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 var MAX_ESM_WORKERS_BUNDLE_BYTES = 115e4;
-var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path5.join)(
+var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path6.join)(
   (0, import_node_os4.tmpdir)(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
 );
@@ -3254,15 +3618,15 @@ function isLocalSpecifier(specifier) {
 }
 async function normalizeLocalPath(filePath) {
   try {
-    return await (0, import_promises2.realpath)(filePath);
+    return await (0, import_promises3.realpath)(filePath);
   } catch {
-    return (0, import_node_path5.resolve)(filePath);
+    return (0, import_node_path6.resolve)(filePath);
   }
 }
 function createPlayWorkspace(entryFile) {
   return {
     entryFile,
-    rootDir: (0, import_node_path5.dirname)(entryFile)
+    rootDir: (0, import_node_path6.dirname)(entryFile)
   };
 }
 function isPathInsideDirectory(filePath, directory) {
@@ -3416,7 +3780,7 @@ function extractDefinedPlayName(sourceCode, _filePath) {
 function getPackageRequireCandidates(fromFile) {
   const candidates = [
     (0, import_node_module.createRequire)(fromFile),
-    (0, import_node_module.createRequire)((0, import_node_path5.join)(process.cwd(), "package.json")),
+    (0, import_node_module.createRequire)((0, import_node_path6.join)(process.cwd(), "package.json")),
     playArtifactRequire
   ];
   return candidates;
@@ -3463,7 +3827,7 @@ function workersNamedPlayEntryAliasPlugin(playFilePath, exportName) {
           contents: `export { ${exportName} as default } from ${JSON.stringify(playFilePath)};
 `,
           loader: "ts",
-          resolveDir: (0, import_node_path5.dirname)(playFilePath)
+          resolveDir: (0, import_node_path6.dirname)(playFilePath)
         })
       );
     }
@@ -3627,7 +3991,7 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
         return {
           contents: buildImportedPlayProxyModule(dependency.playName),
           loader: "ts",
-          resolveDir: (0, import_node_path5.dirname)(args.path)
+          resolveDir: (0, import_node_path6.dirname)(args.path)
         };
       });
     }
@@ -3635,7 +3999,7 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
 }
 async function fileExists(filePath) {
   try {
-    await (0, import_promises2.stat)(filePath);
+    await (0, import_promises3.stat)(filePath);
     return true;
   } catch {
     return false;
@@ -3645,12 +4009,12 @@ async function resolveLocalImport(fromFile, specifier) {
   if (specifier.startsWith("file:")) {
     return normalizeLocalPath(new URL(specifier).pathname);
   }
-  const base = (0, import_node_path5.isAbsolute)(specifier) ? (0, import_node_path5.resolve)(specifier) : (0, import_node_path5.resolve)((0, import_node_path5.dirname)(fromFile), specifier);
+  const base = (0, import_node_path6.isAbsolute)(specifier) ? (0, import_node_path6.resolve)(specifier) : (0, import_node_path6.resolve)((0, import_node_path6.dirname)(fromFile), specifier);
   const candidates = [base];
-  const explicitExtension = (0, import_node_path5.extname)(base).toLowerCase();
+  const explicitExtension = (0, import_node_path6.extname)(base).toLowerCase();
   if (!explicitExtension) {
     candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`));
-    candidates.push(...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path5.join)(base, `index${extension}`)));
+    candidates.push(...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path6.join)(base, `index${extension}`)));
   } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(explicitExtension)) {
     const stem = base.slice(0, -explicitExtension.length);
     candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stem}${extension}`));
@@ -3716,9 +4080,9 @@ async function analyzeSourceGraph(entryFile, adapter) {
       return;
     }
     visited.add(absolutePath);
-    const sourceCode2 = await (0, import_promises2.readFile)(absolutePath, "utf-8");
+    const sourceCode2 = await (0, import_promises3.readFile)(absolutePath, "utf-8");
     localFiles.set(absolutePath, sourceCode2);
-    if ((0, import_node_path5.extname)(absolutePath).toLowerCase() === ".json") {
+    if ((0, import_node_path6.extname)(absolutePath).toLowerCase() === ".json") {
       return;
     }
     const handleSpecifier = async (specifier, line, column, kind) => {
@@ -3742,7 +4106,7 @@ async function analyzeSourceGraph(entryFile, adapter) {
           column
         });
         if (resolved !== absoluteEntryFile && isPlaySourceFile(resolved)) {
-          const importedSource = await (0, import_promises2.readFile)(resolved, "utf-8");
+          const importedSource = await (0, import_promises3.readFile)(resolved, "utf-8");
           const importedPlayName = extractDefinedPlayName(importedSource, resolved);
           if (!importedPlayName) {
             throw new Error(
@@ -3822,20 +4186,20 @@ async function computeWorkersHarnessFingerprintWithAdapter(adapter) {
   const tsFiles = entries.filter((e) => e.isFile() && /\.[cm]?ts$/.test(e.name)).map((e) => e.name).sort();
   const parts = [];
   for (const name of tsFiles) {
-    const contents = await (0, import_promises2.readFile)((0, import_node_path5.join)(adapter.workersHarnessFilesDir, name), "utf-8");
+    const contents = await (0, import_promises3.readFile)((0, import_node_path6.join)(adapter.workersHarnessFilesDir, name), "utf-8");
     parts.push({ name, hash: sha256(contents) });
   }
   return sha256(JSON.stringify(parts));
 }
 function artifactCachePath(graphHash, artifactKind, adapter) {
-  return (0, import_node_path5.join)(
+  return (0, import_node_path6.join)(
     adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR,
     `${graphHash}.${artifactKind}.json`
   );
 }
 async function readArtifactCache(graphHash, artifactKind, adapter) {
   try {
-    const serialized = await (0, import_promises2.readFile)(
+    const serialized = await (0, import_promises3.readFile)(
       artifactCachePath(graphHash, artifactKind, adapter),
       "utf-8"
     );
@@ -3846,8 +4210,8 @@ async function readArtifactCache(graphHash, artifactKind, adapter) {
 }
 async function writeArtifactCache(artifact, adapter) {
   const cacheDir = adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR;
-  await (0, import_promises2.mkdir)(cacheDir, { recursive: true });
-  await (0, import_promises2.writeFile)(
+  await (0, import_promises3.mkdir)(cacheDir, { recursive: true });
+  await (0, import_promises3.writeFile)(
     artifactCachePath(
       artifact.graphHash,
       artifact.artifactKind ?? PLAY_ARTIFACT_KINDS.cjsNode20,
@@ -3863,7 +4227,7 @@ function normalizeSourceMapForRuntime(sourceMapText) {
     if (sourcePath.startsWith("data:") || sourcePath.startsWith("node:") || sourcePath.startsWith("/") || /^[a-zA-Z]+:\/\//.test(sourcePath)) {
       return sourcePath;
     }
-    return (0, import_node_path5.resolve)(process.cwd(), sourcePath);
+    return (0, import_node_path6.resolve)(process.cwd(), sourcePath);
   });
   parsed.sourceRoot = void 0;
   return JSON.stringify(parsed);
@@ -3895,8 +4259,8 @@ async function runEsbuildForCjsNode(entryFile, importedPlayDependencies, adapter
     ...namedExportShim ? {
       stdin: {
         contents: namedExportShim,
-        resolveDir: (0, import_node_path5.dirname)(entryFile),
-        sourcefile: `${(0, import_node_path5.basename)(entryFile)}.${exportName}.entry.ts`,
+        resolveDir: (0, import_node_path6.dirname)(entryFile),
+        sourcefile: `${(0, import_node_path6.basename)(entryFile)}.${exportName}.entry.ts`,
         loader: "ts"
       }
     } : { entryPoints: [entryFile] },
@@ -4072,10 +4436,10 @@ workers-harness:${harnessFingerprint}`
     }
     const { bundledCode, sourceMapText, outputExtension } = buildOutcome;
     const normalizedSourceMap = normalizeSourceMapForRuntime(sourceMapText);
-    const virtualBaseName = exportName === "default" ? (0, import_node_path5.basename)(absolutePath).replace(/\.[^.]+$/, "") : `${(0, import_node_path5.basename)(absolutePath).replace(/\.[^.]+$/, "")}.${exportName}`;
+    const virtualBaseName = exportName === "default" ? (0, import_node_path6.basename)(absolutePath).replace(/\.[^.]+$/, "") : `${(0, import_node_path6.basename)(absolutePath).replace(/\.[^.]+$/, "")}.${exportName}`;
     const virtualFilename = `/virtual/deepline-plays/${analysis.graphHash}/${virtualBaseName}.${outputExtension}`;
     const executableCode = `${bundledCode}
-//# sourceMappingURL=${(0, import_node_path5.basename)(virtualFilename)}.map
+//# sourceMappingURL=${(0, import_node_path6.basename)(virtualFilename)}.map
 `;
     const bundleSizeError = getBundleSizeError(
       absolutePath,
@@ -4184,14 +4548,14 @@ function resolveExecutionProfile(override) {
 
 // src/plays/local-file-discovery.ts
 var import_node_crypto2 = require("crypto");
-var import_promises3 = require("fs/promises");
-var import_node_path6 = require("path");
+var import_promises4 = require("fs/promises");
+var import_node_path7 = require("path");
 var SOURCE_EXTENSIONS2 = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
 function sha2562(buffer) {
   return (0, import_node_crypto2.createHash)("sha256").update(buffer).digest("hex");
 }
 function contentTypeForFile(filePath) {
-  const extension = (0, import_node_path6.extname)(filePath).toLowerCase();
+  const extension = (0, import_node_path7.extname)(filePath).toLowerCase();
   if (extension === ".csv") return "text/csv";
   if (extension === ".json") return "application/json";
   if (extension === ".txt") return "text/plain";
@@ -4375,23 +4739,23 @@ function localImportSpecifiers(sourceCode) {
 }
 async function fileExists2(filePath) {
   try {
-    await (0, import_promises3.stat)(filePath);
+    await (0, import_promises4.stat)(filePath);
     return true;
   } catch {
     return false;
   }
 }
 function isPathInsideDirectory2(filePath, directory) {
-  const relativePath = (0, import_node_path6.relative)(directory, filePath);
-  return relativePath === "" || !relativePath.startsWith("..") && !(0, import_node_path6.isAbsolute)(relativePath);
+  const relativePath = (0, import_node_path7.relative)(directory, filePath);
+  return relativePath === "" || !relativePath.startsWith("..") && !(0, import_node_path7.isAbsolute)(relativePath);
 }
 async function resolveLocalImport2(fromFile, specifier) {
-  const base = (0, import_node_path6.isAbsolute)(specifier) ? (0, import_node_path6.resolve)(specifier) : (0, import_node_path6.resolve)((0, import_node_path6.dirname)(fromFile), specifier);
+  const base = (0, import_node_path7.isAbsolute)(specifier) ? (0, import_node_path7.resolve)(specifier) : (0, import_node_path7.resolve)((0, import_node_path7.dirname)(fromFile), specifier);
   const candidates = [base];
-  const explicitExtension = (0, import_node_path6.extname)(base).toLowerCase();
+  const explicitExtension = (0, import_node_path7.extname)(base).toLowerCase();
   if (!explicitExtension) {
     candidates.push(...SOURCE_EXTENSIONS2.map((extension) => `${base}${extension}`));
-    candidates.push(...SOURCE_EXTENSIONS2.map((extension) => (0, import_node_path6.join)(base, `index${extension}`)));
+    candidates.push(...SOURCE_EXTENSIONS2.map((extension) => (0, import_node_path7.join)(base, `index${extension}`)));
   } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(explicitExtension)) {
     const stem = base.slice(0, -explicitExtension.length);
     candidates.push(...SOURCE_EXTENSIONS2.map((extension) => `${stem}${extension}`));
@@ -4404,18 +4768,18 @@ async function resolveLocalImport2(fromFile, specifier) {
   throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
 }
 async function discoverPackagedLocalFiles(entryFile) {
-  const absoluteEntryFile = (0, import_node_path6.resolve)(entryFile);
-  const packagingRoot = (0, import_node_path6.dirname)(absoluteEntryFile);
+  const absoluteEntryFile = (0, import_node_path7.resolve)(entryFile);
+  const packagingRoot = (0, import_node_path7.dirname)(absoluteEntryFile);
   const files = /* @__PURE__ */ new Map();
   const unresolved = [];
   const visitedFiles = /* @__PURE__ */ new Set();
   const visitSourceFile = async (filePath) => {
-    const absolutePath = (0, import_node_path6.resolve)(filePath);
+    const absolutePath = (0, import_node_path7.resolve)(filePath);
     if (visitedFiles.has(absolutePath)) {
       return;
     }
     visitedFiles.add(absolutePath);
-    const sourceCode = await (0, import_promises3.readFile)(absolutePath, "utf-8");
+    const sourceCode = await (0, import_promises4.readFile)(absolutePath, "utf-8");
     const scanSource = stripCommentsToSpaces2(sourceCode);
     const constants = collectTopLevelStringConstants(sourceCode);
     const childVisits = [];
@@ -4442,16 +4806,16 @@ async function discoverPackagedLocalFiles(entryFile) {
             message: "Could not resolve this ctx.csv(...) path at submit time. Use a string literal, a top-level const string, or pass a runtime input like input.file."
           });
         } else {
-          const absoluteCsvPath = (0, import_node_path6.resolve)((0, import_node_path6.dirname)(absolutePath), resolvedPath);
-          if ((0, import_node_path6.isAbsolute)(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
+          const absoluteCsvPath = (0, import_node_path7.resolve)((0, import_node_path7.dirname)(absolutePath), resolvedPath);
+          if ((0, import_node_path7.isAbsolute)(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
             unresolved.push({
               sourceFragment: sourceCode.slice(argument.start, argument.end).trim(),
               message: "ctx.csv(...) packaged file paths must be relative paths inside the play directory. Pass external files at runtime with input.file instead."
             });
             continue;
           }
-          const buffer = await (0, import_promises3.readFile)(absoluteCsvPath);
-          const stats = await (0, import_promises3.stat)(absoluteCsvPath);
+          const buffer = await (0, import_promises4.readFile)(absoluteCsvPath);
+          const stats = await (0, import_promises4.stat)(absoluteCsvPath);
           files.set(absoluteCsvPath, {
             sourceFragment: sourceCode.slice(argument.start, argument.end).trim(),
             logicalPath: resolvedPath,
@@ -4482,24 +4846,24 @@ async function discoverPackagedLocalFiles(entryFile) {
 // src/plays/bundle-play-file.ts
 var import_meta2 = {};
 var PLAY_BUNDLE_CACHE_VERSION2 = 26;
-var MODULE_DIR = (0, import_node_path7.dirname)((0, import_node_url.fileURLToPath)(import_meta2.url));
-var SDK_PACKAGE_ROOT = (0, import_node_path7.resolve)(MODULE_DIR, "..", "..");
-var SOURCE_REPO_ROOT = (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "..");
+var MODULE_DIR = (0, import_node_path8.dirname)((0, import_node_url.fileURLToPath)(import_meta2.url));
+var SDK_PACKAGE_ROOT = (0, import_node_path8.resolve)(MODULE_DIR, "..", "..");
+var SOURCE_REPO_ROOT = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "..");
 var HAS_SOURCE_BUNDLING_SOURCES = (0, import_node_fs5.existsSync)(
-  (0, import_node_path7.resolve)(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  (0, import_node_path8.resolve)(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PACKAGED_REPO_ROOT = (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "dist", "repo");
+var PACKAGED_REPO_ROOT = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "dist", "repo");
 var HAS_PACKAGED_BUNDLING_SOURCES = (0, import_node_fs5.existsSync)(
-  (0, import_node_path7.resolve)(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  (0, import_node_path8.resolve)(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "..");
-var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? (0, import_node_path7.resolve)(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? (0, import_node_path7.resolve)(PACKAGED_REPO_ROOT, "sdk", "src") : (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "src");
-var SDK_PACKAGE_JSON = (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "package.json");
-var SDK_ENTRY_FILE = (0, import_node_path7.resolve)(SDK_SOURCE_ROOT, "index.ts");
-var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : (0, import_node_path7.resolve)(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
-var SDK_WORKERS_ENTRY_FILE = (0, import_node_path7.resolve)(SDK_SOURCE_ROOT, "worker-play-entry.ts");
-var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path7.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
-var WORKERS_HARNESS_FILES_DIR = (0, import_node_path7.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src");
+var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "..");
+var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? (0, import_node_path8.resolve)(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? (0, import_node_path8.resolve)(PACKAGED_REPO_ROOT, "sdk", "src") : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "src");
+var SDK_PACKAGE_JSON = (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "package.json");
+var SDK_ENTRY_FILE = (0, import_node_path8.resolve)(SDK_SOURCE_ROOT, "index.ts");
+var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : (0, import_node_path8.resolve)(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
+var SDK_WORKERS_ENTRY_FILE = (0, import_node_path8.resolve)(SDK_SOURCE_ROOT, "worker-play-entry.ts");
+var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path8.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
+var WORKERS_HARNESS_FILES_DIR = (0, import_node_path8.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src");
 var hasWarnedAboutNonDevelopmentBundling = false;
 function warnAboutNonDevelopmentBundling(filePath) {
   if (hasWarnedAboutNonDevelopmentBundling) {
@@ -4523,8 +4887,8 @@ function defaultPlayBundleTarget() {
 function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
-    nodeModulesDir: (0, import_node_path7.resolve)(PROJECT_ROOT, "node_modules"),
-    cacheDir: (0, import_node_path7.join)((0, import_node_os5.tmpdir)(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
+    nodeModulesDir: (0, import_node_path8.resolve)(PROJECT_ROOT, "node_modules"),
+    cacheDir: (0, import_node_path8.join)((0, import_node_os5.tmpdir)(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,
@@ -4804,7 +5168,7 @@ function formatPlayListReference(play) {
 function defaultMaterializedPlayPath(reference) {
   const playName = parseReferencedPlayTarget(reference).unqualifiedPlayName;
   const safeName = playName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return (0, import_node_path8.resolve)(`${safeName || "play"}.play.ts`);
+  return (0, import_node_path9.resolve)(`${safeName || "play"}.play.ts`);
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -4867,7 +5231,7 @@ function extractPlayName(code, filePath) {
   throw buildMissingDefinePlayError(filePath);
 }
 function isFileTarget(target) {
-  return (0, import_node_fs6.existsSync)((0, import_node_path8.resolve)(target));
+  return (0, import_node_fs6.existsSync)((0, import_node_path9.resolve)(target));
 }
 function looksLikeFilePath(target) {
   if (target.trim().toLowerCase().startsWith("prebuilt/")) {
@@ -4886,7 +5250,7 @@ function parsePositiveInteger2(value, flagName) {
   return parsed;
 }
 function parseJsonInput(raw) {
-  const source = raw.startsWith("@") ? (0, import_node_fs6.readFileSync)((0, import_node_path8.resolve)(raw.slice(1)), "utf-8") : raw;
+  const source = raw.startsWith("@") ? (0, import_node_fs6.readFileSync)((0, import_node_path9.resolve)(raw.slice(1)), "utf-8") : raw;
   const parsed = JSON.parse(source);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("--input must be a JSON object.");
@@ -4996,7 +5360,7 @@ function applyCsvShortcutInput(input) {
 function isLocalFilePathValue(value) {
   if (typeof value !== "string" || !value.trim()) return false;
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value.trim())) return false;
-  return (0, import_node_fs6.existsSync)((0, import_node_path8.resolve)(value));
+  return (0, import_node_fs6.existsSync)((0, import_node_path9.resolve)(value));
 }
 function inputContainsLocalFilePath(value) {
   if (isLocalFilePathValue(value)) {
@@ -5022,8 +5386,8 @@ async function stageFileInputArgs(input) {
   const localFiles = uniqueBindings.flatMap((binding) => {
     const value = getDottedInputValue(input.runtimeInput, binding.inputPath);
     if (!isLocalFilePathValue(value)) return [];
-    const absolutePath = (0, import_node_path8.resolve)(value);
-    return [{ binding, absolutePath, logicalPath: (0, import_node_path8.basename)(absolutePath) }];
+    const absolutePath = (0, import_node_path9.resolve)(value);
+    return [{ binding, absolutePath, logicalPath: (0, import_node_path9.basename)(absolutePath) }];
   });
   if (localFiles.length === 0) {
     return { inputFile: null, packagedFiles: [] };
@@ -5058,9 +5422,9 @@ function stageFile(logicalPath, absolutePath) {
 }
 function normalizePlayPath(filePath) {
   try {
-    return import_node_fs6.realpathSync.native((0, import_node_path8.resolve)(filePath));
+    return import_node_fs6.realpathSync.native((0, import_node_path9.resolve)(filePath));
   } catch {
-    return (0, import_node_path8.resolve)(filePath);
+    return (0, import_node_path9.resolve)(filePath);
   }
 }
 function formatBundlingErrors(filePath, errors) {
@@ -6086,7 +6450,7 @@ function parsePlayRunOptions(args) {
   let input = null;
   let revisionId = null;
   let revisionSelector = null;
-  const watch = args.includes("--watch");
+  const watch = args.includes("--watch") || args.includes("--wait");
   let jsonOutput = watch ? args.includes("--json") : argsWantJson(args);
   const emitLogs = !jsonOutput || args.includes("--logs");
   const force = args.includes("--force");
@@ -6120,7 +6484,7 @@ function parsePlayRunOptions(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = (0, import_node_path8.resolve)(args[++index]);
+      outPath = (0, import_node_path9.resolve)(args[++index]);
       continue;
     }
     if (arg === "--poll-interval-ms" || arg === "--interval-ms") {
@@ -6136,15 +6500,13 @@ function parsePlayRunOptions(args) {
       if (arg === "--watch") {
         continue;
       }
+      if (arg === "--wait") {
+        continue;
+      }
       if (arg === "--json") {
         jsonOutput = true;
         continue;
       }
-      if (arg === "--wait") {
-        throw new Error(
-          "--wait is removed for `plays run`; use `--watch` to stream completion output."
-        );
-      }
       if (arg === "--tail") {
         throw new Error(
           "--tail is removed for `plays run`; use `--watch` to stream completion output."
@@ -6222,11 +6584,11 @@ function shouldUseLocalOnlyPlayCheck() {
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
-    const resolved = (0, import_node_path8.resolve)(options.target);
+    const resolved = (0, import_node_path9.resolve)(options.target);
     console.error(`File not found: ${resolved}`);
     return 1;
   }
-  const absolutePlayPath = (0, import_node_path8.resolve)(options.target);
+  const absolutePlayPath = (0, import_node_path9.resolve)(options.target);
   const sourceCode = (0, import_node_fs6.readFileSync)(absolutePlayPath, "utf-8");
   let graph;
   try {
@@ -6290,7 +6652,7 @@ async function handleFileBackedRun(options) {
   }
   const client = new DeeplineClient();
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  const absolutePlayPath = (0, import_node_path8.resolve)(options.target.path);
+  const absolutePlayPath = (0, import_node_path9.resolve)(options.target.path);
   progress.phase("compiling play");
   const sourceCode = traceCliSync(
     "cli.play_file_read_source",
@@ -6579,11 +6941,11 @@ async function handlePlayRun(args) {
     if (isFileTarget(options.target.path)) {
       return handleFileBackedRun(options);
     }
-    const resolved = (0, import_node_path8.resolve)(options.target.path);
+    const resolved = (0, import_node_path9.resolve)(options.target.path);
     console.error(`File not found: ${resolved}`);
-    const dir = (0, import_node_path8.dirname)(resolved);
+    const dir = (0, import_node_path9.dirname)(resolved);
     if ((0, import_node_fs6.existsSync)(dir)) {
-      const base = (0, import_node_path8.basename)(resolved);
+      const base = (0, import_node_path9.basename)(resolved);
       try {
         const siblings = (0, import_node_fs6.readdirSync)(dir).filter(
           (f) => f.includes(base.replace(/\.(play\.)?ts$/, "")) || f.endsWith(".play.ts")
@@ -6591,7 +6953,7 @@ async function handlePlayRun(args) {
         if (siblings.length > 0) {
           console.error(`Did you mean one of these?`);
           for (const s of siblings.slice(0, 5)) {
-            console.error(`  ${(0, import_node_path8.join)(dir, s)}`);
+            console.error(`  ${(0, import_node_path9.join)(dir, s)}`);
           }
         }
       } catch {
@@ -6737,7 +7099,7 @@ async function handleRunLogs(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = (0, import_node_path8.resolve)(args[++index]);
+      outPath = (0, import_node_path9.resolve)(args[++index]);
     }
   }
   const client = new DeeplineClient();
@@ -6824,7 +7186,7 @@ async function handleRunExport(args) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
-      outPath = (0, import_node_path8.resolve)(args[++index]);
+      outPath = (0, import_node_path9.resolve)(args[++index]);
     }
   }
   if (!outPath) {
@@ -6864,10 +7226,10 @@ async function handlePlayGet(args) {
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
-      outPath = (0, import_node_path8.resolve)(args[++index]);
+      outPath = (0, import_node_path9.resolve)(args[++index]);
     }
   }
-  const playName = isFileTarget(target) ? extractPlayName((0, import_node_fs6.readFileSync)((0, import_node_path8.resolve)(target), "utf-8"), (0, import_node_path8.resolve)(target)) : parseReferencedPlayTarget(target).playName;
+  const playName = isFileTarget(target) ? extractPlayName((0, import_node_fs6.readFileSync)((0, import_node_path9.resolve)(target), "utf-8"), (0, import_node_path9.resolve)(target)) : parseReferencedPlayTarget(target).playName;
   const detail = isFileTarget(target) ? await client.getPlay(playName) : await assertCanonicalNamedPlayReference(client, target);
   const resolvedSource = detail.play.workingRevision?.sourceCode ?? detail.play.liveRevision?.sourceCode ?? detail.play.currentRevision?.sourceCode ?? detail.play.sourceCode ?? "";
   const materializedFile = outPath ? materializeRemotePlaySource({
@@ -7159,7 +7521,7 @@ async function handlePlayPublish(args) {
     }
     let graph;
     try {
-      graph = await collectBundledPlayGraph((0, import_node_path8.resolve)(playName));
+      graph = await collectBundledPlayGraph((0, import_node_path9.resolve)(playName));
       await compileBundledPlayGraphManifests(client, graph);
       await publishImportedPlayDependencies(client, graph);
     } catch (error) {
@@ -7259,12 +7621,15 @@ Concepts:
   Plays are durable cloud workflows.
   Stable ctx.tools.execute({ id, tool, input }) calls are replay-safe.
   ctx.map adds row keys and row progress.
+  Named play runs use the live revision unless --latest or --revision-id is set.
+  Running a local file does not make it live; use set-live/publish explicitly.
 
 Common commands:
   deepline plays search email --json
   deepline plays describe person-linkedin-to-email --json
   deepline plays check my.play.ts
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays set-live my.play.ts --json
   deepline plays get person-linkedin-to-email --json
 `
   );
@@ -7294,9 +7659,11 @@ Notes:
   Unknown --foo and --foo.bar flags are treated as play input args.
   File args accept local paths; the CLI stages files before submit.
   --watch prints logs, previews, stats, and next commands.
+  --wait is accepted as a compatibility alias for --watch.
   The play page opens in your browser as soon as the run starts; use --no-open
   to only print the URL.
   --force supersedes active runs; it does not bypass completed reuse.
+  This command starts cloud work and may spend Deepline credits through tool calls.
 
 Idempotent execution:
   Stable tool call ids are the reuse key:
@@ -7321,6 +7688,7 @@ Idempotent execution:
 
 Examples:
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
+  deepline plays run my.play.ts --input @input.json --wait --json
   deepline plays run person-linkedin-to-email --input '{"linkedin_url":"..."}' --watch
   deepline plays run enrich.play.ts --csv leads.csv --watch --out leads-enriched.csv
   deepline plays run cto-search.play.ts --limit 5 --watch
@@ -7332,7 +7700,7 @@ Examples:
   ).option(
     "--out <path>",
     "Write the completed row output to CSV; requires --watch"
-  ).option("--watch", "Stream logs until completion").option(
+  ).option("--watch", "Stream logs until completion").option("--wait", "Alias for --watch; stream logs until completion").option(
     "--logs",
     "When output is non-interactive, stream play logs to stderr while waiting"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Supersede any active runs for this play").option("--no-open", "Print the play page URL without opening a browser").option("--json", "Emit JSON output").action(async (target, options, command) => {
@@ -7355,7 +7723,7 @@ Examples:
       ...options.latest ? ["--latest"] : [],
       ...options.revisionId ? ["--revision-id", options.revisionId] : [],
       ...options.out ? ["--out", options.out] : [],
-      ...options.watch ? ["--watch"] : [],
+      ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
@@ -7386,12 +7754,36 @@ Examples:
       ...options.out ? ["--out", options.out] : []
     ]);
   });
-  play.command("list").description("List saved and prebuilt plays.").option("--json", "Emit JSON output").action(async (options) => {
+  play.command("list").description("List saved and prebuilt plays.").addHelpText(
+    "after",
+    `
+Notes:
+  Inventory command for saved org plays and prebuilt plays. Use search for
+  ranked discovery by task or schema.
+
+Examples:
+  deepline plays list
+  deepline plays list --json
+  deepline plays search email --origin prebuilt --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayList([
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("search <query>").description("Search saved and prebuilt plays.").option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  play.command("search <query>").description("Search saved and prebuilt plays.").addHelpText(
+    "after",
+    `
+Notes:
+  Ranked discovery for workflows. Use --origin prebuilt or --origin owned when
+  you need to narrow results. Use describe on a result before running it.
+
+Examples:
+  deepline plays search email
+  deepline plays search "linkedin to email" --origin prebuilt --compact --json
+  deepline plays describe person-linkedin-to-email --json
+`
+  ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlaySearch([
       query,
       ...options.origin ? ["--origin", options.origin] : [],
@@ -7417,13 +7809,43 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("versions").description("List revisions for a named play.").option("--name <name>", "Saved play name").option("--json", "Emit JSON output").action(async (options) => {
+  play.command("versions").description("List revisions for a named play.").addHelpText(
+    "after",
+    `
+Notes:
+  Shows saved revisions for an org-owned play, including which revision is live
+  when that metadata is available. Named runs use the live revision by default.
+
+Examples:
+  deepline plays versions --name my-play
+  deepline plays versions --name my-play --json
+  deepline plays run my-play --revision-id <revision-id> --watch
+`
+  ).option("--name <name>", "Saved play name").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayVersions([
       ...options.name ? ["--name", options.name] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("publish <target>").description("Bundle, validate, save, and publish a play.").option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output").action(async (target, options) => {
+  const addPublishHelp = (command) => command.addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state. For a local file, this bundles, validates, saves a new
+  revision, and promotes that revision live. For a saved play, --latest or
+  --revision-id promotes an existing saved revision live.
+  Running a local file with plays run does not publish it.
+
+Examples:
+  deepline plays set-live my.play.ts --json
+  deepline plays set-live my-play --latest --json
+  deepline plays set-live my-play --revision-id <revision-id> --json
+  deepline plays publish my.play.ts --json
+`
+  );
+  addPublishHelp(
+    play.command("publish <target>").description("Bundle, validate, save, and promote a play revision live.")
+  ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayPublish([
       target,
       ...options.latest ? ["--latest"] : [],
@@ -7431,7 +7853,28 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("delete <target>").description("Delete an org-owned play and its saved revisions/runs.").option("-y, --yes", "Confirm deletion").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+  addPublishHelp(
+    play.command("set-live <target>").description("Promote a local file or saved revision as the live play revision.")
+  ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
+    process.exitCode = await handlePlayPublish([
+      target,
+      ...options.latest ? ["--latest"] : [],
+      ...options.revisionId ? ["--revision-id", options.revisionId] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
+  play.command("delete <target>").description("Delete an org-owned play and its saved revisions/runs.").addHelpText(
+    "after",
+    `
+Notes:
+  Destructive mutation. Deletes an org-owned play plus saved revisions and run
+  records. Prebuilt/read-only plays are refused. Use --yes for noninteractive runs.
+
+Examples:
+  deepline plays delete my-play
+  deepline plays delete my-play --yes --json
+`
+  ).option("-y, --yes", "Confirm deletion").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayDelete([
       target,
       ...options.yes ? ["--yes"] : [],
@@ -7441,6 +7884,12 @@ Examples:
   const runs = program.command("runs").description("Inspect, tail, stop, and export play runs.").addHelpText(
     "after",
     `
+Concepts:
+  A run is one execution instance of a play. It has status, progress, logs,
+  preview output, recovery metadata, and optional full row export.
+  tail reads the live stream. logs fetches persisted logs after the fact.
+  stop mutates cloud state by requesting cancellation.
+
 Examples:
   deepline runs get play/my-play/run/20260501t000000-000 --json
   deepline runs tail play/my-play/run/20260501t000000-000
@@ -7450,14 +7899,36 @@ Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
 `
   );
-  runs.command("get <runId>").description("Get status, progress, outputs, errors, and recovery metadata for a play run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--full", "Debug only: with --json, emit the raw status payload").action(async (runId, options) => {
+  runs.command("get <runId>").description("Get status, progress, outputs, errors, and recovery metadata for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Full run status read. Use --full --json when debugging raw stream/status fields.
+
+Examples:
+  deepline runs get play/my-play/run/20260501t000000-000
+  deepline runs get play/my-play/run/20260501t000000-000 --json
+  deepline runs get play/my-play/run/20260501t000000-000 --full --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--full", "Debug only: with --json, emit the raw status payload").action(async (runId, options) => {
     process.exitCode = await handleRunGet([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.full ? ["--full"] : []
     ]);
   });
-  runs.command("list").description("List play runs.").requiredOption("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  runs.command("list").description("List play runs.").addHelpText(
+    "after",
+    `
+Notes:
+  Bounded inventory for a play's recent runs. Use --compact for agent loops.
+  Common statuses include running, completed, failed, and stopped.
+
+Examples:
+  deepline runs list --play my-play
+  deepline runs list --play my-play --status failed --compact --json
+`
+  ).requiredOption("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleRunsList([
       "--play",
       options.play,
@@ -7466,14 +7937,37 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("tail <runId>").description("Read the canonical live stream for a play run.").option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--compact", "Drop verbose fields from JSON output").action(async (runId, options) => {
+  runs.command("tail <runId>").description("Read the canonical live stream for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Streams live run events until the stream ends. Use get for current status and
+  logs for persisted log history.
+
+Examples:
+  deepline runs tail play/my-play/run/20260501t000000-000
+  deepline runs tail play/my-play/run/20260501t000000-000 --compact --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--compact", "Drop verbose fields from JSON output").action(async (runId, options) => {
     process.exitCode = await handleRunTail([
       runId,
       ...options.json ? ["--json"] : [],
       ...options.compact ? ["--compact"] : []
     ]);
   });
-  runs.command("logs <runId>").description("Fetch persisted logs for a play run.").option("--limit <count>", "Maximum recent log lines to print without --out", "200").option("--out <path>", "Write the full persisted log stream to a file").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("logs <runId>").description("Fetch persisted logs for a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Prints a bounded recent log preview by default. Use --out to write the full
+  persisted log stream to a local file.
+
+Examples:
+  deepline runs logs play/my-play/run/20260501t000000-000
+  deepline runs logs play/my-play/run/20260501t000000-000 --limit 500
+  deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
+`
+  ).option("--limit <count>", "Maximum recent log lines to print without --out", "200").option("--out <path>", "Write the full persisted log stream to a file").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       runId,
       ...options.limit ? ["--limit", options.limit] : [],
@@ -7481,14 +7975,36 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("stop <runId>").description("Stop a play run.").option("--reason <text>", "Reason to include with the stop request").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("stop <runId>").description("Stop a play run.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state by requesting cancellation for an active run. Already
+  terminal runs are returned as no-ops by the server when applicable.
+
+Examples:
+  deepline runs stop play/my-play/run/20260501t000000-000 --reason "stale lock"
+  deepline runs stop play/my-play/run/20260501t000000-000 --json
+`
+  ).option("--reason <text>", "Reason to include with the stop request").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunStop([
       runId,
       ...options.reason ? ["--reason", options.reason] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
-  runs.command("export <runId>").description("Export the completed row output for a play run to CSV.").requiredOption("--out <path>", "Output CSV path").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
+  runs.command("export <runId>").description("Export the completed row output for a play run to CSV.").addHelpText(
+    "after",
+    `
+Notes:
+  Writes the completed row output to the requested local CSV path. Use runs get
+  first when you need to confirm the run is complete or inspect preview output.
+
+Examples:
+  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
+  deepline runs export play/my-play/run/20260501t000000-000 --out output.csv --json
+`
+  ).requiredOption("--out <path>", "Output CSV path").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunExport([
       runId,
       "--out",
@@ -7501,12 +8017,12 @@ Examples:
 // src/cli/commands/tools.ts
 var import_node_fs8 = require("fs");
 var import_node_os7 = require("os");
-var import_node_path10 = require("path");
+var import_node_path11 = require("path");
 
 // src/tool-output.ts
 var import_node_fs7 = require("fs");
 var import_node_os6 = require("os");
-var import_node_path9 = require("path");
+var import_node_path10 = require("path");
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -7581,19 +8097,19 @@ function tryConvertToList(payload, options) {
   return null;
 }
 function ensureOutputDir() {
-  const outputDir = (0, import_node_path9.join)((0, import_node_os6.homedir)(), ".local", "share", "deepline", "data");
+  const outputDir = (0, import_node_path10.join)((0, import_node_os6.homedir)(), ".local", "share", "deepline", "data");
   (0, import_node_fs7.mkdirSync)(outputDir, { recursive: true });
   return outputDir;
 }
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path9.join)(outputDir, `${stem}_${Date.now()}.json`);
+  const outputPath = (0, import_node_path10.join)(outputDir, `${stem}_${Date.now()}.json`);
   (0, import_node_fs7.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem) {
   const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path9.join)(outputDir, `${stem}_${Date.now()}.csv`);
+  const outputPath = (0, import_node_path10.join)(outputDir, `${stem}_${Date.now()}.csv`);
   const seen = /* @__PURE__ */ new Set();
   const columns = [];
   for (const row of rows) {
@@ -7732,16 +8248,44 @@ Concepts:
 
 Common commands:
   deepline tools search email --json
-  deepline tools get hunter_email_verifier --json
+  deepline tools describe hunter_email_verifier --json
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
+
+Output:
+  Search/list output is bounded. Use describe for a compact contract and get for
+  the full machine-readable metadata available for the tool.
 `
   );
-  tools.command("list").description("List available tools.").option("--json", "Emit JSON output").action(async (options) => {
+  tools.command("list").description("List available tools.").addHelpText(
+    "after",
+    `
+Notes:
+  Inventory command for known tool ids. Use search for ranked discovery by
+  intent, aliases, descriptions, and schema fields.
+
+Examples:
+  deepline tools list
+  deepline tools list --json
+  deepline tools search email --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await listTools([
       ...options.json ? ["--json"] : []
     ]);
   });
-  tools.command("search <query>").description("Search available tools.").option("--categories <categories>", "Comma-separated categories to filter ranked search").option("--search_terms <terms>", "Structured search terms for ranked search").option("--search-terms <terms>", "Structured search terms for ranked search").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  tools.command("search <query>").description("Search available tools.").addHelpText(
+    "after",
+    `
+Notes:
+  Ranked discovery for atomic provider/API operations. Results include tool ids
+  that can be passed to deepline tools describe or deepline tools call.
+
+Examples:
+  deepline tools search email
+  deepline tools search "company enrichment" --categories enrichment --json
+  deepline tools search verifier --search-mode v2 --json
+`
+  ).option("--categories <categories>", "Comma-separated categories to filter ranked search").option("--search_terms <terms>", "Structured search terms for ranked search").option("--search-terms <terms>", "Structured search terms for ranked search").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       categories: options.categories,
@@ -7750,15 +8294,18 @@ Common commands:
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });
   });
-  tools.command("get <toolId>").alias("describe").description("Show metadata for a tool.").addHelpText(
+  const addToolMetadataCommand = (command, preferredExample) => command.description("Show metadata for a tool.").addHelpText(
     "after",
     `
 Notes:
-  Shows the tool contract, input schema, output schema, costs, aliases, and metadata.
+  Shows the tool contract, input schema, output schema, Deepline cost, aliases,
+  and metadata. describe is the preferred discovery verb; get is kept as a
+  compatibility command for the same metadata surface.
 
 Examples:
-  deepline tools get hunter_email_verifier
-  deepline tools get hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools ${preferredExample} hunter_email_verifier
+  deepline tools ${preferredExample} hunter_email_verifier --json | jq '.inputSchema'
+  deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (toolId, options) => {
     process.exitCode = await getTool([
@@ -7766,12 +8313,16 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
+  addToolMetadataCommand(tools.command("describe <toolId>"), "describe");
+  addToolMetadataCommand(tools.command("get <toolId>"), "get");
   tools.command("call <toolId>").alias("execute").alias("run").description("Execute a tool by id.").addHelpText(
     "after",
     `
 Notes:
   Use tools for one atomic provider/API operation. Use plays for composed workflows,
   waterfalls, row maps, checkpoints, and retries.
+  Calling a provider-backed tool can spend Deepline credits. Use --json for the
+  stable result payload and --full-output when debugging response metadata.
 
 Examples:
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
@@ -8118,9 +8669,9 @@ function powerShellQuote(value) {
 function seedToolListScript(input) {
   const stem = safeFileStem(input.toolId);
   const fileName = `${stem}-workflow-seed-${Date.now()}.play.ts`;
-  const scriptDir = (0, import_node_fs8.mkdtempSync)((0, import_node_path10.join)((0, import_node_os7.tmpdir)(), "deepline-workflow-seed-"));
+  const scriptDir = (0, import_node_fs8.mkdtempSync)((0, import_node_path11.join)((0, import_node_os7.tmpdir)(), "deepline-workflow-seed-"));
   (0, import_node_fs8.chmodSync)(scriptDir, 448);
-  const scriptPath = (0, import_node_path10.join)(scriptDir, fileName);
+  const scriptPath = (0, import_node_path11.join)(scriptDir, fileName);
   const projectDir = `deepline/projects/${stem}-workflow`;
   const playName = `${stem}-workflow`;
   const sampleRows = input.rows.length > 0 ? `${JSON.stringify(input.rows.slice(0, 2)).replace(/\]$/, "")}, ...]` : "[]";
@@ -8263,7 +8814,7 @@ async function executeTool(args) {
 var import_node_child_process2 = require("child_process");
 var import_node_fs9 = require("fs");
 var import_node_os8 = require("os");
-var import_node_path11 = require("path");
+var import_node_path12 = require("path");
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-sdk";
 var SKILL_AGENTS = ["codex", "claude-code", "cursor"];
@@ -8274,7 +8825,7 @@ function shouldSkipSkillsSync() {
 }
 function sdkSkillsVersionPath(baseUrl) {
   const home = process.env.HOME?.trim() || (0, import_node_os8.homedir)();
-  return (0, import_node_path11.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
+  return (0, import_node_path12.join)(home, ".local", "deepline", baseUrlSlug(baseUrl), "sdk-skills", ".version");
 }
 function readLocalSkillsVersion(baseUrl) {
   const path = sdkSkillsVersionPath(baseUrl);
@@ -8287,7 +8838,7 @@ function readLocalSkillsVersion(baseUrl) {
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  (0, import_node_fs9.mkdirSync)((0, import_node_path11.dirname)(path), { recursive: true });
+  (0, import_node_fs9.mkdirSync)((0, import_node_path12.dirname)(path), { recursive: true });
   (0, import_node_fs9.writeFileSync)(path, `${version}
 `, "utf-8");
 }
@@ -8382,7 +8933,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const child = (0, import_node_child_process2.spawn)(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
@@ -8392,7 +8943,7 @@ function runOneSkillsInstall(install) {
       stderr += chunk.toString("utf-8");
     });
     child.on("error", (error) => {
-      resolve8({
+      resolve9({
         ok: false,
         detail: `failed to start ${install.command}: ${error.message}`,
         manualCommand: install.manualCommand
@@ -8400,11 +8951,11 @@ function runOneSkillsInstall(install) {
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve8({ ok: true, detail: "", manualCommand: install.manualCommand });
+        resolve9({ ok: true, detail: "", manualCommand: install.manualCommand });
         return;
       }
       const detail = stderr.trim();
-      resolve8({
+      resolve9({
         ok: false,
         detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
         manualCommand: install.manualCommand
@@ -8457,6 +9008,9 @@ function shouldPrintStartupPhase() {
     return false;
   }
   const args = process.argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    return false;
+  }
   const command = args[0];
   const subcommand = args[1];
   return (command === "play" || command === "plays") && subcommand === "run";
@@ -8478,7 +9032,7 @@ async function main() {
   if (printStartupPhase) {
     progress?.phase("loading deepline cli");
   }
-  const program = new import_commander.Command();
+  const program = new import_commander2.Command();
   program.name("deepline").description("Deepline CLI (TypeScript SDK)").version(SDK_VERSION, "-v, --version", "Show version").showHelpAfterError().showSuggestionAfterError(true).addHelpText(
     "after",
     `
@@ -8490,9 +9044,23 @@ Common commands:
   deepline plays run my.play.ts --input '{"domain":"stripe.com"}' --watch
   deepline tools call hunter_email_verifier --input '{"email":"a@b.com"}'
 
+Product model:
+  Tools are atomic provider/API operations that may spend credits.
+  Plays are durable workflows backed by source code or saved cloud revisions.
+  Runs are execution instances with logs, status, outputs, and cancellation.
+  Live plays are promoted revisions used by named play runs.
+
 Output:
   Structured commands print human-readable output in a terminal and JSON when stdout is piped.
   Use --json to force JSON in an interactive terminal.
+
+Safety:
+  Commands that mutate state, open a browser, write files, stop work, or spend credits say so in their help.
+  Use --no-open where available for CI and agent runs.
+
+Exit codes:
+  0 success; 2 usage/local input error; 3 auth/permission error; 4 not found;
+  5 server/runtime/provider failure; 7 validation/check failed.
 `
   );
   program.hook("preAction", async (_thisCommand, actionCommand) => {
@@ -8527,7 +9095,17 @@ Output:
   registerCsvCommands(program);
   registerDbCommands(program);
   registerFeedbackCommands(program);
-  program.command("health").description("Check server health.").action(async () => {
+  program.command("health").description("Check server health.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only connectivity check for the configured Deepline host. Prints the raw
+  server health payload as JSON.
+
+Examples:
+  deepline health
+`
+  ).action(async () => {
     try {
       const client = new DeeplineClient();
       const data = await client.health();
@@ -8539,7 +9117,18 @@ Output:
       );
     }
   });
-  program.command("version").description("Show version.").action(() => {
+  program.command("version").description("Show version.").addHelpText(
+    "after",
+    `
+Notes:
+  Prints the SDK CLI package version. The top-level -v/--version flag returns
+  the same version.
+
+Examples:
+  deepline version
+  deepline --version
+`
+  ).action(() => {
     process.stdout.write(`deepline ${SDK_VERSION}
 `);
   });