deepline 0.1.123 → 0.1.124

package/dist/cli/index.js

@@ -403,10 +403,11 @@ var SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: "0.1.123",
+  // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
+  version: "0.1.124",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.123",
+    latest: "0.1.124",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -414,6 +415,55 @@ var SDK_RELEASE = {
         command: "enrich",
         minimumSupported: "0.1.108",
         reason: "Older SDK CLI enrich generated stale play source for the current dataset API."
+      },
+      {
+        command: "plays",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays run",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "run",
+        displayCommand: "plays run",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays check",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "check",
+        displayCommand: "plays check",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays publish",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "publish",
+        displayCommand: "plays publish",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays set-live",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "set-live",
+        displayCommand: "plays set-live",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
       }
     ],
     autoUpdatePatchLag: 2
@@ -2086,12 +2136,14 @@ var DeeplineClient = class {
       play.outputSchema,
       "rowOutputSchema"
     );
+    const description = play.description?.trim() || play.currentRevision?.description?.trim() || play.liveRevision?.description?.trim() || null;
     const runCommand2 = this.playRunCommand(play, { csvInput });
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
+      ...description ? { description } : {},
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -2312,6 +2364,7 @@ var DeeplineClient = class {
         ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
         ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
         ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+        ...request.description ? { description: request.description } : {},
         ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
         ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
         ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2350,6 +2403,7 @@ var DeeplineClient = class {
       ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
       ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
       ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+      ...request.description ? { description: request.description } : {},
       ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
       ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
       ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2507,6 +2561,7 @@ var DeeplineClient = class {
       name: input2.name,
       sourceCode: input2.sourceCode,
       sourceFiles: input2.sourceFiles,
+      description: input2.description,
       artifact: input2.artifact,
       compilerManifest,
       publish: false
@@ -2519,6 +2574,7 @@ var DeeplineClient = class {
     return this.startPlayRun({
       name: input2.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input2.description,
       compilerManifest,
       ...input2.input ? { input: input2.input } : {},
       ...input2.inputFile ? { inputFile: input2.inputFile } : {},
@@ -2573,6 +2629,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2586,6 +2643,7 @@ var DeeplineClient = class {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash: typeof artifact.artifactHash === "string" ? artifact.artifactHash : void 0,
       graphHash: typeof artifact.graphHash === "string" ? artifact.graphHash : void 0,
@@ -8151,6 +8209,8 @@ export default definePlay(${jsString(input2.options.name)}, async (ctx, input: I
     count: await rows.count(),
     rows,
   };
+}, {
+  description: ${jsString(`Bootstrap ${input2.options.template}: seed source rows, run requested stages, and return mapped rows.`)},
 });
 
 `;
@@ -9534,6 +9594,24 @@ function requireCompilerManifest(node) {
   }
   return node.compilerManifest;
 }
+function missingPlayDescriptionMessage(node) {
+  const playName = node.playName ?? extractPlayName(node.sourceCode, node.filePath);
+  return [
+    `Play description is required for ${playName} (${node.filePath}).`,
+    "Add a top-level description to definePlay so agents and future play surfaces can explain what this play does.",
+    `Example: definePlay("${playName}", async (ctx, input) => { ... }, { description: "Look up company details from a domain." })`,
+    `Object form: definePlay({ id: "${playName}", description: "Look up company details from a domain.", input, run })`
+  ].join(" ");
+}
+function collectMissingPlayDescriptionErrors(graph) {
+  return [...graph.nodes.values()].filter((node) => !node.playDescription?.trim()).map(missingPlayDescriptionMessage);
+}
+function assertBundledPlayGraphDescriptions(graph) {
+  const errors = collectMissingPlayDescriptionErrors(graph);
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
 async function publishImportedPlayDependencies(client2, graph) {
   const published = /* @__PURE__ */ new Set();
   const publishNode = async (filePath, skipPublish) => {
@@ -9557,6 +9635,7 @@ async function publishImportedPlayDependencies(client2, graph) {
       name: node.playName,
       sourceCode: node.sourceCode,
       sourceFiles: node.sourceFiles,
+      description: node.playDescription ?? void 0,
       artifact: node.artifact,
       compilerManifest: requireCompilerManifest(node),
       publish: true
@@ -12254,6 +12333,26 @@ async function handlePlayCheck(args) {
     return 1;
   }
   const playName = graph.root.playName ?? extractPlayName(sourceCode, absolutePlayPath);
+  const descriptionErrors = collectMissingPlayDescriptionErrors(graph);
+  if (descriptionErrors.length > 0) {
+    if (options.jsonOutput) {
+      process.stdout.write(
+        `${JSON.stringify({
+          name: playName,
+          valid: false,
+          stage: "authoring",
+          errors: descriptionErrors
+        })}
+`
+      );
+    } else {
+      console.error(`\u2717 ${playName} failed local play check`);
+      for (const error of descriptionErrors) {
+        console.error(`  ${error}`);
+      }
+    }
+    return 1;
+  }
   if (shouldUseLocalOnlyPlayCheck()) {
     const result2 = {
       valid: true,
@@ -12280,6 +12379,7 @@ async function handlePlayCheck(args) {
     name: playName,
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
+    description: graph.root.playDescription ?? void 0,
     artifact: graph.root.artifact
   });
   const enrichedResult = {
@@ -12337,6 +12437,7 @@ async function handleFileBackedRun(options) {
       { targetKind: "file" },
       () => collectBundledPlayGraph(absolutePlayPath, options.profile)
     );
+    assertBundledPlayGraphDescriptions(graph);
     const canDeferCompilerManifest = graph.root.importedPlayDependencies.length === 0 && !sourceGraphMentionsRunPlay(graph.root) && !inputContainsLocalFilePath(runtimeInput);
     if (canDeferCompilerManifest) {
       recordCliTrace({
@@ -12401,6 +12502,7 @@ async function handleFileBackedRun(options) {
     name: playName,
     sourceCode: bundleResult.sourceCode,
     sourceFiles: bundleResult.sourceFiles,
+    description: bundleResult.playDescription ?? void 0,
     runtimeArtifact: bundleResult.artifact,
     ...compilerManifest ? { compilerManifest } : {},
     packagedFileUploads,
@@ -13212,6 +13314,9 @@ function printPlayDescription(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -13264,6 +13369,9 @@ function printCompactPlaySearchResult(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (aliases) {
     console.log(`  Aliases: ${aliases}`);
   }
@@ -13577,6 +13685,7 @@ async function handlePlayPublish(args) {
         { targetKind: "file" },
         () => collectBundledPlayGraph((0, import_node_path10.resolve)(playName))
       );
+      assertBundledPlayGraphDescriptions(graph);
       await traceCliSpan(
         "cli.play_publish_compile_manifests",
         { targetKind: "file", nodeCount: graph.nodes.size },
@@ -13603,6 +13712,7 @@ async function handlePlayPublish(args) {
         name: rootPlayName,
         sourceCode: graph.root.sourceCode,
         sourceFiles: graph.root.sourceFiles,
+        description: graph.root.playDescription ?? void 0,
         artifact: graph.root.artifact,
         compilerManifest: requireCompilerManifest(graph.root),
         publish: true
@@ -15051,7 +15161,7 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
     ...metadataColumnSource ? [metadataColumnSource] : [],
     `    .run({ key: (row, index) => __dlStableRowKey(row, index + rowStart) });`,
     `  return { rows: enriched, count: await enriched.count() };`,
-    `});`
+    `}, { description: ${stringLiteral("Read a CSV file, run the configured Deepline enrich commands, and return enriched rows.")} });`
   ];
   const helpers = idiomaticGetters ? selectUsedHelpers(helperSource(), body.join("\n")) : helperSource();
   return [
@@ -20344,6 +20454,8 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     rows: enrichedData,
     count: await enrichedData.count(),
   };
+}, {
+  description: ${JSON.stringify(`Seed ${input2.toolId} rows into a Deepline workflow-ready dataset.`)},
 });
 `;
   (0, import_node_fs13.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
@@ -22259,6 +22371,16 @@ function isLegacyNoopInvocation() {
   const command = process.argv.slice(2)[0];
   return command === "session" || command === "backend";
 }
+function compatibilityCommandPath(command) {
+  const names = [];
+  let current = command;
+  while (current?.parent) {
+    const name = current.name();
+    if (name) names.unshift(name);
+    current = current.parent;
+  }
+  return names.join(" ");
+}
 function topLevelCommandKnown(program, commandName) {
   const normalized = commandName.trim();
   if (!normalized || normalized.startsWith("-")) {
@@ -22283,6 +22405,8 @@ async function runPlayRunnerHealthCheck() {
         "    .withColumn('echo', (row) => ({ ok: true, id: row.id }))",
         "    .run({ key: 'id' });",
         "  return { ok: true, rows, source: 'deepline health --play-runner' };",
+        "}, {",
+        "  description: 'Run a local Deepline play health check with a tiny dataset.',",
         "});",
         ""
       ].join("\n"),
@@ -22494,11 +22618,12 @@ Exit codes:
       progress?.phase("checking sdk compatibility");
     }
     const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+    const compatibilityCommand = compatibilityCommandPath(actionCommand) || actionCommand.name();
     const compatibility = await traceCliSpan(
       "cli.sdk_compatibility",
-      { baseUrl, command: actionCommand.name() },
+      { baseUrl, command: compatibilityCommand },
       () => checkSdkCompatibility(baseUrl, {
-        command: actionCommand.name()
+        command: compatibilityCommand
       })
     );
     if (compatibility.error) {

package/dist/cli/index.mjs

@@ -380,10 +380,11 @@ var SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: "0.1.123",
+  // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
+  version: "0.1.124",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.123",
+    latest: "0.1.124",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -391,6 +392,55 @@ var SDK_RELEASE = {
         command: "enrich",
         minimumSupported: "0.1.108",
         reason: "Older SDK CLI enrich generated stale play source for the current dataset API."
+      },
+      {
+        command: "plays",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays run",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "run",
+        displayCommand: "plays run",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays check",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "check",
+        displayCommand: "plays check",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays publish",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "publish",
+        displayCommand: "plays publish",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "plays set-live",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+      },
+      {
+        command: "set-live",
+        displayCommand: "plays set-live",
+        minimumSupported: "0.1.110",
+        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
       }
     ],
     autoUpdatePatchLag: 2
@@ -2063,12 +2113,14 @@ var DeeplineClient = class {
       play.outputSchema,
       "rowOutputSchema"
     );
+    const description = play.description?.trim() || play.currentRevision?.description?.trim() || play.liveRevision?.description?.trim() || null;
     const runCommand2 = this.playRunCommand(play, { csvInput });
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
+      ...description ? { description } : {},
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -2289,6 +2341,7 @@ var DeeplineClient = class {
         ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
         ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
         ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+        ...request.description ? { description: request.description } : {},
         ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
         ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
         ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2327,6 +2380,7 @@ var DeeplineClient = class {
       ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
       ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
       ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+      ...request.description ? { description: request.description } : {},
       ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
       ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
       ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2484,6 +2538,7 @@ var DeeplineClient = class {
       name: input2.name,
       sourceCode: input2.sourceCode,
       sourceFiles: input2.sourceFiles,
+      description: input2.description,
       artifact: input2.artifact,
       compilerManifest,
       publish: false
@@ -2496,6 +2551,7 @@ var DeeplineClient = class {
     return this.startPlayRun({
       name: input2.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input2.description,
       compilerManifest,
       ...input2.input ? { input: input2.input } : {},
       ...input2.inputFile ? { inputFile: input2.inputFile } : {},
@@ -2550,6 +2606,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2563,6 +2620,7 @@ var DeeplineClient = class {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash: typeof artifact.artifactHash === "string" ? artifact.artifactHash : void 0,
       graphHash: typeof artifact.graphHash === "string" ? artifact.graphHash : void 0,
@@ -6812,7 +6870,13 @@ import { basename, dirname as dirname6, join as join5, resolve as resolve7 } fro
 import { parse as parseCsvSync2 } from "csv-parse/sync";
 
 // src/cli/commands/plays/bootstrap.ts
-import { closeSync, openSync, readSync, statSync, writeFileSync as writeFileSync7 } from "fs";
+import {
+  closeSync,
+  openSync,
+  readSync,
+  statSync,
+  writeFileSync as writeFileSync7
+} from "fs";
 import { isAbsolute, relative, resolve as resolve6 } from "path";
 import { parse as parseCsvSync } from "csv-parse/sync";
 
@@ -8154,6 +8218,8 @@ export default definePlay(${jsString(input2.options.name)}, async (ctx, input: I
     count: await rows.count(),
     rows,
   };
+}, {
+  description: ${jsString(`Bootstrap ${input2.options.template}: seed source rows, run requested stages, and return mapped rows.`)},
 });
 
 `;
@@ -9537,6 +9603,24 @@ function requireCompilerManifest(node) {
   }
   return node.compilerManifest;
 }
+function missingPlayDescriptionMessage(node) {
+  const playName = node.playName ?? extractPlayName(node.sourceCode, node.filePath);
+  return [
+    `Play description is required for ${playName} (${node.filePath}).`,
+    "Add a top-level description to definePlay so agents and future play surfaces can explain what this play does.",
+    `Example: definePlay("${playName}", async (ctx, input) => { ... }, { description: "Look up company details from a domain." })`,
+    `Object form: definePlay({ id: "${playName}", description: "Look up company details from a domain.", input, run })`
+  ].join(" ");
+}
+function collectMissingPlayDescriptionErrors(graph) {
+  return [...graph.nodes.values()].filter((node) => !node.playDescription?.trim()).map(missingPlayDescriptionMessage);
+}
+function assertBundledPlayGraphDescriptions(graph) {
+  const errors = collectMissingPlayDescriptionErrors(graph);
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
 async function publishImportedPlayDependencies(client2, graph) {
   const published = /* @__PURE__ */ new Set();
   const publishNode = async (filePath, skipPublish) => {
@@ -9560,6 +9644,7 @@ async function publishImportedPlayDependencies(client2, graph) {
       name: node.playName,
       sourceCode: node.sourceCode,
       sourceFiles: node.sourceFiles,
+      description: node.playDescription ?? void 0,
       artifact: node.artifact,
       compilerManifest: requireCompilerManifest(node),
       publish: true
@@ -12257,6 +12342,26 @@ async function handlePlayCheck(args) {
     return 1;
   }
   const playName = graph.root.playName ?? extractPlayName(sourceCode, absolutePlayPath);
+  const descriptionErrors = collectMissingPlayDescriptionErrors(graph);
+  if (descriptionErrors.length > 0) {
+    if (options.jsonOutput) {
+      process.stdout.write(
+        `${JSON.stringify({
+          name: playName,
+          valid: false,
+          stage: "authoring",
+          errors: descriptionErrors
+        })}
+`
+      );
+    } else {
+      console.error(`\u2717 ${playName} failed local play check`);
+      for (const error of descriptionErrors) {
+        console.error(`  ${error}`);
+      }
+    }
+    return 1;
+  }
   if (shouldUseLocalOnlyPlayCheck()) {
     const result2 = {
       valid: true,
@@ -12283,6 +12388,7 @@ async function handlePlayCheck(args) {
     name: playName,
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
+    description: graph.root.playDescription ?? void 0,
     artifact: graph.root.artifact
   });
   const enrichedResult = {
@@ -12340,6 +12446,7 @@ async function handleFileBackedRun(options) {
       { targetKind: "file" },
       () => collectBundledPlayGraph(absolutePlayPath, options.profile)
     );
+    assertBundledPlayGraphDescriptions(graph);
     const canDeferCompilerManifest = graph.root.importedPlayDependencies.length === 0 && !sourceGraphMentionsRunPlay(graph.root) && !inputContainsLocalFilePath(runtimeInput);
     if (canDeferCompilerManifest) {
       recordCliTrace({
@@ -12404,6 +12511,7 @@ async function handleFileBackedRun(options) {
     name: playName,
     sourceCode: bundleResult.sourceCode,
     sourceFiles: bundleResult.sourceFiles,
+    description: bundleResult.playDescription ?? void 0,
     runtimeArtifact: bundleResult.artifact,
     ...compilerManifest ? { compilerManifest } : {},
     packagedFileUploads,
@@ -13215,6 +13323,9 @@ function printPlayDescription(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -13267,6 +13378,9 @@ function printCompactPlaySearchResult(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (aliases) {
     console.log(`  Aliases: ${aliases}`);
   }
@@ -13580,6 +13694,7 @@ async function handlePlayPublish(args) {
         { targetKind: "file" },
         () => collectBundledPlayGraph(resolve7(playName))
       );
+      assertBundledPlayGraphDescriptions(graph);
       await traceCliSpan(
         "cli.play_publish_compile_manifests",
         { targetKind: "file", nodeCount: graph.nodes.size },
@@ -13606,6 +13721,7 @@ async function handlePlayPublish(args) {
         name: rootPlayName,
         sourceCode: graph.root.sourceCode,
         sourceFiles: graph.root.sourceFiles,
+        description: graph.root.playDescription ?? void 0,
         artifact: graph.root.artifact,
         compilerManifest: requireCompilerManifest(graph.root),
         publish: true
@@ -15054,7 +15170,7 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
     ...metadataColumnSource ? [metadataColumnSource] : [],
     `    .run({ key: (row, index) => __dlStableRowKey(row, index + rowStart) });`,
     `  return { rows: enriched, count: await enriched.count() };`,
-    `});`
+    `}, { description: ${stringLiteral("Read a CSV file, run the configured Deepline enrich commands, and return enriched rows.")} });`
   ];
   const helpers = idiomaticGetters ? selectUsedHelpers(helperSource(), body.join("\n")) : helperSource();
   return [
@@ -20360,6 +20476,8 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     rows: enrichedData,
     count: await enrichedData.count(),
   };
+}, {
+  description: ${JSON.stringify(`Seed ${input2.toolId} rows into a Deepline workflow-ready dataset.`)},
 });
 `;
   writeFileSync12(scriptPath, script, { encoding: "utf-8", mode: 384 });
@@ -22282,6 +22400,16 @@ function isLegacyNoopInvocation() {
   const command = process.argv.slice(2)[0];
   return command === "session" || command === "backend";
 }
+function compatibilityCommandPath(command) {
+  const names = [];
+  let current = command;
+  while (current?.parent) {
+    const name = current.name();
+    if (name) names.unshift(name);
+    current = current.parent;
+  }
+  return names.join(" ");
+}
 function topLevelCommandKnown(program, commandName) {
   const normalized = commandName.trim();
   if (!normalized || normalized.startsWith("-")) {
@@ -22306,6 +22434,8 @@ async function runPlayRunnerHealthCheck() {
         "    .withColumn('echo', (row) => ({ ok: true, id: row.id }))",
         "    .run({ key: 'id' });",
         "  return { ok: true, rows, source: 'deepline health --play-runner' };",
+        "}, {",
+        "  description: 'Run a local Deepline play health check with a tiny dataset.',",
         "});",
         ""
       ].join("\n"),
@@ -22517,11 +22647,12 @@ Exit codes:
       progress?.phase("checking sdk compatibility");
     }
     const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+    const compatibilityCommand = compatibilityCommandPath(actionCommand) || actionCommand.name();
     const compatibility = await traceCliSpan(
       "cli.sdk_compatibility",
-      { baseUrl, command: actionCommand.name() },
+      { baseUrl, command: compatibilityCommand },
       () => checkSdkCompatibility(baseUrl, {
-        command: actionCommand.name()
+        command: compatibilityCommand
       })
     );
     if (compatibility.error) {