deepline 0.1.77 → 0.1.78

package/dist/cli/index.mjs

@@ -206,10 +206,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.77",
+  version: "0.1.78",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.77",
+    latest: "0.1.78",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -379,8 +379,8 @@ var HttpClient = class {
     if (lastError instanceof DeeplineError) {
       throw lastError;
     }
-    const errorMessage2 = lastError?.message ? `Unable to connect to ${baseUrl}. ${lastError.message}` : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
-    throw new DeeplineError(errorMessage2);
+    const errorMessage3 = lastError?.message ? `Unable to connect to ${baseUrl}. ${lastError.message}` : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`;
+    throw new DeeplineError(errorMessage3);
   }
   /**
    * Send a GET request.
@@ -785,6 +785,7 @@ var DeeplineClient = class {
       aliases,
       inputSchema: options?.compact ? this.compactSchema(play.inputSchema) : play.inputSchema ?? null,
       outputSchema: options?.compact ? this.compactSchema(play.outputSchema) : play.outputSchema ?? null,
+      staticPipeline: isRecord(play.staticPipeline) ? play.staticPipeline : isRecord(play.currentRevision?.staticPipeline) ? play.currentRevision.staticPipeline : isRecord(play.liveRevision?.staticPipeline) ? play.liveRevision.staticPipeline : null,
       ...csvInput ? { csvInput } : {},
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand: runCommand2,
@@ -4016,6 +4017,51 @@ function customerDbRows(result) {
 function customerDbColumnNames(result) {
   return result.columns.map((column) => column.name).filter(Boolean);
 }
+function errorMessage(value) {
+  return value instanceof Error ? value.message : String(value ?? "");
+}
+function collectErrorText(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return errorMessage(value);
+  }
+  const record = value;
+  return [
+    errorMessage(value),
+    typeof record.error === "string" ? record.error : "",
+    typeof record.message === "string" ? record.message : "",
+    typeof record.detail === "string" ? record.detail : "",
+    typeof record.hint === "string" ? record.hint : "",
+    typeof record.code === "string" ? record.code : "",
+    record.response ? collectErrorText(record.response) : "",
+    record.details ? collectErrorText(record.details) : ""
+  ].filter(Boolean).join("\n");
+}
+function formatDbQueryError(sql, error) {
+  const text = collectErrorText(error);
+  const lower = text.toLowerCase();
+  const referencesStorage = /"storage"\.|storage\./i.test(sql);
+  const runIdColumnMissing = /column\s+"?run_id"?\s+does not exist/i.test(text) || /run_id.*does not exist/i.test(lower);
+  const relationMissing = /relation\s+["']?[^"']*storage[^"']*["']?\s+does not exist/i.test(text) || /42p01/i.test(text);
+  if (referencesStorage && relationMissing) {
+    return [
+      "Customer DB query failed: the referenced storage table does not exist.",
+      "Play map tables are created only when the corresponding ctx.map(...).run(...) call executes. Pilot branches, early returns, and runs that fail before the map do not create that table.",
+      "Use `deepline runs get <run-id> --full --json` to inspect returned dataset handles, then export them with `deepline runs export <run-id> --dataset result.rows --out rows.csv`.",
+      `Original error: ${errorMessage(error)}`
+    ].join("\n");
+  }
+  if (referencesStorage && runIdColumnMissing) {
+    return [
+      "Customer DB query failed: storage map tables use `_run_id`, not `run_id`.",
+      "Prefer `deepline runs export <run-id> --dataset result.rows --out rows.csv` unless you are doing deep table debugging.",
+      `Original error: ${errorMessage(error)}`
+    ].join("\n");
+  }
+  if (error instanceof DeeplineError) {
+    return error.message;
+  }
+  return errorMessage(error);
+}
 function writeCustomerDbCsv(result, outPath) {
   const resolved = resolve5(outPath);
   writeFileSync5(
@@ -4076,7 +4122,13 @@ async function handleDbQuery(args) {
   const jsonOutput = argsWantJson(args);
   const explicitJsonOutput = args.includes("--json");
   const client = new DeeplineClient();
-  const result = await client.queryCustomerDb({ sql, maxRows });
+  let result;
+  try {
+    result = await client.queryCustomerDb({ sql, maxRows });
+  } catch (error) {
+    console.error(formatDbQueryError(sql, error));
+    return 1;
+  }
   const toolCommand = `deepline tools execute query_customer_db --payload ${JSON.stringify(
     {
       sql,
@@ -4237,7 +4289,7 @@ import {
   readFileSync as readFileSync6,
   readdirSync,
   realpathSync,
-  writeFileSync as writeFileSync6
+  writeFileSync as writeFileSync7
 } from "fs";
 import { basename as basename3, dirname as dirname8, join as join7, resolve as resolve10 } from "path";
 
@@ -5910,7 +5962,7 @@ async function bundlePlayFile2(filePath, options = {}) {
 }
 
 // src/cli/commands/plays/bootstrap.ts
-import { closeSync, openSync, readSync, statSync } from "fs";
+import { closeSync, openSync, readSync, statSync, writeFileSync as writeFileSync6 } from "fs";
 import { isAbsolute as isAbsolute3, relative as relative2, resolve as resolve9 } from "path";
 import { parse as parseCsvSync } from "csv-parse/sync";
 
@@ -6085,19 +6137,19 @@ function playBootstrapTemplateConfig(template) {
 function templateExample(template) {
   switch (template) {
     case "people-list":
-      return "deepline plays bootstrap people-list --from provider:dropleads_search_people > people.play.ts";
+      return "deepline plays bootstrap people-list --from provider:dropleads_search_people --out people.play.ts";
     case "company-list":
-      return "deepline plays bootstrap company-list --from provider:apollo_company_search > companies.play.ts";
+      return "deepline plays bootstrap company-list --from provider:apollo_company_search --out companies.play.ts";
     case "people-email":
-      return "deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall > email-flow.play.ts";
+      return "deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --out email-flow.play.ts";
     case "people-phone":
-      return "deepline plays bootstrap people-phone --from csv:data/vp_contacts.csv --using play:prebuilt/person-to-phone > phone-flow.play.ts";
+      return "deepline plays bootstrap people-phone --from csv:data/vp_contacts.csv --using play:prebuilt/person-to-phone --out phone-flow.play.ts";
     case "company-people":
-      return "deepline plays bootstrap company-people --from provider:apollo_company_search --using play:prebuilt/company-to-contact > company-people.play.ts";
+      return "deepline plays bootstrap company-people --from provider:apollo_company_search --using play:prebuilt/company-to-contact --out company-people.play.ts";
     case "company-people-email":
-      return "deepline plays bootstrap company-people-email --from provider:apollo_company_search --people play:prebuilt/company-to-contact --email providers:hunter_email_finder,leadmagic_email_finder > account-emails.play.ts";
+      return "deepline plays bootstrap company-people-email --from provider:apollo_company_search --people play:prebuilt/company-to-contact --email providers:hunter_email_finder,leadmagic_email_finder --out account-emails.play.ts";
     case "company-people-phone":
-      return "deepline plays bootstrap company-people-phone --from provider:apollo_company_search --people play:prebuilt/company-to-contact --phone providers:ai_ark_mobile_phone_finder > account-phones.play.ts";
+      return "deepline plays bootstrap company-people-phone --from provider:apollo_company_search --people play:prebuilt/company-to-contact --phone providers:ai_ark_mobile_phone_finder --out account-phones.play.ts";
   }
 }
 var PLAY_BOOTSTRAP_STAGE_NAMES = [
@@ -6106,19 +6158,22 @@ var PLAY_BOOTSTRAP_STAGE_NAMES = [
   "phone"
 ];
 function playBootstrapUsageLine() {
-  return `Usage: deepline plays bootstrap <${formatPlayBootstrapTemplates()}> --from <csv:PATH|play:REF|provider:ID|providers:ID,ID> [--using <play:REF|providers:ID,ID>] [--people play:REF] [--email <play:REF|providers:ID,ID>] [--phone <play:REF|providers:ID,ID>] [--limit 5] > flow.play.ts`;
+  return `Usage: deepline plays bootstrap <${formatPlayBootstrapTemplates()}> --from <csv:PATH|play:REF|provider:ID|providers:ID,ID> [--using <play:REF|providers:ID,ID>] [--people play:REF] [--email <play:REF|providers:ID,ID>] [--phone <play:REF|providers:ID,ID>] [--limit 5] [--out flow.play.ts]`;
 }
 function requireBootstrapTemplate(rawTemplate) {
   if (!rawTemplate) {
     throw new PlayBootstrapUsageError(
       `plays bootstrap needs a route template: ${formatPlayBootstrapTemplates()}.
-Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall > email-flow.play.ts`
+Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --out email-flow.play.ts`
     );
   }
   if (!isPlayBootstrapTemplate(rawTemplate)) {
+    const looksLikePlayReference = rawTemplate.includes("/") || rawTemplate.endsWith(".play.ts");
     throw new PlayBootstrapUsageError(
       `Unknown plays bootstrap template: ${rawTemplate}
-Supported templates: ${formatPlayBootstrapTemplates()}`
+Supported templates: ${formatPlayBootstrapTemplates()}` + (looksLikePlayReference ? `
+
+"${rawTemplate}" looks like an existing play reference or file, not a bootstrap template. Do not run plays bootstrap on prebuilt/<play-name>. Use "deepline plays run ${rawTemplate} --input '{...}' --watch" to run it directly, "deepline plays describe ${rawTemplate} --json" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
   }
   return rawTemplate;
@@ -6260,7 +6315,8 @@ function parsePlayBootstrapOptions(args) {
     people: null,
     email: null,
     phone: null,
-    limit: 5
+    limit: 5,
+    out: null
   };
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
@@ -6294,6 +6350,10 @@ function parsePlayBootstrapOptions(args) {
         options.limit = parsePositiveInteger2(value(), "--limit");
         index += 1;
         break;
+      case "--out":
+        options.out = value();
+        index += 1;
+        break;
       default:
         throw new PlayBootstrapUsageError(
           `Unknown plays bootstrap option: ${arg}
@@ -6411,7 +6471,7 @@ function packagedCsvPathForPlay(csvPath) {
   const relativePath = relative2(playDir, absoluteCsvPath);
   if (relativePath === "" || relativePath.startsWith("..") || isAbsolute3(relativePath)) {
     throw new PlayBootstrapUsageError(
-      `--from csv:${csvPath} must point to a file inside the directory where you run plays bootstrap. Run bootstrap from the intended play directory, then redirect stdout to a .play.ts file there.`
+      `--from csv:${csvPath} must point to a file inside the directory where you run plays bootstrap. Run bootstrap from the intended play directory and write the play with --out there.`
     );
   }
   const portablePath = relativePath.split("\\").join("/");
@@ -6818,8 +6878,18 @@ function validateBootstrapRoutes(input2) {
       "Company-to-people bootstrap only accepts --people play:<play-ref> for now. Providers are too task-specific; choose or create a people play so the generated file can show the mapping contract."
     );
   }
+  assertComposablePlayRoute({
+    stageLabel: "--people",
+    playRef: stagePlayRef(input2.options.people),
+    play: input2.peoplePlay
+  });
   for (const finder of ["email_finder", "phone_finder"]) {
     const requiredCategory = PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER[finder];
+    assertComposablePlayRoute({
+      stageLabel: finder === "email_finder" ? "--email/--using" : "--phone/--using",
+      playRef: stagePlayRef(finderStage(input2.options, finder)),
+      play: input2.finderPlays[finder] ?? null
+    });
     for (const tool of input2.finderTools[finder] ?? []) {
       if (!tool.categories.includes(requiredCategory)) {
         throw new PlayBootstrapValidationError(
@@ -6834,6 +6904,38 @@ function validateBootstrapRoutes(input2) {
     }
   }
 }
+function staticPipelineSubsteps(pipeline) {
+  if (!isRecord3(pipeline)) return [];
+  return [
+    ...extractionEntries(pipeline.stages),
+    ...extractionEntries(pipeline.substeps)
+  ];
+}
+function playUsesMapBackedRuntime(play) {
+  const pipeline = play?.staticPipeline;
+  if (!isRecord3(pipeline)) return false;
+  if (stringValue(pipeline.tableNamespace)) return true;
+  return staticPipelineSubsteps(pipeline).some((substep) => {
+    if (stringValue(substep.type) === "map") return true;
+    return playUsesMapBackedRuntime({
+      name: play?.name ?? "child",
+      aliases: [],
+      runCommand: "",
+      examples: [],
+      staticPipeline: isRecord3(substep.pipeline) ? substep.pipeline : null
+    });
+  });
+}
+function assertComposablePlayRoute(input2) {
+  if (!input2.playRef || !playUsesMapBackedRuntime(input2.play)) return;
+  const runCommand2 = input2.play?.runCommand?.trim() || `deepline plays run ${input2.playRef} --input '{...}' --watch`;
+  throw new PlayBootstrapValidationError(
+    `Cannot use ${input2.stageLabel} play:${input2.playRef} in plays bootstrap composition: the selected play is map-backed/direct-run-only. Child plays that use ctx.map() own durable table state and must be run directly, exported, or validated as their own play instead of wrapped with ctx.runPlay. Run it directly first: ${runCommand2}`
+  );
+}
+function sourcePlayNeedsExportFirst(input2) {
+  return input2.source.kind === "play" && playUsesMapBackedRuntime(input2.sourcePlay);
+}
 function sourceCollectionName(entity) {
   switch (entity) {
     case "company":
@@ -6863,6 +6965,22 @@ function generateCsvSourceRowsBlock(input2) {
   const ${input2.collection}: ${input2.collectionType}[] = await sourceDataset.peek(limit);`;
 }
 function generatePlaySourceRowsBlock(input2) {
+  if (sourcePlayNeedsExportFirst({
+    source: input2.source,
+    sourcePlay: input2.sourcePlay
+  })) {
+    const sourcePlay = input2.sourcePlay;
+    const runCommand2 = sourcePlay?.runCommand?.trim() || `deepline plays run ${input2.source.value} --input '{...}' --watch`;
+    return `// Source play ${input2.source.value} is map-backed/direct-run-only, so this generated play is stage 2.
+  // Stage 1:
+  //   ${runCommand2}
+  // Stage 2:
+  //   deepline runs export <stage-1-run-id> --dataset 'result.rows' --out source-export.csv
+  // Stage 3:
+  //   deepline plays run <this-file.play.ts> --input '{"sourceCsv":"source-export.csv","limit":${input2.sourcePlay ? "5" : "5"}}' --watch
+  const sourceDataset = await ctx.csv<${input2.collectionType}>(input.sourceCsv ?? './source-export.csv');
+  const ${input2.collection}: ${input2.collectionType}[] = await sourceDataset.peek(limit);`;
+  }
   const playInput = generatePlayInputObject({
     schema: input2.sourcePlay?.inputSchema,
     indent: "    ",
@@ -7147,6 +7265,7 @@ ${typeDefinitions}
 
 type Input = {
   limit?: number;
+  sourceCsv?: string;
 };
 
 export default definePlay(${jsString(input2.options.name)}, async (ctx, input: Input = {}) => {
@@ -7213,6 +7332,7 @@ async function loadBootstrapContracts(client, options) {
   validateBootstrapRoutes({
     options,
     sourceTools: contracts.sourceTools,
+    sourcePlay: contracts.sourcePlay,
     peoplePlay: contracts.peoplePlay,
     finderTools: contracts.finderTools,
     finderPlays: contracts.finderPlays
@@ -7234,11 +7354,11 @@ function loadCsvContext(source) {
       };
   }
 }
-function errorMessage(error) {
+function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function renderPlayBootstrapError(error) {
-  console.error(errorMessage(error));
+  console.error(errorMessage2(error));
   return error instanceof PlayBootstrapError ? error.exitCode : 1;
 }
 async function runPlayBootstrap(args) {
@@ -7251,6 +7371,12 @@ async function runPlayBootstrap(args) {
     ...contracts,
     ...csvContext
   });
+  if (options.out) {
+    writeFileSync6(resolve9(options.out), source, "utf-8");
+    process.stdout.write(`Wrote ${resolve9(options.out)}
+`);
+    return 0;
+  }
   process.stdout.write(source);
   return 0;
 }
@@ -7263,7 +7389,7 @@ function registerPlayBootstrapCommand(play) {
     `
 Notes:
   Cloud-validated play generator for agents. Pick the JTBD as the positional
-  template, bind resources with typed refs, redirect stdout to a .play.ts file,
+  template, bind resources with typed refs, write the .play.ts file with --out,
   then edit the generated TODO mapping comments. Multiple finder providers are
   generated as a waterfall in the order you pass them.
 
@@ -7271,9 +7397,8 @@ Notes:
   Deepline. It prints TypeScript source only and does not run paid tools; the
   generated play may spend credits later when you run it.
 
-  stdout is the generated .play.ts source. Errors and diagnostics go to stderr.
-  There is no JSON mode and no --out; use shell redirection:
-    deepline plays bootstrap ... > scratchpad.play.ts
+  By default stdout is the generated .play.ts source. Use --out to write a file
+  directly. Errors and diagnostics go to stderr. There is no JSON mode.
 
   Templates:
     people-list             start from people/contact rows
@@ -7297,7 +7422,7 @@ Notes:
     email/phone finder providers must match their category and expose value getters
     finder plays/providers must match the route; generated code leaves input mapping explicit
     business-specific provider inputs and company -> people persona fields are TODOs in code
-    csv: paths are resolved from the directory where you run bootstrap; redirect the play file there too
+    csv: paths are resolved from the directory where you run bootstrap; write the play file there too
 
   Exit codes:
     0 success
@@ -7305,13 +7430,13 @@ Notes:
     7 route validation failed
 
 Examples:
-  deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --limit 5 > email-flow.play.ts
+  deepline plays bootstrap people-email --from csv:data/leads.csv --using play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out email-flow.play.ts
   deepline plays check email-flow.play.ts
   deepline plays run email-flow.play.ts --input '{"limit":5}' --watch
 
-  deepline plays bootstrap people-email --from provider:dropleads_search_people --using providers:hunter_email_finder,leadmagic_email_finder --limit 5 > prospecting.play.ts
-  deepline plays bootstrap company-people-email --from provider:apollo_company_search --people play:prebuilt/company-to-contact --email play:prebuilt/name-and-domain-to-email-waterfall --limit 5 > account-contacts.play.ts
-  deepline plays bootstrap company-list --from provider:apollo_company_search --limit 5 > companies.play.ts
+  deepline plays bootstrap people-email --from provider:dropleads_search_people --using providers:hunter_email_finder,leadmagic_email_finder --limit 5 --out prospecting.play.ts
+  deepline plays bootstrap company-people-email --from provider:apollo_company_search --people play:prebuilt/company-to-contact --email play:prebuilt/name-and-domain-to-email-waterfall --limit 5 --out account-contacts.play.ts
+  deepline plays bootstrap company-list --from provider:apollo_company_search --limit 5 --out companies.play.ts
 `
   ).option("--name <name>", "Generated play name").option(
     "--from <ref>",
@@ -7328,7 +7453,7 @@ Examples:
   ).option(
     "--phone <ref>",
     "Phone finder stage: play:REF, provider:ID, or providers:ID,ID"
-  ).option("--limit <n>", "Maximum rows to fan out in the generated play").action(async (template, options) => {
+  ).option("--limit <n>", "Maximum rows to fan out in the generated play").option("--out <path>", "Write generated play source to a file").action(async (template, options) => {
     process.exitCode = await handlePlayBootstrap([
       template,
       ...options.name ? ["--name", options.name] : [],
@@ -7337,7 +7462,8 @@ Examples:
       ...options.people ? ["--people", options.people] : [],
       ...options.email ? ["--email", options.email] : [],
       ...options.phone ? ["--phone", options.phone] : [],
-      ...options.limit ? ["--limit", options.limit] : []
+      ...options.limit ? ["--limit", options.limit] : [],
+      ...options.out ? ["--out", options.out] : []
     ]);
   });
 }
@@ -7487,204 +7613,6 @@ function createCliProgress(enabled) {
   return progress;
 }
 
-// ../shared_libs/plays/row-identity.ts
-var POSTGRES_IDENTIFIER_MAX_LENGTH = 63;
-var PLAY_NAME_MAX_LENGTH = POSTGRES_IDENTIFIER_MAX_LENGTH;
-var MAP_KEY_NAMESPACE_MAX_LENGTH = POSTGRES_IDENTIFIER_MAX_LENGTH;
-var SHA256_INITIAL_HASH = [
-  1779033703,
-  3144134277,
-  1013904242,
-  2773480762,
-  1359893119,
-  2600822924,
-  528734635,
-  1541459225
-];
-var SHA256_ROUND_CONSTANTS = [
-  1116352408,
-  1899447441,
-  3049323471,
-  3921009573,
-  961987163,
-  1508970993,
-  2453635748,
-  2870763221,
-  3624381080,
-  310598401,
-  607225278,
-  1426881987,
-  1925078388,
-  2162078206,
-  2614888103,
-  3248222580,
-  3835390401,
-  4022224774,
-  264347078,
-  604807628,
-  770255983,
-  1249150122,
-  1555081692,
-  1996064986,
-  2554220882,
-  2821834349,
-  2952996808,
-  3210313671,
-  3336571891,
-  3584528711,
-  113926993,
-  338241895,
-  666307205,
-  773529912,
-  1294757372,
-  1396182291,
-  1695183700,
-  1986661051,
-  2177026350,
-  2456956037,
-  2730485921,
-  2820302411,
-  3259730800,
-  3345764771,
-  3516065817,
-  3600352804,
-  4094571909,
-  275423344,
-  430227734,
-  506948616,
-  659060556,
-  883997877,
-  958139571,
-  1322822218,
-  1537002063,
-  1747873779,
-  1955562222,
-  2024104815,
-  2227730452,
-  2361852424,
-  2428436474,
-  2756734187,
-  3204031479,
-  3329325298
-];
-function rightRotate32(value, bits) {
-  return value >>> bits | value << 32 - bits;
-}
-function sha256Hex(input2) {
-  const bytes = Array.from(new TextEncoder().encode(input2));
-  const bitLength = bytes.length * 8;
-  bytes.push(128);
-  while (bytes.length % 64 !== 56) {
-    bytes.push(0);
-  }
-  const highBits = Math.floor(bitLength / 4294967296);
-  const lowBits = bitLength >>> 0;
-  bytes.push(
-    highBits >>> 24 & 255,
-    highBits >>> 16 & 255,
-    highBits >>> 8 & 255,
-    highBits & 255,
-    lowBits >>> 24 & 255,
-    lowBits >>> 16 & 255,
-    lowBits >>> 8 & 255,
-    lowBits & 255
-  );
-  const hash = [...SHA256_INITIAL_HASH];
-  const words = new Array(64).fill(0);
-  for (let offset = 0; offset < bytes.length; offset += 64) {
-    for (let index = 0; index < 16; index += 1) {
-      const wordOffset = offset + index * 4;
-      words[index] = (bytes[wordOffset] ?? 0) << 24 | (bytes[wordOffset + 1] ?? 0) << 16 | (bytes[wordOffset + 2] ?? 0) << 8 | (bytes[wordOffset + 3] ?? 0);
-    }
-    for (let index = 16; index < 64; index += 1) {
-      const s0 = rightRotate32(words[index - 15], 7) ^ rightRotate32(words[index - 15], 18) ^ words[index - 15] >>> 3;
-      const s1 = rightRotate32(words[index - 2], 17) ^ rightRotate32(words[index - 2], 19) ^ words[index - 2] >>> 10;
-      words[index] = words[index - 16] + s0 + words[index - 7] + s1 >>> 0;
-    }
-    let [a, b, c, d, e, f, g, h] = hash;
-    for (let index = 0; index < 64; index += 1) {
-      const s1 = rightRotate32(e, 6) ^ rightRotate32(e, 11) ^ rightRotate32(e, 25);
-      const ch = e & f ^ ~e & g;
-      const temp1 = h + s1 + ch + SHA256_ROUND_CONSTANTS[index] + words[index] >>> 0;
-      const s0 = rightRotate32(a, 2) ^ rightRotate32(a, 13) ^ rightRotate32(a, 22);
-      const maj = a & b ^ a & c ^ b & c;
-      const temp2 = s0 + maj >>> 0;
-      h = g;
-      g = f;
-      f = e;
-      e = d + temp1 >>> 0;
-      d = c;
-      c = b;
-      b = a;
-      a = temp1 + temp2 >>> 0;
-    }
-    hash[0] = hash[0] + a >>> 0;
-    hash[1] = hash[1] + b >>> 0;
-    hash[2] = hash[2] + c >>> 0;
-    hash[3] = hash[3] + d >>> 0;
-    hash[4] = hash[4] + e >>> 0;
-    hash[5] = hash[5] + f >>> 0;
-    hash[6] = hash[6] + g >>> 0;
-    hash[7] = hash[7] + h >>> 0;
-  }
-  return hash.map((word) => word.toString(16).padStart(8, "0")).join("");
-}
-function sanitizeIdentifierPart(value) {
-  return value.trim().replace(/[^a-z0-9]+/gi, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
-}
-function validateIdentifierPart(rawValue, label, maxLength) {
-  const sanitized = sanitizeIdentifierPart(rawValue);
-  if (!sanitized) {
-    throw new Error(
-      `${label} must contain at least one letter or number after normalization. Use only letters, numbers, underscores, or hyphens.`
-    );
-  }
-  if (sanitized.length > maxLength) {
-    throw new Error(
-      `${label} is too long after normalization (${sanitized.length}/${maxLength}). Shorten it to ${maxLength} characters or fewer. Normalized value: "${sanitized}".`
-    );
-  }
-  return sanitized;
-}
-function normalizePlayName(value) {
-  if (value.includes("/")) {
-    throw new Error(
-      'Play name cannot contain "/". Slash is reserved for qualified play references like "prebuilt/example" or "self/example".'
-    );
-  }
-  return validateIdentifierPart(value, "Play name", PLAY_NAME_MAX_LENGTH);
-}
-function normalizePlayNameForSheet(value) {
-  if (!value.includes("/")) {
-    return normalizePlayName(value);
-  }
-  const digest = sha256Hex(value).slice(0, 12);
-  const normalizedReference = sanitizeIdentifierPart(
-    value.replace(/\//g, "__")
-  );
-  const prefixLength = Math.max(1, PLAY_NAME_MAX_LENGTH - digest.length - 1);
-  const prefix = normalizedReference.slice(0, prefixLength).replace(/_+$/g, "") || "qualified_play";
-  return `${prefix}_${digest}`;
-}
-function normalizeTableNamespace(value) {
-  return validateIdentifierPart(
-    value,
-    "ctx.dataset() key",
-    MAP_KEY_NAMESPACE_MAX_LENGTH
-  );
-}
-function validatePlaySheetTableName(playName, tableNamespace) {
-  const playSegment = normalizePlayNameForSheet(playName);
-  const keySegment = normalizeTableNamespace(tableNamespace);
-  const resolved = `${playSegment}_${keySegment}`;
-  if (resolved.length > POSTGRES_IDENTIFIER_MAX_LENGTH) {
-    throw new Error(
-      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.dataset() key. Resolved table name: "${resolved}".`
-    );
-  }
-  return resolved;
-}
-
 // src/cli/trace.ts
 var cliTraceStartedAt = Date.now();
 function isTruthyEnv(value) {
@@ -7735,6 +7663,11 @@ async function traceCliSpan(phase, fields, run) {
 
 // src/cli/play-check-hints.ts
 var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific fields.";
+var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Use `.peek(n)` for a small preview or `.materialize()` when you intentionally need rows in memory; do not use `.rows`, `.toArray()`, or array methods directly on the dataset handle.";
+var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
+var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for replay-safe receipts.";
+var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or map-backed batch plays must be run directly, exported, then consumed by a separate play.";
+var MAP_BACKED_CHILD_HINT = "Deepline hint: map-backed child plays own durable table state and cannot be called from another play. Run that play directly, export its dataset, then pass the CSV to the next play.";
 function sourceLineForError(sourceCode, error) {
   const match = error.match(/:(\d+):(\d+)\s/);
   const lineNumber = match?.[1] ? Number(match[1]) : NaN;
@@ -7745,16 +7678,61 @@ function looksLikeInvalidExtractedGetter(error, sourceLine) {
   if (!/Property '[^']+' does not exist on type/.test(error)) return false;
   return /\bextracted(?:Values|Lists)\s*\./.test(sourceLine);
 }
+function looksLikeDatasetApiMisuse(error, sourceLine) {
+  return /Property '(?:rows|toArray|forEach|map|filter|reduce)' does not exist on type '[^']*PlayDataset/.test(
+    error
+  ) || /\b(?:\.rows|\.toArray\(\)|\.forEach\(|\.map\(|\.filter\(|\.reduce\()/.test(
+    sourceLine
+  );
+}
+function looksLikeRowPropertyMismatch(error, sourceLine) {
+  if (!/Property '[^']+' does not exist on type/.test(error)) return false;
+  if (looksLikeInvalidExtractedGetter(error, sourceLine)) return false;
+  return /\brow\.[A-Za-z_][A-Za-z0-9_]*/.test(sourceLine);
+}
+function looksLikeToolsExecuteSignature(error, sourceLine) {
+  return /ctx\.tools\.execute requires a request object/i.test(error) || /Expected 1 arguments?, but got [2-9]/.test(error) && /\btools\.execute\(/.test(sourceLine);
+}
+function looksLikeRunPlaySignature(error, sourceLine) {
+  return /ctx\.runPlay/i.test(error) || /(?:Expected|Argument of type|No overload matches)/.test(error) && /\brunPlay\(/.test(sourceLine);
+}
+function looksLikeMapBackedChild(error) {
+  return /map-backed child play|direct-run-only|cannot call a map-backed|own durable table/i.test(
+    error
+  );
+}
+function hintForError(error, sourceLine) {
+  if (looksLikeInvalidExtractedGetter(error, sourceLine)) {
+    return EXTRACTED_GETTER_ERROR_HINT;
+  }
+  if (looksLikeDatasetApiMisuse(error, sourceLine)) {
+    return DATASET_API_HINT;
+  }
+  if (looksLikeToolsExecuteSignature(error, sourceLine)) {
+    return TOOLS_EXECUTE_SIGNATURE_HINT;
+  }
+  if (looksLikeMapBackedChild(error)) {
+    return MAP_BACKED_CHILD_HINT;
+  }
+  if (looksLikeRunPlaySignature(error, sourceLine)) {
+    return RUN_PLAY_SIGNATURE_HINT;
+  }
+  if (looksLikeRowPropertyMismatch(error, sourceLine)) {
+    return ROW_PROPERTY_HINT;
+  }
+  return null;
+}
 function addPlayCheckRepairHints(input2) {
-  let addedHint = false;
+  const addedHints = /* @__PURE__ */ new Set();
   return input2.errors.map((error) => {
     const line = sourceLineForError(input2.sourceCode, error);
-    if (addedHint || !looksLikeInvalidExtractedGetter(error, line) || error.includes(EXTRACTED_GETTER_ERROR_HINT)) {
+    const hint = hintForError(error, line);
+    if (!hint || addedHints.has(hint) || error.includes(hint)) {
       return error;
     }
-    addedHint = true;
+    addedHints.add(hint);
     return `${error}
-${EXTRACTED_GETTER_ERROR_HINT}`;
+${hint}`;
   });
 }
 
@@ -7869,10 +7847,10 @@ function materializeRemotePlaySource(input2) {
     if (existingSource === input2.sourceCode) {
       return { path: outputPath, status: "unchanged", created: false };
     }
-    writeFileSync6(outputPath, input2.sourceCode, "utf-8");
+    writeFileSync7(outputPath, input2.sourceCode, "utf-8");
     return { path: outputPath, status: "updated", created: false };
   }
-  writeFileSync6(outputPath, input2.sourceCode, "utf-8");
+  writeFileSync7(outputPath, input2.sourceCode, "utf-8");
   return { path: outputPath, status: "created", created: true };
 }
 function formatLoadedPlayMessage(materializedFile) {
@@ -8311,8 +8289,6 @@ var TERMINAL_PLAY_STATUSES2 = /* @__PURE__ */ new Set([
   "cancelled"
 ]);
 var PLAY_START_TRANSIENT_RETRY_DELAYS_MS = [500, 1500];
-var PLAY_CUSTOMER_STORAGE_SCHEMA_NAME = "storage";
-var PLAY_INTERNAL_STEP_RECEIPT_TABLE = "_deepline_step_receipts";
 function getEventPayload(event) {
   return event.payload && typeof event.payload === "object" ? event.payload : {};
 }
@@ -8366,36 +8342,8 @@ function getLogLinesFromLiveEvent(event) {
   const lines = getEventPayload(event).lines;
   return Array.isArray(lines) ? lines.filter((line) => typeof line === "string") : [];
 }
-function quoteSqlIdentifier(identifier) {
-  return `"${identifier.replace(/"/g, '""')}"`;
-}
-function quoteSqlLiteral(value) {
-  return `'${value.replace(/'/g, "''")}'`;
-}
-function buildDebugDbQueryCommand(sql) {
-  return `deepline db query --sql ${shellSingleQuote(sql)} --max-rows 20 --json`;
-}
-function buildStepReceiptsDebugCommand(runId) {
-  const table = `${quoteSqlIdentifier(
-    PLAY_CUSTOMER_STORAGE_SCHEMA_NAME
-  )}.${quoteSqlIdentifier(PLAY_INTERNAL_STEP_RECEIPT_TABLE)}`;
-  const sql = `select convert_from(k, 'UTF8') as receipt_key, case status when 0 then 'pending' when 1 then 'running' when 2 then 'completed' when 3 then 'failed' when 4 then 'skipped' else status::text end as status, output, error, updated_at from ${table} where run_id = ${quoteSqlLiteral(runId)} order by updated_at asc, receipt_key asc limit 20`;
-  return buildDebugDbQueryCommand(sql);
-}
-function buildMapTableDebugCommand(input2) {
-  try {
-    const tableName = validatePlaySheetTableName(
-      input2.playName,
-      input2.tableNamespace
-    );
-    const table = `${quoteSqlIdentifier(
-      PLAY_CUSTOMER_STORAGE_SCHEMA_NAME
-    )}.${quoteSqlIdentifier(tableName)}`;
-    const sql = `select * from ${table} where _run_id = ${quoteSqlLiteral(input2.runId)} limit 20`;
-    return buildDebugDbQueryCommand(sql);
-  } catch {
-    return null;
-  }
+function buildRunInspectCommand(runId) {
+  return `deepline runs get ${runId} --full --json`;
 }
 function extractTableNamespaceFromLiveEvent(event) {
   const payload = getEventPayload(event);
@@ -8420,7 +8368,7 @@ function emitLiveDebugTableHints(input2) {
   if (!input2.state.emittedDebugKeys.has(receiptsKey)) {
     input2.state.emittedDebugKeys.add(receiptsKey);
     input2.progress.writeLine(
-      `Debug top-level outputs: ${buildStepReceiptsDebugCommand(input2.runId)}`,
+      `Inspect run output: ${buildRunInspectCommand(input2.runId)}`,
       process.stdout
     );
   }
@@ -8432,17 +8380,9 @@ function emitLiveDebugTableHints(input2) {
   if (input2.state.emittedDebugKeys.has(tableKey)) {
     return;
   }
-  const command = buildMapTableDebugCommand({
-    playName: input2.playName,
-    runId: input2.runId,
-    tableNamespace
-  });
-  if (!command) {
-    return;
-  }
   input2.state.emittedDebugKeys.add(tableKey);
   input2.progress.writeLine(
-    `Debug rows for ${tableNamespace}: ${command}`,
+    `Possible map table ${tableNamespace}: created only after this ctx.map(...).run(...) executes. Inspect returned datasets with ${buildRunInspectCommand(input2.runId)}`,
     process.stdout
   );
 }
@@ -8646,7 +8586,7 @@ async function waitForPlayCompletionByStream(input2) {
   }
   const phaseSuffix = lastPhase && lastPhase.trim() ? ` (last observed phase: ${lastPhase.trim()})` : "";
   throw new DeeplineError(
-    `Play live stream ended before the run reached a terminal state runId=${input2.workflowId}${phaseSuffix}.`,
+    `Play watch stream ended before the run reached a terminal status. runId=${input2.workflowId}${phaseSuffix}. Inspect the current run with 'deepline runs get ${input2.workflowId} --full --json' or continue watching with 'deepline runs tail ${input2.workflowId}'.`,
     void 0,
     "PLAY_LIVE_STREAM_ENDED",
     {
@@ -8807,7 +8747,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
       const reason = error instanceof Error ? error.message : String(error);
       if (!input2.jsonOutput) {
         process.stderr.write(
-          `[play watch] start stream failed after run ${lastKnownWorkflowId}; reconnecting to run stream (${reason})
+          `[play watch] start stream failed after run ${lastKnownWorkflowId}; reconnecting to canonical run stream (${reason})
 `
         );
       }
@@ -8844,7 +8784,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   if (lastKnownWorkflowId) {
     if (!input2.jsonOutput) {
       input2.progress.writeLine(
-        `[play watch] start stream ended after run ${lastKnownWorkflowId}; reconnecting to run stream`
+        `[play watch] start stream ended after run ${lastKnownWorkflowId}; reconnecting to canonical run stream`
       );
     }
     recordCliTrace({
@@ -8874,7 +8814,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   const phaseSuffix = lastPhase && lastPhase.trim() ? ` (last observed phase: ${lastPhase.trim()})` : "";
   const idSuffix = lastKnownWorkflowId ? ` runId=${lastKnownWorkflowId}` : "";
   throw new DeeplineError(
-    `Play start stream ended before the run reached a terminal state${idSuffix}${phaseSuffix}.`,
+    `Play start stream ended before a terminal status was observed${idSuffix}${phaseSuffix}. If a run id was printed, inspect it with 'deepline runs get <run-id> --full --json' or continue watching with 'deepline runs tail <run-id>'.`,
     void 0,
     "PLAY_START_STREAM_ENDED",
     {
@@ -9222,6 +9162,32 @@ function formatPlayErrorForDisplay(status, error) {
   }
   return error;
 }
+function isGenericInternalServerError(error) {
+  if (!error) return false;
+  return /^(?:internalservererror|internal server error|http 500|500)$/i.test(
+    error.trim()
+  );
+}
+function selectRunErrorForDisplay(status) {
+  const progressError = getStringField(status.progress, "error");
+  if (!isGenericInternalServerError(progressError)) {
+    return progressError;
+  }
+  const directErrors = getRecordField(status, "errors");
+  if (Array.isArray(directErrors)) {
+    for (const entry of directErrors) {
+      const message = getStringField(entry, "message");
+      if (message && !isGenericInternalServerError(message)) {
+        return message;
+      }
+    }
+  }
+  const directError = getStringField(status, "error");
+  if (directError && !isGenericInternalServerError(directError)) {
+    return directError;
+  }
+  return progressError;
+}
 function normalizeRunStatusForEnvelope(status) {
   const run = status.run ?? null;
   return {
@@ -9359,8 +9325,7 @@ function compactPlayStatus(status) {
   const billing = status && typeof status === "object" ? stripProviderSpendFromBilling(
     status.billing
   ) : null;
-  const progressError = status.progress?.error;
-  const error = typeof progressError === "string" ? progressError : typeof status.error === "string" ? String(status.error) : null;
+  const error = selectRunErrorForDisplay(status) ?? (typeof status.error === "string" ? String(status.error) : null);
   const displayError = formatPlayErrorForDisplay(status, error);
   return {
     runId: status.runId,
@@ -9615,8 +9580,8 @@ function writePlayResult(status, jsonOutput, options) {
   for (const warning of warnings) {
     lines.push(`  warning: ${warning}`);
   }
-  const progressError = status.progress?.error;
-  if (progressError && typeof progressError === "string") {
+  const progressError = selectRunErrorForDisplay(status);
+  if (progressError) {
     const billing = extractBillingForStatus(status, progressError);
     if (isInsufficientCreditsBilling(billing)) {
       lines.push(...buildInsufficientCreditsSummaryLines({ status, billing }));
@@ -9668,9 +9633,6 @@ var RUN_EXPORT_PAGE_SIZE = 5e3;
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function sqlStringLiteral(value) {
-  return `'${value.replace(/'/g, "''")}'`;
-}
 function runExportRetryCommand(runId, outPath, datasetPath) {
   return `deepline runs export ${runId}${datasetPath ? ` --dataset ${shellSingleQuote(datasetPath)}` : ""} --out ${shellSingleQuote(resolve10(outPath))}`;
 }
@@ -9689,26 +9651,6 @@ function extractRunPlayName(status) {
   }
   return null;
 }
-function normalizeCustomerDbIdentifier(value) {
-  return value.split("/").pop().replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
-}
-function buildCustomerDbQueryPlan(input2) {
-  const playName = extractRunPlayName(input2.status);
-  const tableNamespace = input2.rowsInfo.tableNamespace?.trim();
-  if (!playName || !tableNamespace || input2.rowsInfo.totalRows <= 0) {
-    return null;
-  }
-  const tableName = `${normalizeCustomerDbIdentifier(playName)}_${normalizeCustomerDbIdentifier(
-    tableNamespace
-  )}`;
-  const sql = `select * from "storage"."${tableName}" where _run_id = ${sqlStringLiteral(input2.status.runId)} limit ${input2.rowsInfo.totalRows}`;
-  const base = `deepline customer-db query --sql ${shellSingleQuote(sql)} --max-rows ${input2.rowsInfo.totalRows}`;
-  return {
-    sql,
-    json: `${base} --json`,
-    csv: `${base} --format csv --out ${shellSingleQuote(resolve10(input2.outPath))}`
-  };
-}
 function exportableSheetRow(row) {
   if (!row || typeof row !== "object" || Array.isArray(row)) {
     return null;
@@ -10055,8 +9997,12 @@ function renderServerResultView(value) {
       lines.push(
         `    ${String(table.tableNamespace ?? "table")}${lineLabel}: ${rowLabel}${details.join("  ")}`
       );
-      if (typeof table.queryDatasetCommand === "string") {
-        lines.push(`      inspect rows: ${table.queryDatasetCommand}`);
+      if (typeof table.queryDatasetCommand === "string" && typeof table.rowCount === "number" && table.rowCount > 0) {
+        lines.push(`      debug backing table: ${table.queryDatasetCommand}`);
+      } else if (typeof table.queryDatasetCommand === "string") {
+        lines.push(
+          "      no rows observed for this run; backing table is created only if this map ran"
+        );
       }
       if (table.debugHelp && typeof table.debugHelp === "object" && !Array.isArray(table.debugHelp)) {
         const debugHelp = table.debugHelp;
@@ -10402,9 +10348,51 @@ function printToolGetterHints(hints) {
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
-    const resolved = resolve10(options.target);
-    console.error(`File not found: ${resolved}`);
-    return 1;
+    const client2 = new DeeplineClient();
+    try {
+      await assertCanonicalNamedPlayReference(client2, options.target);
+      const play = await client2.describePlay(
+        parseReferencedPlayTarget2(options.target).playName,
+        { compact: true }
+      );
+      const result2 = {
+        valid: true,
+        target: options.target,
+        name: play.name,
+        reference: play.reference ?? options.target,
+        origin: play.origin ?? null,
+        ownerType: play.ownerType ?? null,
+        inputSchema: play.inputSchema ?? null,
+        outputSchema: play.outputSchema ?? null,
+        staticPipeline: play.staticPipeline ?? null,
+        note: "Named/prebuilt play contract is available. No run was started."
+      };
+      if (options.jsonOutput) {
+        process.stdout.write(`${JSON.stringify(result2)}
+`);
+      } else {
+        console.log(`\u2713 ${result2.reference} passed named play contract check`);
+        console.log("  no run started; no Deepline credits spent");
+        if (play.runCommand) console.log(`  run: ${play.runCommand}`);
+      }
+      return 0;
+    } catch (error) {
+      const resolved = resolve10(options.target);
+      const message = error instanceof Error && error.message ? error.message : `File not found: ${resolved}`;
+      if (options.jsonOutput) {
+        process.stdout.write(
+          `${JSON.stringify({
+            valid: false,
+            target: options.target,
+            errors: [message]
+          })}
+`
+        );
+      } else {
+        console.error(message);
+      }
+      return 1;
+    }
   }
   const absolutePlayPath = resolve10(options.target);
   const sourceCode = readFileSync6(absolutePlayPath, "utf-8");
@@ -10941,7 +10929,7 @@ async function handleRunLogs(args) {
   const status = await client.runs.get(runId);
   const logs = status.progress?.logs ?? [];
   if (outPath) {
-    writeFileSync6(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
+    writeFileSync7(outPath, `${logs.join("\n")}${logs.length > 0 ? "\n" : ""}`);
     printCommandEnvelope(
       {
         runId: status.runId,
@@ -11051,18 +11039,9 @@ async function handleRunExport(args) {
     datasetPath
   });
   const source = exportResult?.rowsInfo.source ?? datasetPath ?? null;
-  const queryPlan = exportResult && outPath ? buildCustomerDbQueryPlan({
-    status,
-    rowsInfo: exportResult.rowsInfo,
-    outPath
-  }) : null;
   const next = {
     ...buildRunNextCommands(status),
-    export: runExportRetryCommand(status.runId, outPath, datasetPath ?? source),
-    ...queryPlan ? {
-      queryJson: queryPlan.json,
-      queryCsv: queryPlan.csv
-    } : {}
+    export: runExportRetryCommand(status.runId, outPath, datasetPath ?? source)
   };
   const payload = {
     runId: status.runId,
@@ -11071,13 +11050,6 @@ async function handleRunExport(args) {
     source,
     rowCount: exportResult?.rowsInfo.totalRows ?? null,
     columns: exportResult?.rowsInfo.columns ?? [],
-    ...queryPlan ? {
-      query: {
-        sql: queryPlan.sql,
-        json: queryPlan.json,
-        csv: queryPlan.csv
-      }
-    } : {},
     ...metadataOutPath ? { metadata_path: metadataOutPath } : {},
     local: { csv_path: exportResult?.path ?? null },
     next,
@@ -11087,15 +11059,14 @@ async function handleRunExport(args) {
           title: "run export",
           lines: [
             `Exported ${status.runId} to ${exportResult?.path ?? outPath}`,
-            ...source ? [`source=${source}`] : [],
-            ...queryPlan ? [`query=${queryPlan.json}`] : []
+            ...source ? [`source=${source}`] : []
           ]
         }
       ]
     }
   };
   if (metadataOutPath) {
-    writeFileSync6(
+    writeFileSync7(
       metadataOutPath,
       `${JSON.stringify(payload, null, 2)}
 `,
@@ -11268,7 +11239,8 @@ function parsePlaySearchOptions(args) {
   return {
     query,
     jsonOutput: argsWantJson(args),
-    compact: args.includes("--compact")
+    compact: args.includes("--compact"),
+    prebuiltOnly: args.includes("--prebuilt")
   };
 }
 function printPlayDescription(play) {
@@ -11316,6 +11288,7 @@ function printPlayDescription(play) {
       console.log(`    ${line}`);
     }
   }
+  console.log(`  Describe: deepline plays describe ${reference} --json`);
   console.log(`  Run: ${play.runCommand}`);
   const cloneEditStarter = play.cloneEditStarter ?? buildCloneEditStarter(play);
   if (cloneEditStarter) {
@@ -11323,6 +11296,31 @@ function printPlayDescription(play) {
     console.log(`  Check starter: ${cloneEditStarter.checkCommand}`);
   }
 }
+function inputFieldNames(schema) {
+  const fields = Array.isArray(schema?.fields) ? schema.fields : [];
+  return fields.map(
+    (field) => field && typeof field === "object" ? String(field.name ?? "").trim() : ""
+  ).filter(Boolean);
+}
+function printCompactPlaySearchResult(play) {
+  const reference = formatPlayListReference(play);
+  const aliases = play.aliases.slice(0, 6).join(", ");
+  console.log(`Play: ${reference}`);
+  if (play.displayName && play.displayName !== play.name) {
+    console.log(`  Display name: ${play.displayName}`);
+  }
+  if (aliases) {
+    console.log(`  Aliases: ${aliases}`);
+  }
+  const fields = inputFieldNames(play.inputSchema);
+  if (fields.length > 0) {
+    console.log(`  Inputs: ${fields.join(", ")}`);
+  } else if (play.inputSchema) {
+    console.log("  Inputs: see describe");
+  }
+  console.log(`  Describe: deepline plays describe ${reference} --json`);
+  console.log(`  Run: ${play.runCommand}`);
+}
 function compactPlaySchema(schema) {
   if (!schema) return null;
   const fields = Array.isArray(schema.fields) ? schema.fields.map(
@@ -11386,22 +11384,44 @@ async function handlePlaySearch(args) {
     return 1;
   }
   const client = new DeeplineClient();
-  const plays = await client.searchPlays({
+  const plays = (await client.searchPlays({
     query: options.query,
     compact: options.compact
-  });
+  })).filter(
+    (play) => options.prebuiltOnly ? play.origin === "prebuilt" || play.ownerType === "deepline" : true
+  );
   if (options.jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ plays })}
-`);
+    const jsonPlays = options.prebuiltOnly ? plays.map((play) => ({
+      ...play,
+      inputSchema: compactPlaySchema(play.inputSchema)
+    })) : plays;
+    process.stdout.write(
+      `${JSON.stringify({
+        plays: jsonPlays,
+        total: jsonPlays.length,
+        truncated: false
+      })}
+`
+    );
     return 0;
   }
-  process.stdout.write(`${plays.length} plays found:
+  const displayPlays = options.prebuiltOnly ? plays.slice(0, 5) : plays;
+  process.stdout.write(
+    `${plays.length} plays found${options.prebuiltOnly && plays.length > displayPlays.length ? `; showing top ${displayPlays.length}` : ""}:
 
-`);
-  for (const play of plays) {
-    printPlayDescription(play);
+`
+  );
+  for (const play of displayPlays) {
+    if (options.prebuiltOnly) {
+      printCompactPlaySearchResult(play);
+    } else {
+      printPlayDescription(play);
+    }
     console.log("");
   }
+  if (options.prebuiltOnly && plays.length > displayPlays.length) {
+    console.log("Use --json for the full machine-readable result set.");
+  }
   return 0;
 }
 function normalizePlayGrepText(value) {
@@ -11668,15 +11688,18 @@ Common commands:
   deepline plays get person-linkedin-to-email --json
 `
   );
-  play.command("check <target>").description("Bundle-check a local play file.").addHelpText(
+  play.command("check <target>").description("Check a local play file or named/prebuilt play contract.").addHelpText(
     "after",
     `
 Notes:
   Validates a local play without storing it, promoting it, or starting a run.
   This uses the authoritative cloud preflight path.
+  For named or prebuilt plays, validates that the contract is discoverable
+  without starting a run or spending Deepline credits.
 
 Examples:
   deepline plays check my.play.ts
+  deepline plays check prebuilt/name-and-domain-to-email-waterfall-batch
   deepline plays check my.play.ts --json
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
@@ -11826,11 +11849,13 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  const addPlaySearchCommand = (command) => command.description("Search saved and prebuilt plays.").addHelpText(
+  const addPlaySearchCommand = (command) => command.description("Search saved and prebuilt plays.").option("--prebuilt", "Only show Deepline-managed prebuilt plays").addHelpText(
     "after",
     `
 Notes:
   Ranked discovery for workflows. Use describe on a result before running it.
+  Prefer --prebuilt for new GTM tasks so old workspace scratchpads do not
+  outrank Deepline-managed routes unless the user names one explicitly.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering the play registry.
 
@@ -11842,6 +11867,7 @@ Examples:
   ).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.prebuilt ? ["--prebuilt"] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.json ? ["--json"] : []
     ]);
@@ -12089,7 +12115,7 @@ Notes:
   Writes a returned dataset handle to the requested local CSV path. Use runs get
   first to inspect dataset paths like result.rows or result.nested.contacts.
   --metadata-out writes the same export metadata object returned by --json,
-  including source and follow-on customer-db query commands when available.
+  including the source dataset path and row/column metadata.
 
 Examples:
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
@@ -13796,12 +13822,12 @@ Examples:
 
 // src/cli/commands/tools.ts
 import { Option } from "commander";
-import { chmodSync, mkdtempSync, writeFileSync as writeFileSync8 } from "fs";
+import { chmodSync, mkdtempSync, writeFileSync as writeFileSync9 } from "fs";
 import { tmpdir as tmpdir4 } from "os";
 import { join as join10 } from "path";
 
 // src/tool-output.ts
-import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync7 } from "fs";
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join9 } from "path";
 function isPlainObject(value) {
@@ -13906,7 +13932,7 @@ function ensureOutputDir() {
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
   const outputPath = join9(outputDir, `${stem}_${Date.now()}.json`);
-  writeFileSync7(outputPath, JSON.stringify(payload, null, 2), "utf-8");
+  writeFileSync8(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem) {
@@ -13934,7 +13960,7 @@ function writeCsvOutputFile(rows, stem) {
   for (const row of rows) {
     lines.push(columns.map((column) => escapeCell(row[column])).join(","));
   }
-  writeFileSync7(outputPath, `${lines.join("\n")}
+  writeFileSync8(outputPath, `${lines.join("\n")}
 `, "utf-8");
   const previewRows = rows.slice(0, 5);
   const previewColumns = columns.slice(0, 5);
@@ -14020,7 +14046,7 @@ async function listTools(args) {
   const client = new DeeplineClient();
   const categoryArgIndex = args.findIndex((arg) => arg === "--categories");
   const categoryFilter = categoryArgIndex >= 0 ? args[categoryArgIndex + 1] : "";
-  const compact = args.includes("--compact");
+  const compact = args.includes("--compact") || !args.includes("--json");
   const requestedCategories = categoryFilter ? categoryFilter.split(",").map((item) => item.trim()).filter(Boolean) : [];
   const items = (await client.listTools({
     ...categoryFilter ? { categories: categoryFilter } : {}
@@ -14076,9 +14102,10 @@ async function searchTools(queryInput, options = {}) {
     searchMode: options.searchMode,
     includeSearchDebug: options.includeSearchDebug
   });
-  const payload = options.compact && Array.isArray(result.tools) ? {
+  const shouldCompact = options.compact || !options.json;
+  const payload = shouldCompact && Array.isArray(result.tools) ? {
     ...result,
-    tools: result.tools.map(compactTool)
+    tools: result.tools.slice(0, 8).map(compactTool)
   } : result;
   printCommandEnvelope(payload, {
     json: options.json || shouldEmitJson()
@@ -14119,7 +14146,8 @@ async function grepTools(queryInput, options = {}) {
       mode
     )
   );
-  const outputTools = options.compact ? tools.map(compactTool) : tools;
+  const shouldCompact = options.compact || !options.json;
+  const outputTools = shouldCompact ? tools.slice(0, 8).map(compactTool) : tools;
   printCommandEnvelope(
     {
       tools: outputTools,
@@ -14138,11 +14166,19 @@ async function grepTools(queryInput, options = {}) {
   );
   return 0;
 }
+function numericToolField(tool, field) {
+  const value = tool[field];
+  return typeof value === "number" ? value : void 0;
+}
 function compactTool(tool) {
   const listed = toListedTool(tool);
+  const searchScore = numericToolField(tool, "searchScore");
+  const search_score = numericToolField(tool, "search_score");
   return {
     id: listed.id,
     toolId: listed.toolId,
+    ...search_score !== void 0 ? { search_score } : {},
+    ...searchScore !== void 0 ? { searchScore } : {},
     provider: listed.provider,
     displayName: listed.displayName,
     description: listed.description,
@@ -14463,7 +14499,7 @@ async function getTool(toolId, options = {}) {
   }
   if (shouldEmitJson()) {
     process.stdout.write(
-      `${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
+      `${JSON.stringify(toolContractJsonForDescribe(tool, toolId))}
 `
     );
     return 0;
@@ -14788,8 +14824,8 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: `deepline tools execute ${toolId} --input '{...}' --json`,
       observedOutput: `deepline tools execute ${toolId} --input '{...}' --json`,
-      forPlayGetterBugs: "Run the play, then inspect the emitted table commands from runs get. Use deepline db query against the run tables before editing getters.",
-      executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run tables."
+      forPlayGetterBugs: "Run a tiny play, inspect `deepline runs get <run-id> --full --json`, and export returned dataset handles with `deepline runs export`. Backing tables exist only for ctx.map(...).run(...) stages that actually executed.",
+      executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run output and returned dataset handles."
     },
     starterScript: {
       path: starterScript.path,
@@ -15040,7 +15076,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   };
 });
 `;
-  writeFileSync8(scriptPath, script, { encoding: "utf-8", mode: 384 });
+  writeFileSync9(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
     sourceCode: script,
@@ -15596,7 +15632,7 @@ import {
   readdirSync as readdirSync2,
   readFileSync as readFileSync7,
   statSync as statSync2,
-  writeFileSync as writeFileSync9
+  writeFileSync as writeFileSync10
 } from "fs";
 import { homedir as homedir6 } from "os";
 import { dirname as dirname10, join as join12 } from "path";
@@ -15630,7 +15666,7 @@ function readLocalSkillsVersion(baseUrl) {
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
   mkdirSync5(dirname10(path), { recursive: true });
-  writeFileSync9(path, `${version}
+  writeFileSync10(path, `${version}
 `, "utf-8");
 }
 function installedSdkSkillHasStalePositionalExecuteExamples() {
@@ -15813,6 +15849,7 @@ async function syncSdkSkillsIfNeeded(baseUrl) {
 }
 
 // src/cli/index.ts
+var PREFLIGHT_TIMEOUT_MS = 3e3;
 function asCommanderError(error) {
   if (!(error instanceof Error) || !("code" in error)) {
     return null;
@@ -15893,6 +15930,124 @@ async function runPlayRunnerHealthCheck() {
     await rm2(dir, { recursive: true, force: true });
   }
 }
+function pickString(value, ...keys) {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function preflightErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runPreflightCheck() {
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  const healthController = new AbortController();
+  const healthTimeout = setTimeout(
+    () => healthController.abort(),
+    PREFLIGHT_TIMEOUT_MS
+  );
+  const health = await fetch(new URL("/api/v2/health", baseUrl), {
+    signal: healthController.signal
+  }).then(async (response) => {
+    const payload = await response.json().catch(() => ({}));
+    return {
+      status: response.ok ? pickString(payload, "status") ?? "ok" : "unreachable",
+      version: pickString(payload, "version")
+    };
+  }).catch(() => ({ status: "unreachable", version: null })).finally(() => clearTimeout(healthTimeout));
+  const apiKey = resolveApiKeyForBaseUrl(baseUrl);
+  const http = apiKey ? new HttpClient(
+    resolveConfig({
+      baseUrl,
+      apiKey,
+      timeout: PREFLIGHT_TIMEOUT_MS,
+      maxRetries: 0
+    })
+  ) : null;
+  const [auth, billing] = http ? await Promise.all([
+    http.post("/api/v2/auth/cli/status", {
+      api_key: apiKey,
+      reveal: false
+    }).catch((error) => ({
+      status: "not_connected",
+      connected: false,
+      error: preflightErrorMessage(error)
+    })),
+    http.get("/api/v2/billing/balance").catch(
+      (error) => ({
+        balance: null,
+        balance_display: "unavailable",
+        balance_status: "unknown",
+        error: preflightErrorMessage(error)
+      })
+    )
+  ]) : [
+    {
+      status: "not_connected",
+      connected: false,
+      error: "No API key found. Run: deepline auth register"
+    },
+    {
+      balance: null,
+      balance_display: "unavailable until authenticated",
+      balance_status: "unknown"
+    }
+  ];
+  const authStatus = pickString(auth, "status") ?? "unknown";
+  const billingRecord = billing;
+  const balanceDisplay = pickString(billing, "balance_display", "balanceDisplay") ?? `${String(billingRecord.balance ?? 0)} Deepline Credits`;
+  const balanceStatus = pickString(billing, "balance_status", "balanceStatus") ?? "unknown";
+  return {
+    status: health.status === "ok" && (authStatus === "connected" || authStatus === "claimed") ? "ok" : "check",
+    host: baseUrl,
+    health: {
+      status: health.status,
+      version: health.version ?? null
+    },
+    auth: {
+      status: authStatus,
+      connected: authStatus === "connected" || authStatus === "claimed",
+      org_id: pickString(auth, "org_id", "orgId"),
+      org_name: pickString(auth, "org_name", "orgName"),
+      rate_limit_tier: pickString(auth, "rate_limit_tier", "rateLimitTier"),
+      error: pickString(auth, "error")
+    },
+    billing: {
+      balance: billingRecord.balance ?? null,
+      balance_display: balanceDisplay,
+      rough_usd_balance: billingRecord.rough_usd_balance ?? billingRecord.roughUsdBalance ?? null,
+      balance_status: balanceStatus,
+      error: pickString(billing, "error")
+    },
+    render: {
+      sections: [
+        {
+          title: "preflight",
+          lines: [
+            `host: ${baseUrl}`,
+            `health: ${health.status}`,
+            `auth: ${authStatus}`,
+            `billing: ${balanceDisplay} (${balanceStatus})`
+          ]
+        }
+      ]
+    }
+  };
+}
+function printPreflightHuman(data) {
+  const render = data.render;
+  const lines = render?.sections?.flatMap((section) => section.lines ?? []);
+  if (lines?.length) {
+    process.stdout.write(`${lines.join("\n")}
+`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+}
 async function main() {
   const mainStartedAt = Date.now();
   recordCliTrace({
@@ -15909,6 +16064,7 @@ async function main() {
     "after",
     `
 Common commands:
+  deepline preflight
   deepline health
   deepline auth status --json
   deepline plays search email --json
@@ -15930,7 +16086,6 @@ Output:
 
 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;
@@ -15972,6 +16127,26 @@ Exit codes:
   registerDbCommands(program);
   registerFeedbackCommands(program);
   registerUpdateCommand(program);
+  program.command("preflight").description("Run compact health, auth, and Deepline billing checks.").option("--json", "Force JSON output.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only setup check for the configured Deepline host. Shows server health,
+  auth connection, and customer-visible Deepline balance in one compact command.
+
+Examples:
+  deepline preflight
+  deepline preflight --json
+`
+  ).action(async (options) => {
+    const data = await runPreflightCheck();
+    if (shouldEmitJson(options.json)) {
+      process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    } else {
+      printPreflightHuman(data);
+    }
+  });
   program.command("health").description("Check server health.").option("--json", "Force JSON output.").option(
     "--play-runner",
     "Run a tiny no-provider play to verify the full play execution plane."