deepline 0.1.54 → 0.1.56

package/dist/cli/index.js

@@ -220,10 +220,10 @@ function resolveConfig(options) {
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.54",
-  apiContract: "2026-05-run-response-package",
+  version: "0.1.56",
+  apiContract: "2026-05-play-tool-describe-starters",
   supportPolicy: {
-    latest: "0.1.54",
+    latest: "0.1.56",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -727,6 +727,23 @@ var DeeplineClient = class {
     }
     return `deepline plays run ${target} --input '{...}' --watch`;
   }
+  starterPlayPath(play) {
+    const target = play.reference || play.name;
+    const unqualifiedName = target.split("/").pop() || play.name;
+    const safeName = unqualifiedName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    return `./${safeName || "play"}.play.ts`;
+  }
+  playCloneEditStarter(play) {
+    const readonlyPrebuilt = (play.origin === "prebuilt" || play.ownerType === "deepline") && !play.canEdit;
+    if (!play.canClone && !readonlyPrebuilt) return void 0;
+    const target = play.reference || play.name;
+    const path = this.starterPlayPath(play);
+    return {
+      path,
+      command: `deepline plays get ${target} --source --out ${path}`,
+      checkCommand: `deepline plays check ${path}`
+    };
+  }
   summarizePlayListItem(play, options) {
     const aliases = play.aliases?.length ? play.aliases : [play.name];
     const csvInput = this.schemaMetadata(play.inputSchema, "csvInput");
@@ -735,6 +752,7 @@ var DeeplineClient = class {
       "rowOutputSchema"
     );
     const runCommand2 = this.playRunCommand(play, { csvInput });
+    const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
@@ -750,6 +768,7 @@ var DeeplineClient = class {
       ...rowOutputSchema ? { rowOutputSchema } : {},
       runCommand: runCommand2,
       examples: [runCommand2],
+      ...cloneEditStarter ? { cloneEditStarter } : {},
       currentPublishedVersion: play.currentPublishedVersion ?? null,
       isDraftDirty: play.isDraftDirty
     };
@@ -1452,7 +1471,6 @@ var DeeplineClient = class {
   async searchPlays(options) {
     const params = new URLSearchParams();
     params.set("search", options.query.trim());
-    if (options.origin) params.set("origin", options.origin);
     const response = await this.http.get(
       `/api/v2/plays?${params.toString()}`
     );
@@ -4085,11 +4103,23 @@ var PLAY_ARTIFACT_CACHE_DIR = (0, import_node_path7.join)(
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
 );
 var PLAY_PROXY_NAMESPACE = "deepline-play-runtime-ref";
-var SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+var SOURCE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json"
+];
 var WORKERS_PLAY_ENTRY_VIRTUAL = "deepline-play-entry";
 var PLAY_SOURCE_FILE_PATTERN = /\.play\.(?:[cm]?[jt]sx?)$/i;
 var NODE_BUILTIN_SET = new Set(
-  import_node_module.builtinModules.flatMap((name) => name.startsWith("node:") ? [name, name.slice(5)] : [name, `node:${name}`])
+  import_node_module.builtinModules.flatMap(
+    (name) => name.startsWith("node:") ? [name, name.slice(5)] : [name, `node:${name}`]
+  )
 );
 function assertValidExportName(exportName) {
   if (exportName === "default") return;
@@ -4169,15 +4199,27 @@ function findSourceImportReferences(sourceCode) {
   };
   const staticImportPattern = /\b(?:import|export)\s+(?!type\b)(?:[\s\S]*?\s+from\s*)?(['"])([^'"\n]+)\1/g;
   for (const match of source.matchAll(staticImportPattern)) {
-    addReference(match[2], match.index + match[0].lastIndexOf(match[1]), "static");
+    addReference(
+      match[2],
+      match.index + match[0].lastIndexOf(match[1]),
+      "static"
+    );
   }
   const dynamicImportPattern = /\bimport\s*\(\s*(['"])([^'"\n]+)\1/g;
   for (const match of source.matchAll(dynamicImportPattern)) {
-    addReference(match[2], match.index + match[0].lastIndexOf(match[1]), "dynamic-import");
+    addReference(
+      match[2],
+      match.index + match[0].lastIndexOf(match[1]),
+      "dynamic-import"
+    );
   }
   const requirePattern = /\brequire\s*\(\s*(['"])([^'"\n]+)\1/g;
   for (const match of source.matchAll(requirePattern)) {
-    addReference(match[2], match.index + match[0].lastIndexOf(match[1]), "require");
+    addReference(
+      match[2],
+      match.index + match[0].lastIndexOf(match[1]),
+      "require"
+    );
   }
   const literalDynamicImportIndexes = new Set(
     [...source.matchAll(dynamicImportPattern)].map((match) => match.index)
@@ -4210,7 +4252,9 @@ function unquoteStringLiteral(literal) {
     return null;
   }
   try {
-    return JSON.parse(quote === '"' ? trimmed : `"${trimmed.slice(1, -1).replace(/"/g, '\\"')}"`);
+    return JSON.parse(
+      quote === '"' ? trimmed : `"${trimmed.slice(1, -1).replace(/"/g, '\\"')}"`
+    );
   } catch {
     return trimmed.slice(1, -1);
   }
@@ -4262,7 +4306,9 @@ function extractDefinedPlayName(sourceCode) {
       const closeBrace = findMatchingBrace(source, argIndex);
       if (closeBrace < 0) continue;
       const objectSource = source.slice(argIndex + 1, closeBrace);
-      const idMatch = objectSource.match(/(?:^|[,{\s])(?:id|['"]id['"])\s*:\s*(['"])([\s\S]*?)\1/);
+      const idMatch = objectSource.match(
+        /(?:^|[,{\s])(?:id|['"]id['"])\s*:\s*(['"])([\s\S]*?)\1/
+      );
       if (idMatch?.[2]?.trim()) {
         return idMatch[2].trim();
       }
@@ -4371,7 +4417,12 @@ function workersNamedPlayEntryAliasPlugin(playFilePath, exportName) {
   };
 }
 function workersNodeBuiltinStubPlugin() {
-  const UNSUPPORTED = /* @__PURE__ */ new Set(["node:fs", "node:fs/promises", "node:os", "node:child_process"]);
+  const UNSUPPORTED = /* @__PURE__ */ new Set([
+    "node:fs",
+    "node:fs/promises",
+    "node:os",
+    "node:child_process"
+  ]);
   return {
     name: "deepline-workers-node-builtin-stub",
     setup(buildContext) {
@@ -4420,16 +4471,13 @@ function zodNonEnglishLocaleStubPlugin() {
         }
         return { path: args.path, namespace: NAMESPACE };
       });
-      buildContext.onLoad(
-        { filter: /.*/, namespace: NAMESPACE },
-        () => ({
-          // zod locales export a default object literal. Empty object is
-          // structurally compatible — accessing any locale key returns
-          // undefined and zod falls back to its built-in English.
-          contents: "export default {};",
-          loader: "js"
-        })
-      );
+      buildContext.onLoad({ filter: /.*/, namespace: NAMESPACE }, () => ({
+        // zod locales export a default object literal. Empty object is
+        // structurally compatible — accessing any locale key returns
+        // undefined and zod falls back to its built-in English.
+        contents: "export default {};",
+        loader: "js"
+      }));
     }
   };
 }
@@ -4500,7 +4548,10 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
     return null;
   }
   const dependenciesByPath = new Map(
-    importedPlayDependencies.map((dependency) => [dependency.filePath, dependency])
+    importedPlayDependencies.map((dependency) => [
+      dependency.filePath,
+      dependency
+    ])
   );
   return {
     name: "deepline-imported-play-proxy",
@@ -4520,17 +4571,20 @@ function importedPlayProxyPlugin(importedPlayDependencies) {
           pluginData: dependency
         };
       });
-      buildContext.onLoad({ filter: /.*/, namespace: PLAY_PROXY_NAMESPACE }, async (args) => {
-        const dependency = args.pluginData ?? dependenciesByPath.get(args.path);
-        if (!dependency) {
-          return null;
+      buildContext.onLoad(
+        { filter: /.*/, namespace: PLAY_PROXY_NAMESPACE },
+        async (args) => {
+          const dependency = args.pluginData ?? dependenciesByPath.get(args.path);
+          if (!dependency) {
+            return null;
+          }
+          return {
+            contents: buildImportedPlayProxyModule(dependency.playName),
+            loader: "ts",
+            resolveDir: (0, import_node_path7.dirname)(args.path)
+          };
         }
-        return {
-          contents: buildImportedPlayProxyModule(dependency.playName),
-          loader: "ts",
-          resolveDir: (0, import_node_path7.dirname)(args.path)
-        };
-      });
+      );
     }
   };
 }
@@ -4550,18 +4604,26 @@ async function resolveLocalImport(fromFile, specifier) {
   const candidates = [base];
   const explicitExtension = (0, import_node_path7.extname)(base).toLowerCase();
   if (!explicitExtension) {
-    candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`));
-    candidates.push(...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path7.join)(base, `index${extension}`)));
+    candidates.push(
+      ...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`)
+    );
+    candidates.push(
+      ...SOURCE_EXTENSIONS.map((extension) => (0, import_node_path7.join)(base, `index${extension}`))
+    );
   } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(explicitExtension)) {
     const stem = base.slice(0, -explicitExtension.length);
-    candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stem}${extension}`));
+    candidates.push(
+      ...SOURCE_EXTENSIONS.map((extension) => `${stem}${extension}`)
+    );
   }
   for (const candidate of candidates) {
     if (await fileExists(candidate)) {
       return normalizeLocalPath(candidate);
     }
   }
-  throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
+  throw new Error(
+    `Could not resolve local import "${specifier}" from ${fromFile}`
+  );
 }
 function resolvePackageImport(specifier, fromFile, adapter) {
   const packageName = getPackageName(specifier);
@@ -4609,7 +4671,9 @@ async function analyzeSourceGraph(entryFile, adapter) {
         );
       }
       if (NODE_BUILTIN_SET.has(specifier)) {
-        nodeBuiltins.add(specifier.startsWith("node:") ? specifier : `node:${specifier}`);
+        nodeBuiltins.add(
+          specifier.startsWith("node:") ? specifier : `node:${specifier}`
+        );
         return;
       }
       if (isLocalSpecifier(specifier)) {
@@ -4644,7 +4708,11 @@ async function analyzeSourceGraph(entryFile, adapter) {
           `${absolutePath}:${line}:${column} Unsupported import specifier "${specifier}". Allowed imports are relative files, Node builtins, and installed packages.`
         );
       }
-      const packageImport = resolvePackageImport(specifier, absolutePath, adapter);
+      const packageImport = resolvePackageImport(
+        specifier,
+        absolutePath,
+        adapter
+      );
       packages.set(packageImport.name, packageImport.version);
     };
     try {
@@ -4694,16 +4762,23 @@ async function analyzeSourceGraph(entryFile, adapter) {
       packages: [...packages.entries()].map(([name, version]) => ({ name, version })).sort((left, right) => left.name.localeCompare(right.name))
     },
     playName,
-    importedPlayDependencies: [...importedPlayDependencies.values()].sort((left, right) => left.filePath.localeCompare(right.filePath))
+    importedPlayDependencies: [...importedPlayDependencies.values()].sort(
+      (left, right) => left.filePath.localeCompare(right.filePath)
+    )
   };
 }
 async function computeWorkersHarnessFingerprintWithAdapter(adapter) {
   const { readdir } = await import("fs/promises");
-  const entries = await readdir(adapter.workersHarnessFilesDir, { withFileTypes: true });
+  const entries = await readdir(adapter.workersHarnessFilesDir, {
+    withFileTypes: true
+  });
   const tsFiles = entries.filter((e) => e.isFile() && /\.[cm]?ts$/.test(e.name)).map((e) => e.name).sort();
   const parts = [];
   for (const name of tsFiles) {
-    const contents = await (0, import_promises3.readFile)((0, import_node_path7.join)(adapter.workersHarnessFilesDir, name), "utf-8");
+    const contents = await (0, import_promises3.readFile)(
+      (0, import_node_path7.join)(adapter.workersHarnessFilesDir, name),
+      "utf-8"
+    );
     parts.push({ name, hash: sha256(contents) });
   }
   return sha256(JSON.stringify(parts));
@@ -4879,9 +4954,47 @@ async function runEsbuildForEsmWorkers(playEntryFile, importedPlayDependencies,
     outputExtension: "mjs"
   };
 }
+var PLAY_ARTIFACT_TARGET_ADAPTERS = {
+  [PLAY_ARTIFACT_KINDS.cjsNode20]: {
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
+    codeFormat: "cjs_module",
+    includeWorkersHarnessInGraphHash: false,
+    runEsbuild: ({
+      entryFile,
+      importedPlayDependencies,
+      adapter,
+      exportName
+    }) => runEsbuildForCjsNode(
+      entryFile,
+      importedPlayDependencies,
+      adapter,
+      exportName
+    )
+  },
+  [PLAY_ARTIFACT_KINDS.esmWorkers]: {
+    artifactKind: PLAY_ARTIFACT_KINDS.esmWorkers,
+    codeFormat: "esm_module",
+    includeWorkersHarnessInGraphHash: true,
+    runEsbuild: ({
+      entryFile,
+      importedPlayDependencies,
+      adapter,
+      exportName
+    }) => runEsbuildForEsmWorkers(
+      entryFile,
+      importedPlayDependencies,
+      adapter,
+      exportName
+    )
+  }
+};
+function resolvePlayArtifactTargetAdapter(artifactKind) {
+  return PLAY_ARTIFACT_TARGET_ADAPTERS[artifactKind];
+}
 async function bundlePlayFile(filePath, options) {
   const adapter = options.adapter;
   const target = options.target ?? PLAY_ARTIFACT_KINDS.cjsNode20;
+  const targetAdapter = resolvePlayArtifactTargetAdapter(target);
   const exportName = options.exportName?.trim() || "default";
   assertValidExportName(exportName);
   const absolutePath = await normalizeLocalPath(filePath);
@@ -4892,7 +5005,7 @@ async function bundlePlayFile(filePath, options) {
       `${analysis.graphHash}
 entry-export:${exportName}`
     );
-    if (target === PLAY_ARTIFACT_KINDS.esmWorkers) {
+    if (targetAdapter.includeWorkersHarnessInGraphHash) {
       const harnessFingerprint = await computeWorkersHarnessFingerprintWithAdapter(adapter);
       analysis.graphHash = sha256(
         `${analysis.graphHash}
@@ -4905,7 +5018,9 @@ workers-harness:${harnessFingerprint}`
         sourcePath: absolutePath,
         importedFilePaths: [
           ...analysis.importPolicy.localFiles,
-          ...analysis.importedPlayDependencies.map((dependency) => dependency.filePath)
+          ...analysis.importedPlayDependencies.map(
+            (dependency) => dependency.filePath
+          )
         ]
       }) ?? []
     ];
@@ -4916,7 +5031,11 @@ workers-harness:${harnessFingerprint}`
         errors: typecheckErrors
       };
     }
-    const cachedArtifact = await readArtifactCache(analysis.graphHash, target, adapter);
+    const cachedArtifact = await readArtifactCache(
+      analysis.graphHash,
+      target,
+      adapter
+    );
     const discoveredFiles = await adapter.discoverPackagedLocalFiles(absolutePath);
     if (cachedArtifact) {
       const cachedArtifactSizeError = getBundleSizeError(
@@ -4943,7 +5062,12 @@ workers-harness:${harnessFingerprint}`
         importedPlayDependencies: analysis.importedPlayDependencies
       };
     }
-    const buildOutcome = target === PLAY_ARTIFACT_KINDS.esmWorkers ? await runEsbuildForEsmWorkers(absolutePath, analysis.importedPlayDependencies, adapter, exportName) : await runEsbuildForCjsNode(absolutePath, analysis.importedPlayDependencies, adapter, exportName);
+    const buildOutcome = await targetAdapter.runEsbuild({
+      entryFile: absolutePath,
+      importedPlayDependencies: analysis.importedPlayDependencies,
+      adapter,
+      exportName
+    });
     if (Array.isArray(buildOutcome)) {
       return {
         success: false,
@@ -4970,9 +5094,8 @@ workers-harness:${harnessFingerprint}`
         errors: [bundleSizeError]
       };
     }
-    const codeFormat = target === PLAY_ARTIFACT_KINDS.esmWorkers ? "esm_module" : "cjs_module";
     const artifact = {
-      codeFormat,
+      codeFormat: targetAdapter.codeFormat,
       artifactKind: target,
       entryFile: absolutePath,
       virtualFilename,
@@ -5016,6 +5139,13 @@ workers-harness:${harnessFingerprint}`
   }
 }
 
+// ../shared_libs/play-runtime/dedup-backend.ts
+var PLAY_DEDUP_BACKENDS = {
+  inMemory: "in_memory",
+  neonTable: "neon_table",
+  durableObject: "durable_object"
+};
+
 // ../shared_libs/play-runtime/scheduler-backend.ts
 var PLAY_SCHEDULER_BACKENDS = {
   temporal: "temporal",
@@ -5023,44 +5153,65 @@ var PLAY_SCHEDULER_BACKENDS = {
   inProcess: "in-process"
 };
 
-// ../shared_libs/play-runtime/dedup-backend.ts
-var PLAY_DEDUP_BACKENDS = {
-  inMemory: "in_memory",
-  neonTable: "neon_table",
-  durableObject: "durable_object"
+// ../shared_libs/play-runtime/providers.ts
+var PLAY_RUNTIME_PROVIDER_IDS = {
+  workersEdge: "workers_edge",
+  local: "local"
 };
-
-// ../shared_libs/play-runtime/profiles.ts
-var PLAY_EXECUTION_PROFILES = {
+var PLAY_RUNTIME_PROVIDERS = {
   workers_edge: {
-    id: "workers_edge",
+    id: PLAY_RUNTIME_PROVIDER_IDS.workersEdge,
     scheduler: PLAY_SCHEDULER_BACKENDS.cfWorkflows,
     runner: PLAY_RUNTIME_BACKENDS.cloudflareWorkers,
     dedup: PLAY_DEDUP_BACKENDS.durableObject,
+    artifactKind: PLAY_ARTIFACT_KINDS.esmWorkers,
     label: "Cloudflare Dynamic Workflows + Dynamic Workers + DO dedup"
   },
   local: {
-    id: "local",
+    id: PLAY_RUNTIME_PROVIDER_IDS.local,
     scheduler: PLAY_SCHEDULER_BACKENDS.temporal,
     runner: PLAY_RUNTIME_BACKENDS.localProcess,
     dedup: PLAY_DEDUP_BACKENDS.inMemory,
+    artifactKind: PLAY_ARTIFACT_KINDS.cjsNode20,
     label: "Local Temporal scheduler + local subprocess runner (tests)"
   }
 };
-function defaultExecutionProfile() {
-  return PLAY_EXECUTION_PROFILES.workers_edge;
+function defaultPlayRuntimeProvider() {
+  return PLAY_RUNTIME_PROVIDERS.workers_edge;
 }
-function resolveExecutionProfile(override) {
+function resolvePlayRuntimeProvider(override) {
   if (override?.trim()) {
     const id = override.trim();
-    if (id in PLAY_EXECUTION_PROFILES) {
-      return PLAY_EXECUTION_PROFILES[id];
+    if (id in PLAY_RUNTIME_PROVIDERS) {
+      return PLAY_RUNTIME_PROVIDERS[id];
     }
     throw new Error(
-      `Unknown execution profile "${id}". Expected one of: ${Object.keys(PLAY_EXECUTION_PROFILES).join(", ")}.`
+      `Unknown play runtime provider "${id}". Expected one of: ${Object.keys(
+        PLAY_RUNTIME_PROVIDERS
+      ).join(", ")}.`
     );
   }
-  return defaultExecutionProfile();
+  return defaultPlayRuntimeProvider();
+}
+
+// ../shared_libs/play-runtime/profiles.ts
+var PLAY_EXECUTION_PROFILE_IDS = {
+  ...PLAY_RUNTIME_PROVIDER_IDS
+};
+var PLAY_EXECUTION_PROFILES = PLAY_RUNTIME_PROVIDERS;
+function resolveExecutionProfile(override) {
+  try {
+    return resolvePlayRuntimeProvider(override);
+  } catch (error) {
+    if (override?.trim()) {
+      throw new Error(
+        `Unknown execution profile "${override.trim()}". Expected one of: ${Object.keys(
+          PLAY_EXECUTION_PROFILES
+        ).join(", ")}.`
+      );
+    }
+    throw error;
+  }
 }
 
 // src/plays/local-file-discovery.ts
@@ -5379,8 +5530,19 @@ var SDK_PACKAGE_JSON = (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "package
 var SDK_ENTRY_FILE = (0, import_node_path9.resolve)(SDK_SOURCE_ROOT, "index.ts");
 var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : (0, import_node_path9.resolve)(SDK_PACKAGE_ROOT, "dist", "index.d.ts");
 var SDK_WORKERS_ENTRY_FILE = (0, import_node_path9.resolve)(SDK_SOURCE_ROOT, "worker-play-entry.ts");
-var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path9.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src", "entry.ts");
-var WORKERS_HARNESS_FILES_DIR = (0, import_node_path9.resolve)(PROJECT_ROOT, "apps", "play-runner-workers", "src");
+var WORKERS_HARNESS_ENTRY_FILE = (0, import_node_path9.resolve)(
+  PROJECT_ROOT,
+  "apps",
+  "play-runner-workers",
+  "src",
+  "entry.ts"
+);
+var WORKERS_HARNESS_FILES_DIR = (0, import_node_path9.resolve)(
+  PROJECT_ROOT,
+  "apps",
+  "play-runner-workers",
+  "src"
+);
 var hasWarnedAboutNonDevelopmentBundling = false;
 function warnAboutNonDevelopmentBundling(filePath) {
   if (hasWarnedAboutNonDevelopmentBundling) {
@@ -5399,13 +5561,16 @@ function warnAboutNonDevelopmentBundling(filePath) {
   );
 }
 function defaultPlayBundleTarget() {
-  return PLAY_BACKEND_DESCRIPTORS[resolveExecutionProfile(null).runner].artifactKind;
+  return resolveExecutionProfile(null).artifactKind;
 }
 function createSdkPlayBundlingAdapter() {
   return {
     projectRoot: PROJECT_ROOT,
     nodeModulesDir: (0, import_node_path9.resolve)(PROJECT_ROOT, "node_modules"),
-    cacheDir: (0, import_node_path9.join)((0, import_node_os5.tmpdir)(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`),
+    cacheDir: (0, import_node_path9.join)(
+      (0, import_node_os5.tmpdir)(),
+      `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION2}`
+    ),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,
@@ -5570,6 +5735,204 @@ 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(input) {
+  const bytes = Array.from(new TextEncoder().encode(input));
+  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.map() 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.map() key. Resolved table name: "${resolved}".`
+    );
+  }
+  return resolved;
+}
+
 // src/cli/trace.ts
 var cliTraceStartedAt = Date.now();
 function isTruthyEnv(value) {
@@ -5618,6 +5981,31 @@ 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.";
+function sourceLineForError(sourceCode, error) {
+  const match = error.match(/:(\d+):(\d+)\s/);
+  const lineNumber = match?.[1] ? Number(match[1]) : NaN;
+  if (!Number.isInteger(lineNumber) || lineNumber < 1) return "";
+  return sourceCode.split(/\r?\n/)[lineNumber - 1] ?? "";
+}
+function looksLikeInvalidExtractedGetter(error, sourceLine) {
+  if (!/Property '[^']+' does not exist on type/.test(error)) return false;
+  return /\bextracted(?:Values|Lists)\s*\./.test(sourceLine);
+}
+function addPlayCheckRepairHints(input) {
+  let addedHint = false;
+  return input.errors.map((error) => {
+    const line = sourceLineForError(input.sourceCode, error);
+    if (addedHint || !looksLikeInvalidExtractedGetter(error, line) || error.includes(EXTRACTED_GETTER_ERROR_HINT)) {
+      return error;
+    }
+    addedHint = true;
+    return `${error}
+${EXTRACTED_GETTER_ERROR_HINT}`;
+  });
+}
+
 // src/cli/commands/play.ts
 var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--json",
@@ -5697,9 +6085,23 @@ function formatPlayListReference(play) {
   return play.reference || play.name;
 }
 function defaultMaterializedPlayPath(reference) {
+  return (0, import_node_path10.resolve)(defaultStarterPlayPath(reference));
+}
+function defaultStarterPlayPath(reference) {
   const playName = parseReferencedPlayTarget(reference).unqualifiedPlayName;
   const safeName = playName.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return (0, import_node_path10.resolve)(`${safeName || "play"}.play.ts`);
+  return `./${safeName || "play"}.play.ts`;
+}
+function buildCloneEditStarter(play) {
+  const readonlyPrebuilt = (play.origin === "prebuilt" || play.ownerType === "deepline") && !play.canEdit;
+  if (!play.canClone && !readonlyPrebuilt) return void 0;
+  const reference = play.reference || play.name;
+  const path = defaultStarterPlayPath(reference);
+  return {
+    path,
+    command: `deepline plays get ${reference} --source --out ${path}`,
+    checkCommand: `deepline plays check ${path}`
+  };
 }
 function materializeRemotePlaySource(input) {
   if (isFileTarget(input.target)) {
@@ -6145,6 +6547,8 @@ 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 : {};
 }
@@ -6198,6 +6602,86 @@ 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(input) {
+  try {
+    const tableName = validatePlaySheetTableName(
+      input.playName,
+      input.tableNamespace
+    );
+    const table = `${quoteSqlIdentifier(
+      PLAY_CUSTOMER_STORAGE_SCHEMA_NAME
+    )}.${quoteSqlIdentifier(tableName)}`;
+    const sql = `select * from ${table} where _run_id = ${quoteSqlLiteral(input.runId)} limit 20`;
+    return buildDebugDbQueryCommand(sql);
+  } catch {
+    return null;
+  }
+}
+function extractTableNamespaceFromLiveEvent(event) {
+  const payload = getEventPayload(event);
+  const candidates = [
+    payload.artifactTableNamespace,
+    payload.tableNamespace,
+    payload.mapNodeId
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return null;
+}
+function emitLiveDebugTableHints(input) {
+  if (input.jsonOutput || !input.runId || input.runId === "pending") {
+    return;
+  }
+  input.state.emittedDebugKeys ??= /* @__PURE__ */ new Set();
+  const receiptsKey = `receipts:${input.runId}`;
+  if (!input.state.emittedDebugKeys.has(receiptsKey)) {
+    input.state.emittedDebugKeys.add(receiptsKey);
+    input.progress.writeLine(
+      `Debug top-level outputs: ${buildStepReceiptsDebugCommand(input.runId)}`,
+      process.stdout
+    );
+  }
+  const tableNamespace = extractTableNamespaceFromLiveEvent(input.event);
+  if (!tableNamespace) {
+    return;
+  }
+  const tableKey = `table:${input.runId}:${tableNamespace}`;
+  if (input.state.emittedDebugKeys.has(tableKey)) {
+    return;
+  }
+  const command = buildMapTableDebugCommand({
+    playName: input.playName,
+    runId: input.runId,
+    tableNamespace
+  });
+  if (!command) {
+    return;
+  }
+  input.state.emittedDebugKeys.add(tableKey);
+  input.progress.writeLine(
+    `Debug rows for ${tableNamespace}: ${command}`,
+    process.stdout
+  );
+}
 function describeLiveEventPhase(event) {
   const payload = getEventPayload(event);
   if (event.type === "play.run.status") {
@@ -6350,6 +6834,14 @@ async function waitForPlayCompletionByStream(input) {
         lastPhase = phase;
         input.progress.phase(phase);
       }
+      emitLiveDebugTableHints({
+        event,
+        playName: input.playName,
+        runId: input.workflowId,
+        jsonOutput: input.jsonOutput,
+        state: input.state,
+        progress: input.progress
+      });
       printPlayLogLines({
         lines: getLogLinesFromLiveEvent(event),
         status: null,
@@ -6498,6 +6990,14 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
         state,
         progress: input.progress
       });
+      emitLiveDebugTableHints({
+        event,
+        playName: input.playName,
+        runId: workflowId,
+        jsonOutput: input.jsonOutput,
+        state,
+        progress: input.progress
+      });
       if (!input.jsonOutput) {
         printPlayProgressLines({
           lines: getProgressLinesFromLiveEvent(event),
@@ -6553,6 +7053,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
       });
       return waitForPlayCompletionByStream({
         client: input.client,
+        playName: input.playName,
         workflowId: lastKnownWorkflowId,
         dashboardUrl,
         jsonOutput: input.jsonOutput,
@@ -6588,6 +7089,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input) {
     });
     return waitForPlayCompletionByStream({
       client: input.client,
+      playName: input.playName,
       workflowId: lastKnownWorkflowId,
       dashboardUrl,
       jsonOutput: input.jsonOutput,
@@ -7971,6 +8473,10 @@ async function handlePlayCheck(args) {
   });
   const enrichedResult = {
     ...result,
+    errors: result.valid ? result.errors : addPlayCheckRepairHints({
+      errors: result.errors,
+      sourceCode: graph.root.sourceCode
+    }),
     toolGetterHints: result.toolGetterHints ?? await buildToolGetterHints(client, result.staticPipeline)
   };
   if (options.jsonOutput) {
@@ -8756,25 +9262,13 @@ function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
     throw new Error(
-      "Usage: deepline plays search <query> [--origin prebuilt|owned] [--compact] [--json]"
+      "Usage: deepline plays search <query> [--compact] [--json]"
     );
   }
-  let origin;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--origin" && args[index + 1]) {
-      const rawOrigin = args[++index].trim().toLowerCase();
-      if (rawOrigin !== "prebuilt" && rawOrigin !== "owned") {
-        throw new Error(`Invalid value for --origin: ${rawOrigin}`);
-      }
-      origin = rawOrigin;
-    }
-  }
   return {
     query,
     jsonOutput: argsWantJson(args),
-    compact: args.includes("--compact"),
-    origin
+    compact: args.includes("--compact")
   };
 }
 function printPlayDescription(play) {
@@ -8823,10 +9317,10 @@ function printPlayDescription(play) {
     }
   }
   console.log(`  Run: ${play.runCommand}`);
-  if (play.origin === "prebuilt" && !play.canEdit) {
-    console.log(
-      `  Customize: deepline plays get ${reference} --source --out ./my-play.play.ts`
-    );
+  const cloneEditStarter = play.cloneEditStarter ?? buildCloneEditStarter(play);
+  if (cloneEditStarter) {
+    console.log(`  Clone/edit starter: ${cloneEditStarter.command}`);
+    console.log(`  Check starter: ${cloneEditStarter.checkCommand}`);
   }
 }
 function compactPlaySchema(schema) {
@@ -8858,6 +9352,7 @@ function summarizePlayListItemForCli(play, options) {
   const csvInput = playSchemaMetadata(play.inputSchema, "csvInput");
   const rowOutputSchema = playSchemaMetadata(play.outputSchema, "rowOutputSchema");
   const runCommand2 = playRunCommand(play, { csvInput });
+  const cloneEditStarter = buildCloneEditStarter(play);
   return {
     name: play.name,
     ...play.reference ? { reference: play.reference } : {},
@@ -8873,6 +9368,7 @@ function summarizePlayListItemForCli(play, options) {
     ...rowOutputSchema ? { rowOutputSchema } : {},
     runCommand: runCommand2,
     examples: [runCommand2],
+    ...cloneEditStarter ? { cloneEditStarter } : {},
     currentPublishedVersion: play.currentPublishedVersion ?? null,
     isDraftDirty: play.isDraftDirty
   };
@@ -8888,7 +9384,6 @@ async function handlePlaySearch(args) {
   const client = new DeeplineClient();
   const plays = await client.searchPlays({
     query: options.query,
-    ...options.origin ? { origin: options.origin } : {},
     compact: options.compact
   });
   if (options.jsonOutput) {
@@ -8934,20 +9429,12 @@ function matchesPlayGrepQuery(value, query, mode) {
 async function handlePlayGrep(args) {
   const query = args[0]?.trim();
   if (!query) {
-    console.error("Usage: deepline plays grep <query> [--origin prebuilt|owned] [--compact] [--json]");
+    console.error("Usage: deepline plays grep <query> [--mode all|any|phrase] [--compact] [--json]");
     return 1;
   }
-  let origin;
   let mode = "all";
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === "--origin" && args[index + 1]) {
-      const rawOrigin = args[++index].trim().toLowerCase();
-      if (rawOrigin !== "prebuilt" && rawOrigin !== "owned") {
-        throw new Error(`Invalid value for --origin: ${rawOrigin}`);
-      }
-      origin = rawOrigin;
-    }
     if (arg === "--mode" && args[index + 1]) {
       const rawMode = args[++index].trim().toLowerCase();
       mode = rawMode === "any" || rawMode === "phrase" ? rawMode : "all";
@@ -8957,13 +9444,8 @@ async function handlePlayGrep(args) {
   const client = new DeeplineClient();
   const plays = (await client.listPlays({
     grep: query,
-    grepMode: mode,
-    ...origin ? { origin } : {}
-  })).filter((play) => {
-    if (!origin) return true;
-    const isPrebuilt = play.origin === "prebuilt" || play.ownerType === "deepline";
-    return origin === "prebuilt" ? isPrebuilt : !isPrebuilt;
-  }).filter(
+    grepMode: mode
+  })).filter(
     (play) => matchesPlayGrepQuery(
       {
         name: play.name,
@@ -8984,8 +9466,7 @@ async function handlePlayGrep(args) {
       plays,
       count: plays.length,
       query,
-      grep: { mode, terms: parsePlayGrepTerms(query, mode) },
-      filters: { origin: origin ?? null }
+      grep: { mode, terms: parsePlayGrepTerms(query, mode) }
     })}
 `);
     return 0;
@@ -9321,7 +9802,7 @@ Notes:
 Examples:
   deepline plays list
   deepline plays list --origin prebuilt --json
-  deepline plays search email --origin prebuilt --json
+  deepline plays search email --json
 `
   ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handlePlayList([
@@ -9333,20 +9814,18 @@ Examples:
     "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.
+  Ranked discovery for workflows. Use describe on a result before running it.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering the play registry.
 
 Examples:
   deepline plays search email
-  deepline plays grep "linkedin to email" --origin prebuilt --compact --json
+  deepline plays grep "linkedin to email" --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) => {
+  ).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] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.json ? ["--json"] : []
     ]);
@@ -9362,14 +9841,13 @@ Notes:
   --mode all for AND.
 
 Examples:
-  deepline plays grep email --origin prebuilt --json
-  deepline plays grep "company contact" --origin prebuilt --mode all --json
+  deepline plays grep email --json
+  deepline plays grep "company contact" --mode all --json
   deepline plays describe prebuilt/company-to-contact --json
 `
-  ).option("--origin <origin>", "Filter to prebuilt or owned plays").option("--compact", "Emit compact schemas").option("--mode <mode>", "Grep matching mode: all, any, or phrase").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  ).option("--compact", "Emit compact schemas").option("--mode <mode>", "Grep matching mode: all, any, or phrase").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlayGrep([
       query,
-      ...options.origin ? ["--origin", options.origin] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.mode ? ["--mode", options.mode] : [],
       ...options.json ? ["--json"] : []
@@ -9385,6 +9863,7 @@ Notes:
 Examples:
   deepline plays describe person-linkedin-to-email
   deepline plays describe person-linkedin-to-email --json
+  deepline plays get prebuilt/person-linkedin-to-email --source --out ./person-linkedin-to-email.play.ts
 `
   ).option("--compact", "Emit compact schemas").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayDescribe([
@@ -10209,6 +10688,11 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   const cost = recordField(tool, "cost");
   const deeplineCredits = numberField(tool, "deeplineCreditsPerPricingUnit", "deepline_credits_per_pricing_unit");
   const deeplineUsdPerPricingUnit = numberField(tool, "deeplineUsdPerPricingUnit", "deepline_usd_per_pricing_unit");
+  const starterScript = seedToolListScript({
+    toolId,
+    payload: samplePayloadForInputFields(inputFields),
+    rows: []
+  });
   return {
     schemaVersion: 1,
     toolId,
@@ -10233,7 +10717,16 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
       extractedLists,
       extractedValues
     },
-    executeCommand: `deepline tools execute ${toolId} --input '{...}' --json`
+    executeCommand: `deepline tools execute ${toolId} --input '{...}' --json`,
+    starterScript: {
+      path: starterScript.path,
+      sourceCode: starterScript.sourceCode,
+      projectDir: starterScript.projectDir,
+      copyToProject: {
+        macosLinux: starterScript.macCopyCommand,
+        windowsPowerShell: starterScript.windowsCopyCommand
+      }
+    }
   };
 }
 function extractionContractEntries(entries) {
@@ -10275,6 +10768,13 @@ function printCompactToolContract(tool, requestedToolId) {
   }
   console.log("");
   printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
+  const starterScript = isRecord4(contract.starterScript) ? contract.starterScript : {};
+  const starterPath = stringField(starterScript, "path");
+  if (starterPath) {
+    console.log("");
+    console.log(`Starter script: ${starterPath}`);
+    console.log("Copy it into your project and replace the sample input with the proven probe payload.");
+  }
   if (listGetters.length || valueGetters.length) {
     console.log("");
     console.log("Getters:");
@@ -10326,14 +10826,7 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
   const toolId = String(contract.toolId);
   const inputFields = Array.isArray(contract.inputFields) ? contract.inputFields : [];
-  const sampleInput = Object.fromEntries(
-    inputFields.slice(0, 4).flatMap((field) => {
-      if (!isRecord4(field)) return [];
-      const name = stringField(field, "name");
-      if (!name) return [];
-      return [[name, sampleValueForField(field)]];
-    })
-  );
+  const sampleInput = samplePayloadForInputFields(inputFields);
   console.log(`Use in a play:`);
   console.log("```ts");
   console.log("const result = await ctx.tools.execute({");
@@ -10394,6 +10887,16 @@ function sampleValueForField(field) {
   if (type === "object") return {};
   return "...";
 }
+function samplePayloadForInputFields(fields) {
+  return Object.fromEntries(
+    fields.slice(0, 4).flatMap((field) => {
+      if (!isRecord4(field)) return [];
+      const name = stringField(field, "name");
+      if (!name) return [];
+      return [[name, sampleValueForField(field)]];
+    })
+  );
+}
 function stableStepIdForTool(toolId) {
   return toolId.replace(/^[a-z0-9]+_/, "").replace(/[^a-z0-9_]+/gi, "_") || "tool_call";
 }
@@ -10406,6 +10909,12 @@ function playResultExpression(entry) {
 }
 function toolMetadataJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
+  const inputFields = toolInputFieldsForDisplay(recordField(tool, "inputSchema", "input_schema"));
+  const starterScript = seedToolListScript({
+    toolId,
+    payload: samplePayloadForInputFields(inputFields),
+    rows: []
+  });
   const {
     cost: _cost,
     deeplineCreditsPerPricingUnit: _deeplineCreditsPerPricingUnit,
@@ -10425,12 +10934,48 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
+    usageGuidance: usageGuidanceWithAccessDefaults(recordField(tool, "usageGuidance", "usage_guidance")),
     runtimeOutputHelp: {
-      contract: "tools describe shows the declared schema and semantic getters; it is not an observed provider response.",
+      contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",
+      getterScope: "extractedValues/extractedLists .get() only works for declared Deepline getters listed in usageGuidance.toolExecutionResult.",
+      rawToolResponse: "Use toolExecutionResult.toolResponse.raw for provider/tool-specific fields, fields in outputSchema that are not declared getters, and debugging.",
+      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."
+    },
+    starterScript: {
+      path: starterScript.path,
+      sourceCode: starterScript.sourceCode,
+      projectDir: starterScript.projectDir,
+      copyToProject: {
+        macosLinux: starterScript.macCopyCommand,
+        windowsPowerShell: starterScript.windowsCopyCommand
+      }
+    }
+  };
+}
+function usageGuidanceWithAccessDefaults(usageGuidance) {
+  if (Object.keys(usageGuidance).length === 0) return usageGuidance;
+  const existingAccess = recordField(usageGuidance, "access");
+  return {
+    ...usageGuidance,
+    access: {
+      extractedLists: {
+        expression: "toolExecutionResult.extractedLists.<name>.get()",
+        meaning: "Declared Deepline list extractors only."
+      },
+      extractedValues: {
+        expression: "toolExecutionResult.extractedValues.<name>.get()",
+        meaning: "Declared Deepline scalar extractors only."
+      },
+      rawToolResponse: {
+        expression: "toolExecutionResult.toolResponse.raw",
+        meaning: "Raw tool response for provider/tool-specific fields and debugging."
+      },
+      invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; use toolResponse.raw for provider/tool-specific fields.",
+      ...existingAccess
     }
   };
 }
@@ -10647,6 +11192,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   (0, import_node_fs10.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
   return {
     path: scriptPath,
+    sourceCode: script,
     projectDir,
     macCopyCommand: `mkdir -p ${shellQuote(projectDir)} && cp ${shellQuote(scriptPath)} ${shellQuote(`${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`