deepline 0.1.23 → 0.1.25

package/dist/cli/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command } from "commander";
+import { Command as Command2 } from "commander";
 
 // src/config.ts
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
@@ -243,7 +243,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
@@ -525,7 +525,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
@@ -533,7 +533,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") {
@@ -2023,7 +2023,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) {
@@ -2330,18 +2330,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] : []
     ]);
@@ -2367,6 +2397,10 @@ Examples:
 }
 
 // src/cli/commands/billing.ts
+import { Command } from "commander";
+import { appendFile, mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname4, resolve as resolve3 } from "path";
+import { stringify as stringify2 } from "csv-stringify/sync";
 function humanize(value) {
   return String(value || "").split("_").filter(Boolean).map((token) => token[0]?.toUpperCase() + token.slice(1)).join(" ") || "Unknown";
 }
@@ -2384,6 +2418,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 stringify2(rows, {
+    header,
+    columns: [
+      "created_at",
+      "delta_credits",
+      "reason",
+      "provider",
+      "operation",
+      "request_id",
+      "run_id",
+      "api_key_id",
+      "stripe_session_id"
+    ]
+  });
+}
+function defaultLedgerExportPath() {
+  return resolve3(
+    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");
@@ -2472,6 +2554,51 @@ async function handleHistory(options) {
   process.stdout.write(`${rows.length} row(s) exported.
 `);
 }
+async function handleLedgerExportAll(options) {
+  const { http } = getAuthedHttpClient();
+  const outputPath = options.output ? resolve3(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 mkdir2(dirname4(outputPath), { recursive: true });
+      await writeFile2(outputPath, ledgerRowsToCsv([], true), "utf-8");
+      initializedOutput = true;
+    }
+    if (rows.length > 0) {
+      await 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", {
@@ -2495,20 +2622,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 Command("export").description("Export billing ledger rows.").addHelpText(
+      "after",
+      `
+Examples:
+  deepline billing ledger export all
+`
+    ).addCommand(
+      new 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
 import { writeFileSync as writeFileSync4 } from "fs";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 var CSV_PROJECTED_FIELDS_KEY = "__deeplineCsvProjectedFields";
 function csvProjectedFields(row) {
   const serialized = row[CSV_PROJECTED_FIELDS_KEY];
@@ -2838,7 +3101,7 @@ function writeCanonicalRowsCsv(rowsInfo, outPath) {
     rows: rowsInfo.rows,
     columns: rowsInfo.columns
   });
-  const resolved = resolve3(outPath);
+  const resolved = resolve4(outPath);
   writeFileSync4(
     resolved,
     csvStringFromRows(sanitized.rows, sanitized.columns),
@@ -2934,8 +3197,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
@@ -3015,8 +3301,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,
@@ -3042,9 +3352,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
@@ -3124,9 +3454,43 @@ 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
@@ -3138,19 +3502,19 @@ import {
   realpathSync,
   writeFileSync as writeFileSync5
 } from "fs";
-import { basename as basename3, dirname as dirname7, join as join6, resolve as resolve7 } from "path";
+import { basename as basename3, dirname as dirname8, join as join6, resolve as resolve8 } from "path";
 
 // src/plays/bundle-play-file.ts
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname6, join as join5, resolve as resolve6 } from "path";
+import { dirname as dirname7, join as join5, resolve as resolve7 } from "path";
 import { fileURLToPath } from "url";
 import { existsSync as existsSync4 } from "fs";
 
 // ../shared_libs/plays/bundling/index.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir2, readFile, realpath, stat, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir3, readFile, realpath, stat, writeFile as writeFile3 } from "fs/promises";
 import { tmpdir } from "os";
-import { basename, dirname as dirname4, extname, isAbsolute, join as join3, resolve as resolve4 } from "path";
+import { basename, dirname as dirname5, extname, isAbsolute, join as join3, resolve as resolve5 } from "path";
 import { builtinModules, createRequire } from "module";
 import { build } from "esbuild";
 
@@ -3243,13 +3607,13 @@ async function normalizeLocalPath(filePath) {
   try {
     return await realpath(filePath);
   } catch {
-    return resolve4(filePath);
+    return resolve5(filePath);
   }
 }
 function createPlayWorkspace(entryFile) {
   return {
     entryFile,
-    rootDir: dirname4(entryFile)
+    rootDir: dirname5(entryFile)
   };
 }
 function isPathInsideDirectory(filePath, directory) {
@@ -3450,7 +3814,7 @@ function workersNamedPlayEntryAliasPlugin(playFilePath, exportName) {
           contents: `export { ${exportName} as default } from ${JSON.stringify(playFilePath)};
 `,
           loader: "ts",
-          resolveDir: dirname4(playFilePath)
+          resolveDir: dirname5(playFilePath)
         })
       );
     }
@@ -3614,7 +3978,7 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
         return {
           contents: buildImportedPlayProxyModule(dependency.playName),
           loader: "ts",
-          resolveDir: dirname4(args.path)
+          resolveDir: dirname5(args.path)
         };
       });
     }
@@ -3632,7 +3996,7 @@ async function resolveLocalImport(fromFile, specifier) {
   if (specifier.startsWith("file:")) {
     return normalizeLocalPath(new URL(specifier).pathname);
   }
-  const base = isAbsolute(specifier) ? resolve4(specifier) : resolve4(dirname4(fromFile), specifier);
+  const base = isAbsolute(specifier) ? resolve5(specifier) : resolve5(dirname5(fromFile), specifier);
   const candidates = [base];
   const explicitExtension = extname(base).toLowerCase();
   if (!explicitExtension) {
@@ -3833,8 +4197,8 @@ async function readArtifactCache(graphHash, artifactKind, adapter) {
 }
 async function writeArtifactCache(artifact, adapter) {
   const cacheDir = adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR;
-  await mkdir2(cacheDir, { recursive: true });
-  await writeFile2(
+  await mkdir3(cacheDir, { recursive: true });
+  await writeFile3(
     artifactCachePath(
       artifact.graphHash,
       artifact.artifactKind ?? PLAY_ARTIFACT_KINDS.cjsNode20,
@@ -3850,7 +4214,7 @@ function normalizeSourceMapForRuntime(sourceMapText) {
     if (sourcePath.startsWith("data:") || sourcePath.startsWith("node:") || sourcePath.startsWith("/") || /^[a-zA-Z]+:\/\//.test(sourcePath)) {
       return sourcePath;
     }
-    return resolve4(process.cwd(), sourcePath);
+    return resolve5(process.cwd(), sourcePath);
   });
   parsed.sourceRoot = void 0;
   return JSON.stringify(parsed);
@@ -3882,7 +4246,7 @@ async function runEsbuildForCjsNode(entryFile, importedPlayDependencies, adapter
     ...namedExportShim ? {
       stdin: {
         contents: namedExportShim,
-        resolveDir: dirname4(entryFile),
+        resolveDir: dirname5(entryFile),
         sourcefile: `${basename(entryFile)}.${exportName}.entry.ts`,
         loader: "ts"
       }
@@ -4172,7 +4536,7 @@ function resolveExecutionProfile(override) {
 // src/plays/local-file-discovery.ts
 import { createHash as createHash2 } from "crypto";
 import { readFile as readFile2, stat as stat2 } from "fs/promises";
-import { basename as basename2, dirname as dirname5, extname as extname2, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve5 } from "path";
+import { basename as basename2, dirname as dirname6, extname as extname2, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve6 } from "path";
 var SOURCE_EXTENSIONS2 = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
 function sha2562(buffer) {
   return createHash2("sha256").update(buffer).digest("hex");
@@ -4373,7 +4737,7 @@ function isPathInsideDirectory2(filePath, directory) {
   return relativePath === "" || !relativePath.startsWith("..") && !isAbsolute2(relativePath);
 }
 async function resolveLocalImport2(fromFile, specifier) {
-  const base = isAbsolute2(specifier) ? resolve5(specifier) : resolve5(dirname5(fromFile), specifier);
+  const base = isAbsolute2(specifier) ? resolve6(specifier) : resolve6(dirname6(fromFile), specifier);
   const candidates = [base];
   const explicitExtension = extname2(base).toLowerCase();
   if (!explicitExtension) {
@@ -4391,13 +4755,13 @@ async function resolveLocalImport2(fromFile, specifier) {
   throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
 }
 async function discoverPackagedLocalFiles(entryFile) {
-  const absoluteEntryFile = resolve5(entryFile);
-  const packagingRoot = dirname5(absoluteEntryFile);
+  const absoluteEntryFile = resolve6(entryFile);
+  const packagingRoot = dirname6(absoluteEntryFile);
   const files = /* @__PURE__ */ new Map();
   const unresolved = [];
   const visitedFiles = /* @__PURE__ */ new Set();
   const visitSourceFile = async (filePath) => {
-    const absolutePath = resolve5(filePath);
+    const absolutePath = resolve6(filePath);
     if (visitedFiles.has(absolutePath)) {
       return;
     }
@@ -4429,7 +4793,7 @@ 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 = resolve5(dirname5(absolutePath), resolvedPath);
+          const absoluteCsvPath = resolve6(dirname6(absolutePath), resolvedPath);
           if (isAbsolute2(resolvedPath) || !isPathInsideDirectory2(absoluteCsvPath, packagingRoot)) {
             unresolved.push({
               sourceFragment: sourceCode.slice(argument.start, argument.end).trim(),
@@ -4468,24 +4832,24 @@ async function discoverPackagedLocalFiles(entryFile) {
 
 // src/plays/bundle-play-file.ts
 var PLAY_BUNDLE_CACHE_VERSION2 = 26;
-var MODULE_DIR = dirname6(fileURLToPath(import.meta.url));
-var SDK_PACKAGE_ROOT = resolve6(MODULE_DIR, "..", "..");
-var SOURCE_REPO_ROOT = resolve6(SDK_PACKAGE_ROOT, "..");
+var MODULE_DIR = dirname7(fileURLToPath(import.meta.url));
+var SDK_PACKAGE_ROOT = resolve7(MODULE_DIR, "..", "..");
+var SOURCE_REPO_ROOT = resolve7(SDK_PACKAGE_ROOT, "..");
 var HAS_SOURCE_BUNDLING_SOURCES = existsSync4(
-  resolve6(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  resolve7(SOURCE_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
 );
-var PACKAGED_REPO_ROOT = resolve6(SDK_PACKAGE_ROOT, "dist", "repo");
+var PACKAGED_REPO_ROOT = resolve7(SDK_PACKAGE_ROOT, "dist", "repo");
 var HAS_PACKAGED_BUNDLING_SOURCES = existsSync4(
-  resolve6(PACKAGED_REPO_ROOT, "apps", "play-runner-workers", "src", "entry.ts")
+  resolve7(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 : resolve6(SDK_PACKAGE_ROOT, "..");
-var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? resolve6(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? resolve6(PACKAGED_REPO_ROOT, "sdk", "src") : resolve6(SDK_PACKAGE_ROOT, "src");
-var SDK_PACKAGE_JSON = resolve6(SDK_PACKAGE_ROOT, "package.json");
-var SDK_ENTRY_FILE = resolve6(SDK_SOURCE_ROOT, "index.ts");
-var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : resolve6(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
-var SDK_WORKERS_ENTRY_FILE = resolve6(SDK_SOURCE_ROOT, "worker-play-entry.ts");
-var WORKERS_HARNESS_ENTRY_FILE = resolve6(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
-var WORKERS_HARNESS_FILES_DIR = resolve6(PROJECT_ROOT, "apps", "play-runner-workers", "src");
+var PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? SOURCE_REPO_ROOT : HAS_PACKAGED_BUNDLING_SOURCES ? PACKAGED_REPO_ROOT : resolve7(SDK_PACKAGE_ROOT, "..");
+var SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES ? resolve7(SOURCE_REPO_ROOT, "sdk", "src") : HAS_PACKAGED_BUNDLING_SOURCES ? resolve7(PACKAGED_REPO_ROOT, "sdk", "src") : resolve7(SDK_PACKAGE_ROOT, "src");
+var SDK_PACKAGE_JSON = resolve7(SDK_PACKAGE_ROOT, "package.json");
+var SDK_ENTRY_FILE = resolve7(SDK_SOURCE_ROOT, "index.ts");
+var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : resolve7(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
+var SDK_WORKERS_ENTRY_FILE = resolve7(SDK_SOURCE_ROOT, "worker-play-entry.ts");
+var WORKERS_HARNESS_ENTRY_FILE = resolve7(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
+var WORKERS_HARNESS_FILES_DIR = resolve7(PROJECT_ROOT, "apps", "play-runner-workers", "src");
 var hasWarnedAboutNonDevelopmentBundling = false;
 function warnAboutNonDevelopmentBundling(filePath) {
   if (hasWarnedAboutNonDevelopmentBundling) {
@@ -4509,7 +4873,7 @@ function defaultPlayBundleTarget() {
 function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
-    nodeModulesDir: resolve6(PROJECT_ROOT, "node_modules"),
+    nodeModulesDir: resolve7(PROJECT_ROOT, "node_modules"),
     cacheDir: join5(tmpdir2(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
@@ -4790,7 +5154,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 resolve7(`${safeName || "play"}.play.ts`);
+  return resolve8(`${safeName || "play"}.play.ts`);
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -4853,7 +5217,7 @@ function extractPlayName(code, filePath) {
   throw buildMissingDefinePlayError(filePath);
 }
 function isFileTarget(target) {
-  return existsSync5(resolve7(target));
+  return existsSync5(resolve8(target));
 }
 function looksLikeFilePath(target) {
   if (target.trim().toLowerCase().startsWith("prebuilt/")) {
@@ -4872,7 +5236,7 @@ function parsePositiveInteger2(value, flagName) {
   return parsed;
 }
 function parseJsonInput(raw) {
-  const source = raw.startsWith("@") ? readFileSync3(resolve7(raw.slice(1)), "utf-8") : raw;
+  const source = raw.startsWith("@") ? readFileSync3(resolve8(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.");
@@ -4982,7 +5346,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 existsSync5(resolve7(value));
+  return existsSync5(resolve8(value));
 }
 function inputContainsLocalFilePath(value) {
   if (isLocalFilePathValue(value)) {
@@ -5008,7 +5372,7 @@ async function stageFileInputArgs(input) {
   const localFiles = uniqueBindings.flatMap((binding) => {
     const value = getDottedInputValue(input.runtimeInput, binding.inputPath);
     if (!isLocalFilePathValue(value)) return [];
-    const absolutePath = resolve7(value);
+    const absolutePath = resolve8(value);
     return [{ binding, absolutePath, logicalPath: basename3(absolutePath) }];
   });
   if (localFiles.length === 0) {
@@ -5044,9 +5408,9 @@ function stageFile(logicalPath, absolutePath) {
 }
 function normalizePlayPath(filePath) {
   try {
-    return realpathSync.native(resolve7(filePath));
+    return realpathSync.native(resolve8(filePath));
   } catch {
-    return resolve7(filePath);
+    return resolve8(filePath);
   }
 }
 function formatBundlingErrors(filePath, errors) {
@@ -6072,7 +6436,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");
@@ -6106,7 +6470,7 @@ function parsePlayRunOptions(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = resolve7(args[++index]);
+      outPath = resolve8(args[++index]);
       continue;
     }
     if (arg === "--poll-interval-ms" || arg === "--interval-ms") {
@@ -6122,15 +6486,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."
@@ -6208,11 +6570,11 @@ function shouldUseLocalOnlyPlayCheck() {
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
-    const resolved = resolve7(options.target);
+    const resolved = resolve8(options.target);
     console.error(`File not found: ${resolved}`);
     return 1;
   }
-  const absolutePlayPath = resolve7(options.target);
+  const absolutePlayPath = resolve8(options.target);
   const sourceCode = readFileSync3(absolutePlayPath, "utf-8");
   let graph;
   try {
@@ -6276,7 +6638,7 @@ async function handleFileBackedRun(options) {
   }
   const client = new DeeplineClient();
   const progress = getActiveCliProgress() ?? createCliProgress(!options.jsonOutput);
-  const absolutePlayPath = resolve7(options.target.path);
+  const absolutePlayPath = resolve8(options.target.path);
   progress.phase("compiling play");
   const sourceCode = traceCliSync(
     "cli.play_file_read_source",
@@ -6565,9 +6927,9 @@ async function handlePlayRun(args) {
     if (isFileTarget(options.target.path)) {
       return handleFileBackedRun(options);
     }
-    const resolved = resolve7(options.target.path);
+    const resolved = resolve8(options.target.path);
     console.error(`File not found: ${resolved}`);
-    const dir = dirname7(resolved);
+    const dir = dirname8(resolved);
     if (existsSync5(dir)) {
       const base = basename3(resolved);
       try {
@@ -6723,7 +7085,7 @@ async function handleRunLogs(args) {
       continue;
     }
     if (arg === "--out" && args[index + 1]) {
-      outPath = resolve7(args[++index]);
+      outPath = resolve8(args[++index]);
     }
   }
   const client = new DeeplineClient();
@@ -6810,7 +7172,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 = resolve7(args[++index]);
+      outPath = resolve8(args[++index]);
     }
   }
   if (!outPath) {
@@ -6850,10 +7212,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 = resolve7(args[++index]);
+      outPath = resolve8(args[++index]);
     }
   }
-  const playName = isFileTarget(target) ? extractPlayName(readFileSync3(resolve7(target), "utf-8"), resolve7(target)) : parseReferencedPlayTarget(target).playName;
+  const playName = isFileTarget(target) ? extractPlayName(readFileSync3(resolve8(target), "utf-8"), resolve8(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({
@@ -7145,7 +7507,7 @@ async function handlePlayPublish(args) {
     }
     let graph;
     try {
-      graph = await collectBundledPlayGraph(resolve7(playName));
+      graph = await collectBundledPlayGraph(resolve8(playName));
       await compileBundledPlayGraphManifests(client, graph);
       await publishImportedPlayDependencies(client, graph);
     } catch (error) {
@@ -7245,12 +7607,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
 `
   );
@@ -7280,9 +7645,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:
@@ -7307,6 +7674,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
@@ -7318,7 +7686,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) => {
@@ -7341,7 +7709,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"] : [],
@@ -7372,12 +7740,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] : [],
@@ -7403,13 +7795,53 @@ 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"] : [],
+      ...options.revisionId ? ["--revision-id", options.revisionId] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
+  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"] : [],
@@ -7417,7 +7849,18 @@ 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) => {
+  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"] : [],
@@ -7427,6 +7870,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
@@ -7436,14 +7885,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,
@@ -7452,14 +7923,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] : [],
@@ -7467,14 +7961,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",
@@ -7718,16 +8234,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,
@@ -7736,15 +8280,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([
@@ -7752,12 +8299,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"}'
@@ -8249,7 +8800,7 @@ async function executeTool(args) {
 import { spawn, spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname8, join as join9 } from "path";
+import { dirname as dirname9, join as join9 } from "path";
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-sdk";
 var SKILL_AGENTS = ["codex", "claude-code", "cursor"];
@@ -8273,7 +8824,7 @@ function readLocalSkillsVersion(baseUrl) {
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  mkdirSync5(dirname8(path), { recursive: true });
+  mkdirSync5(dirname9(path), { recursive: true });
   writeFileSync8(path, `${version}
 `, "utf-8");
 }
@@ -8368,7 +8919,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   return [npxInstall];
 }
 function runOneSkillsInstall(install) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const child = spawn(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
@@ -8378,7 +8929,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
@@ -8386,11 +8937,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
@@ -8443,6 +8994,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";
@@ -8464,7 +9018,7 @@ async function main() {
   if (printStartupPhase) {
     progress?.phase("loading deepline cli");
   }
-  const program = new Command();
+  const program = new Command2();
   program.name("deepline").description("Deepline CLI (TypeScript SDK)").version(SDK_VERSION, "-v, --version", "Show version").showHelpAfterError().showSuggestionAfterError(true).addHelpText(
     "after",
     `
@@ -8476,9 +9030,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) => {
@@ -8513,7 +9081,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();
@@ -8525,7 +9103,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}
 `);
   });