deepline 0.3.311 → 0.3.312

package/dist/cli/{play-SOG5Q2GE.mjs → chunk-I25C4KL7.mjs}

@@ -1,13 +1,17 @@
 import {
-  handleDeploymentGet,
-  handleDeploymentsList
-} from "./chunk-4WFNAWVO.mjs";
+  addDescribeOptions,
+  schemaFields
+} from "./chunk-76VKBPOC.mjs";
 import {
   parseCsvDataInput
 } from "./chunk-EDWJY6T4.mjs";
 import {
   registerDeprecatedSearchCommand
-} from "./chunk-ICZB4GTY.mjs";
+} from "./chunk-MK4K5MQU.mjs";
+import {
+  handleDeploymentGet,
+  handleDeploymentsList
+} from "./chunk-EHVJ7XXD.mjs";
 import {
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
   PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER,
@@ -30,7 +34,7 @@ import {
   normalizeRunEventOperationRequest,
   parseLogLevel,
   playInputExampleArgs
-} from "./chunk-5OVNL6LS.mjs";
+} from "./chunk-NWFE4PGX.mjs";
 import {
   CSV_DATA_INPUT_KEY,
   buildNamedPlayRunRequest,
@@ -62,12 +66,10 @@ import {
   printJson,
   printJsonError,
   renderCommandEnvelopeText
-} from "./chunk-SPUTBCUR.mjs";
+} from "./chunk-ZH7KTVAB.mjs";
 import {
   fetchWithDeploymentProtection
-} from "./chunk-Q3LYQTSO.mjs";
-import "./chunk-DLIRSHV6.mjs";
-import "./chunk-SGTSJCOA.mjs";
+} from "./chunk-WPTUKXIF.mjs";
 import {
   PLAY_DEFAULT_EXPORT,
   extractDefinedPlayName,
@@ -75,14 +77,10 @@ import {
   listPlayFileExports,
   parsePlaySourceForAnalysis,
   resolveEnabledExecutionProfile
-} from "./chunk-4NIQA6S7.mjs";
-import "./chunk-H7HIDGZ7.mjs";
-import "./chunk-WB6Z2Q44.mjs";
-import "./chunk-6IKARAYD.mjs";
+} from "./chunk-US4S3E4Y.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";
-import "./chunk-WZYKRD7T.mjs";
 import {
   __commonJS,
   __toESM
@@ -1917,6 +1915,7 @@ function displayPlayPath(path, ownerName) {
     ...path?.folders ?? []
   ].join(" / ");
 }
+var playDisplayNameSchema = z.string().trim().nullable().transform((value) => value || null);
 var PLAY_SETTING_FIELDS = {
   path: {
     schema: playPathSchema.default(null).describe(
@@ -1937,9 +1936,26 @@ var PLAY_SETTING_FIELDS = {
         "null"
       ],
       parse: (value) => value === "null" ? null : parsePlayPath(value),
-      format: formatPlayPath
+      format: (value) => formatPlayPath(playPathSchema.parse(value))
     },
     ui: { control: "play-location-picker" }
+  },
+  displayName: {
+    schema: playDisplayNameSchema.default(null).describe(
+      "Optional human-readable Play name. Null uses the name derived from the identifier."
+    ),
+    label: "Display name",
+    description: "Optional name shown in the UI. Leave empty to use the name derived from the Play identifier.",
+    get defaultValue() {
+      return this.schema.parse(void 0);
+    },
+    cli: {
+      valueSyntax: "text | null",
+      examples: ["Find verified emails", "null"],
+      parse: (value) => value === "null" ? null : value,
+      format: (value) => playDisplayNameSchema.parse(value) ?? "null"
+    },
+    ui: { control: "text" }
   }
 };
 var playSettingsSchema = z.object(
@@ -2043,6 +2059,7 @@ function resolveField(key, command) {
   return entry[1];
 }
 function printSettings(result, json, name) {
+  result = { ...result, settings: parsePlaySettings(result.settings) };
   const selected = fields.filter(([key]) => !name || key === name);
   printCommandEnvelope(
     {
@@ -4295,7 +4312,7 @@ Example: deepline plays bootstrap people-email --from csv:data/leads.csv --using
       `Unknown plays bootstrap template: ${rawTemplate}
 Supported templates: ${formatPlayBootstrapTemplates()}|${MONITOR_BOOTSTRAP_TEMPLATE}` + (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 '{...}'" 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.` : "")
+"${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 '{...}'" to run it directly, "deepline describe ${rawTemplate}" to inspect its contract, or "deepline plays get ${rawTemplate} --source --out scratchpad.play.ts" to clone/edit it.` : "")
     );
   }
   return rawTemplate;
@@ -4798,7 +4815,7 @@ function generateSourceProviderInputObject(input) {
   );
   const lines = [
     `${indent}// TODO: fill ${entity} source inputs for ${label}.`,
-    `${indent}// Inspect: deepline tools describe ${label} --json`
+    `${indent}// Inspect: deepline describe ${label}`
   ];
   for (const field of required) {
     lines.push(`${indent}// ${field}: ${exampleValueComment(field)},`);
@@ -4891,7 +4908,7 @@ function safeIdentifier(value) {
   return value.replace(/[^A-Za-z0-9_]+/g, "_");
 }
 function playInspectionComments(playRef, indent) {
-  return [`${indent}// Inspect: deepline plays describe ${playRef} --json`];
+  return [`${indent}// Inspect: deepline describe ${playRef}`];
 }
 function accessorExpression(base, field) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field) ? `${base}.${field}` : `${base}[${jsString(field)}]`;
@@ -5005,7 +5022,7 @@ function validateBootstrapRoutes(input) {
     }
     if (getterNamesFromTool(tool, "list").length === 0) {
       throw new PlayBootstrapValidationError(
-        `Cannot use ${tool.toolId} as a ${config.sourceEntity} source: it exposes no extracted list getters. Run: deepline tools describe ${tool.toolId} --json`
+        `Cannot use ${tool.toolId} as a ${config.sourceEntity} source: it exposes no extracted list getters. Run: deepline describe ${tool.toolId}`
       );
     }
   }
@@ -5034,7 +5051,7 @@ function validateBootstrapRoutes(input) {
       }
       if (getterNamesFromTool(tool, "value").length === 0) {
         throw new PlayBootstrapValidationError(
-          `Cannot use ${tool.toolId} as a ${finder}: it exposes no extracted value getters. Run: deepline tools describe ${tool.toolId} --json`
+          `Cannot use ${tool.toolId} as a ${finder}: it exposes no extracted value getters. Run: deepline describe ${tool.toolId}`
         );
       }
     }
@@ -6956,7 +6973,7 @@ function stringValue2(value) {
 }
 
 // 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`. Read tool-specific fields from `toolExecutionResult.toolResponse.rawV2` using the nesting shown in the response example, and use `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
+var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline describe <tool>`. Read tool-specific fields from `toolExecutionResult.toolResponse.rawV2` using the nesting shown in the response example, and use `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
 var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy, durable, and async-only. Use `.count()`, `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.length`, numeric indexing, spread, synchronous iteration, `.rows`, or `.toArray()`.";
 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 logs, metadata, and result-cache identity; terminal cache reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
@@ -9359,9 +9376,7 @@ function buildPlayReferenceNotFoundMessage(input) {
           `    deepline plays versions --name ${suggestion.reference} --json`
         );
       } else {
-        lines.push(
-          `    deepline plays describe ${suggestion.reference} --json`
-        );
+        lines.push(`    deepline describe ${suggestion.reference}`);
       }
     }
   }
@@ -9611,7 +9626,7 @@ function parseJsonInput(raw, flag = "--input") {
     parsed = JSON.parse(source);
   } catch {
     throw new DeeplineError(
-      `${flag} expects a valid JSON object or @input.json. A bare file path is not JSON.${flag === "--input" ? " Use the field names and run example from plays check <file> or plays describe <play>. --csv contacts.csv supplies input.csv only when the Play declares that field." : ""}`,
+      `${flag} expects a valid JSON object or @input.json. A bare file path is not JSON.${flag === "--input" ? " Use the field names and run example from plays check <file> or deepline describe <play>. --csv contacts.csv supplies input.csv only when the Play declares that field." : ""}`,
       void 0,
       "INVALID_JSON"
     );
@@ -16738,6 +16753,42 @@ function csvColumnLines(csvInput) {
     CSV_HEADER_MATCHING_NOTE
   ];
 }
+function describedPlay(play) {
+  const reference = formatPlayListReference(play);
+  const starter = play.cloneEditStarter ?? buildCloneEditStarter(play);
+  const csv = play.csvInput ?? {};
+  const headers = isRecord3(csv.defaultColumns) ? csv.defaultColumns : {};
+  const rowInputs = schemaFields(csv.rowInputSchema).map((field) => {
+    const header = [headers[field.name]].flat().filter((name) => name && name !== field.name).join(" or ");
+    return header ? {
+      ...field,
+      description: [field.description, `CSV header: ${header}`].filter(Boolean).join(" - ")
+    } : field;
+  });
+  const rowOutput = play.rowOutputSchema ?? {};
+  const added = isRecord3(rowOutput.addedColumns) ? rowOutput.addedColumns : {};
+  const rowOutputs = schemaFields(
+    Object.keys(added).length ? { properties: added } : rowOutput
+  ).map((field) => ({ ...field, required: true }));
+  return {
+    kind: play.ownerType === "deepline" ? "prebuilt_play" : "custom_play",
+    id: reference,
+    ...play.displayName && play.displayName !== play.name ? { displayName: play.displayName } : {},
+    ...play.description ? { description: play.description } : {},
+    guidance: [],
+    inputs: schemaFields(play.inputSchema),
+    outputs: schemaFields(play.outputSchema),
+    ...rowInputs.length ? { rowInputs } : {},
+    ...rowOutputs.length ? { rowOutputs } : {},
+    runner: {
+      via: "play",
+      reference,
+      // A CSV play's run command is built by the server around its columns.
+      ...play.csvInput ? { cli: play.runCommand } : {}
+    },
+    ...starter ? { source: starter.command } : {}
+  };
+}
 function printPlayDescription(play) {
   const reference = formatPlayListReference(play);
   const labels = [
@@ -16816,7 +16867,7 @@ function printPlayDescription(play) {
     );
   }
   printScheduledPlayCapacity(play.activeScheduledPlays);
-  console.log(`  Describe: deepline plays describe ${reference} --json`);
+  console.log(`  Describe: deepline describe ${reference}`);
   console.log(`  Run: ${play.runCommand}`);
   const cloneEditStarter = play.cloneEditStarter ?? buildCloneEditStarter(play);
   if (cloneEditStarter) {
@@ -16827,10 +16878,11 @@ function printPlayDescription(play) {
 function summarizePlayGrepResult(play) {
   const reference = formatPlayListReference(play);
   return {
-    name: play.displayName?.trim() || play.name,
+    name: play.name,
+    ...play.displayName ? { displayName: play.displayName } : {},
     reference,
     matches: play.matches ?? [],
-    describe: `deepline plays describe ${reference} --json`
+    describe: `deepline describe ${reference}`
   };
 }
 function formatPlayGrepMatches(matches) {
@@ -16861,7 +16913,7 @@ async function handlePlayGrep(args) {
 `
   );
   for (const result of results) {
-    console.log(result.name);
+    console.log(result.displayName?.trim() || result.name);
     const matches = formatPlayGrepMatches(result.matches);
     if (matches) console.log(`  Matched: ${matches}`);
     console.log(`  Describe: ${result.describe}`);
@@ -16902,7 +16954,7 @@ async function handlePlayDescribe(args) {
     })() : null;
     const next = [
       `deepline plays check ${playName}`,
-      ...definedName ? [`deepline plays describe <workspace>/${definedName}`] : []
+      ...definedName ? [`deepline describe <workspace>/${definedName}`] : []
     ];
     if (argsWantJson(args)) {
       printCompactJson({
@@ -17404,7 +17456,7 @@ Concepts:
 
 Run and retrieve results:
   1. Discover a Play: deepline plays search email --json
-     Inspect its input contract: deepline plays describe <play-name> --json
+     Inspect its input contract: deepline describe <play-name>
   2. Start and follow a new run: deepline plays run workflow.play.ts --csv contacts.csv
      This example requires input.csv. Use the selected Play's actual input fields.
      Run waits and shows progress by default; --no-wait returns immediately.
@@ -17439,7 +17491,7 @@ Authoring:
 
 Common commands:
   deepline search --type prebuilts email --json
-  deepline plays describe prebuilt/person-linkedin-to-email --json
+  deepline describe prebuilt/person-linkedin-to-email
   deepline plays check prebuilt/name-and-domain-to-email-waterfall-batch
   deepline plays run prebuilt/person-linkedin-to-email --input '{"linkedin_url":"..."}'
   deepline plays get prebuilt/person-linkedin-to-email --json
@@ -17829,7 +17881,7 @@ Notes:
 
 Examples:
   deepline plays grep email --json
-  deepline plays describe prebuilt/company-to-contact --json
+  deepline describe prebuilt/company-to-contact
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
     process.exitCode = await handlePlayGrep([
@@ -17837,7 +17889,7 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  play.command("describe [target]").usage("<target> [options]").description("Describe a play contract and how to run it.").addHelpText(
+  const describeCommand = play.command("describe [target]", { hidden: true }).usage("<target> [options]").description("Describe a play contract and how to run it.").addHelpText(
     "after",
     `
 Notes:
@@ -17855,11 +17907,33 @@ Examples:
   ).option("--compact", "Emit compact schemas").option(
     "--json [fields]",
     "JSON output; optionally select comma-separated dotted paths"
-  ).action(async (target, options) => {
-    process.exitCode = await handlePlayDescribe(
-      describeArgs(target, options)
-    );
-  });
+  );
+  addDescribeOptions(describeCommand, { json: false }).action(
+    async (target, options) => {
+      const ownView = () => handlePlayDescribe(describeArgs(target, options));
+      const [flagText] = [options.json].filter(
+        (value) => typeof value === "string"
+      );
+      const name = target || flagText;
+      const selectsFields = Boolean(target && flagText);
+      const own = !name || options.compact || selectsFields || looksLikeRunId(name) || isFileTarget(name) || looksLikeFilePath(name);
+      if (own) {
+        process.exitCode = await ownView();
+        return;
+      }
+      const { describeAnything } = await import("./describe-PAUHJF7H.mjs");
+      process.exitCode = await describeAnything(
+        name,
+        {
+          ...options,
+          kinds: ["prebuilts", "custom"],
+          json: Boolean(options.json)
+        },
+        // An unknown play keeps this command's suggestions.
+        ownView
+      );
+    }
+  );
   play.command("versions").description("List revisions for a named play.").addHelpText(
     "after",
     `
@@ -18794,68 +18868,70 @@ async function handlePlayShareUnpublish(args) {
   console.log(`Unpublished ${name}; the public page has been removed.`);
   return 0;
 }
+
 export {
-  PREBUILT_PLAY_TAG_KEYS,
-  assertDatasetHasExportableRows,
-  buildPlayCompletionTextLines,
-  buildRunActivityTextLines,
-  buildRunLaunch,
-  buildRunLogsText,
-  buildRunPackageTextLines,
-  buildStopAllDryRunTextLines,
-  clampJsonPreviewText,
-  compactPlayStatus,
-  csvColumnLines,
+  resolveDatasetByName,
+  loadPlayBundler,
+  parsePlayRunHeaderFlag,
+  writePlayRunIdFile,
+  preflightLocalFileInputs,
   describeSleepUntil,
-  exportPlayStatusRows,
-  formatPlaySandboxRuntimeWarning,
-  formatStepLabelFromNodeId,
   getFinalStatusFromLiveEvent,
+  formatStepLabelFromNodeId,
+  getStepTransitionLineFromLiveEvent,
   getProgressLinesFromLiveEvent,
+  shouldPrintPlayProgressLine,
   getRunningHeartbeatLine,
-  getStepTransitionLineFromLiveEvent,
+  waitForPlayCompletionByWatch,
+  startAndWaitForPlayCompletionByStream,
+  truncateErrorForDisplay,
+  clampJsonPreviewText,
+  withTerminalPlayIdentity,
+  compactPlayStatus,
+  buildRunActivityTextLines,
+  buildRunPackageTextLines,
+  buildRunLaunch,
+  buildPlayCompletionTextLines,
+  resolvePlayRunOutputStatus,
+  assertDatasetHasExportableRows,
+  exportPlayStatusRows,
+  parsePlayRunOptions,
+  parsePlayPublishOptions,
+  formatPlaySandboxRuntimeWarning,
   handlePlayCheck,
-  handlePlayDelete,
-  handlePlayDescribe,
-  handlePlayGet,
-  handlePlayGrep,
-  handlePlayList,
-  handlePlayPin,
-  handlePlayPublish,
-  handlePlayRestore,
   handlePlayRun,
-  handlePlaySave,
-  handlePlaySharePublish,
-  handlePlayShareRegenerate,
-  handlePlayShareStatus,
-  handlePlayShareUnpublish,
-  handlePlayShareUpdate,
-  handlePlayVersions,
-  handleRunEventSearch,
-  handleRunExport,
+  renderRunOverviewText,
   handleRunGet,
   handleRunLifecycleStatus,
+  handleRunsRerun,
+  handleRunsList,
+  handleRunTail,
   handleRunLogs,
+  selectRunLogTailPage,
+  handleRunEventSearch,
+  buildRunLogsText,
+  resolveRunStopState,
   handleRunStop,
+  buildStopAllDryRunTextLines,
   handleRunStopAll,
-  handleRunTail,
-  handleRunsList,
-  handleRunsRerun,
-  loadPlayBundler,
-  parsePlayPublishOptions,
-  parsePlayRunHeaderFlag,
-  parsePlayRunOptions,
-  preflightLocalFileInputs,
+  handleRunExport,
+  handlePlayGet,
+  handlePlayVersions,
+  PREBUILT_PLAY_TAG_KEYS,
+  handlePlayList,
+  handlePlayPin,
+  csvColumnLines,
+  describedPlay,
+  handlePlayGrep,
+  handlePlayDescribe,
+  handlePlaySave,
+  handlePlayPublish,
+  handlePlayDelete,
+  handlePlayRestore,
   registerPlayCommands,
-  renderRunOverviewText,
-  resolveDatasetByName,
-  resolvePlayRunOutputStatus,
-  resolveRunStopState,
-  selectRunLogTailPage,
-  shouldPrintPlayProgressLine,
-  startAndWaitForPlayCompletionByStream,
-  truncateErrorForDisplay,
-  waitForPlayCompletionByWatch,
-  withTerminalPlayIdentity,
-  writePlayRunIdFile
+  handlePlayShareStatus,
+  handlePlaySharePublish,
+  handlePlayShareUpdate,
+  handlePlayShareRegenerate,
+  handlePlayShareUnpublish
 };

package/dist/cli/{chunk-W7INSYJS.js → chunk-IALPYID6.js}

@@ -3,7 +3,7 @@
 var _chunk3KC45UVFjs = require('./chunk-3KC45UVF.js');
 
 
-var _chunkZDO3TO3Mjs = require('./chunk-ZDO3TO3M.js');
+var _chunkOJ243ZA5js = require('./chunk-OJ243ZA5.js');
 
 
 
@@ -54,7 +54,7 @@ function buildPlayContractCompatibility(input) {
     artifactVersion: PLAY_ARTIFACT_VERSION,
     runtimeBackend: _nullishCoalesce(_optionalChain([input, 'optionalAccess', _ => _.runtimeBackend]), () => ( null)),
     toolErrorSchemaVersion: _nullishCoalesce(_optionalChain([input, 'optionalAccess', _2 => _2.toolErrorSchemaVersion]), () => ( _chunk7P5AA3SNjs.TOOL_EXECUTION_ERROR_SCHEMA_VERSION)),
-    authoringContractEdition: _nullishCoalesce(_optionalChain([input, 'optionalAccess', _3 => _3.authoringContractEdition]), () => ( _chunkZDO3TO3Mjs.PLAY_AUTHORING_CONTRACT_EDITION)),
+    authoringContractEdition: _nullishCoalesce(_optionalChain([input, 'optionalAccess', _3 => _3.authoringContractEdition]), () => ( _chunkOJ243ZA5js.PLAY_AUTHORING_CONTRACT_EDITION)),
     toolResponseContract: _nullishCoalesce(_optionalChain([input, 'optionalAccess', _4 => _4.toolResponseContract]), () => ( _chunkS6R3OX7Bjs.RAW_V2_TOOL_RESPONSE_CONTRACT)),
     toolResponseReceiptRevision: _chunkS6R3OX7Bjs.normalizeToolResponseReceiptRevision.call(void 0, 
       _nullishCoalesce(_optionalChain([input, 'optionalAccess', _5 => _5.toolResponseReceiptRevision]), () => ( _chunkS6R3OX7Bjs.RAW_V2_TOOL_RESPONSE_RECEIPT_REVISION))
@@ -2729,7 +2729,7 @@ async function bundlePlayFile(filePath, options) {
     analysis.graphHash = sha256(
       `${analysis.graphHash}
 entry-export:${exportName}
-authoring-contract-edition:${_chunkZDO3TO3Mjs.PLAY_AUTHORING_CONTRACT_EDITION}`
+authoring-contract-edition:${_chunkOJ243ZA5js.PLAY_AUTHORING_CONTRACT_EDITION}`
     );
     const sourceFiles = Object.fromEntries(
       Object.entries(analysis.sourceFiles).map(([sourcePath, sourceCode]) => [

package/dist/cli/{chunk-ICZB4GTY.mjs → chunk-MK4K5MQU.mjs}

@@ -1,13 +1,13 @@
 import {
   DeeplineClient
-} from "./chunk-5OVNL6LS.mjs";
+} from "./chunk-NWFE4PGX.mjs";
 import {
   printCommandEnvelope
-} from "./chunk-SPUTBCUR.mjs";
+} from "./chunk-ZH7KTVAB.mjs";
 import {
   resolveConfig,
   sdkCliStateDirPath
-} from "./chunk-Q3LYQTSO.mjs";
+} from "./chunk-WPTUKXIF.mjs";
 
 // src/cli/search-ref.ts
 import { mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -75,6 +75,21 @@ function addSearchOptions(command) {
     "What you are trying to accomplish: input you have -> result you need"
   ).option("--limit <count>", "Maximum ranked results to return (1-50)").option("--offset <count>", "Zero-based ranked result offset").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--json", "Emit JSON output instead of the readable default");
 }
+function pointAtDescribe(result) {
+  const old = /`deepline (tools|plays) describe [^`]*`/;
+  const render = result.render;
+  for (const section of render?.sections ?? []) {
+    if (!section.lines?.some((line) => old.test(line))) continue;
+    section.lines = [
+      "Run `deepline describe <id>` before executing a tool or running a play.",
+      ...section.lines.filter((line) => !old.test(line))
+    ];
+  }
+  const templates = result.commandTemplates;
+  for (const template of Object.values(templates ?? {})) {
+    if (template.describe) template.describe = "deepline describe <id>";
+  }
+}
 async function runSearch(queryInput, options, types, exclude = []) {
   const query = queryInput?.trim() ?? "";
   const searchTerms = options.searchTerms ?? options.search_terms;
@@ -95,6 +110,7 @@ async function runSearch(queryInput, options, types, exclude = []) {
     includeSearchDebug: Boolean(options.includeSearchDebug)
   });
   if (searchRef) rememberSearchRef(searchRef);
+  pointAtDescribe(result);
   printCommandEnvelope(result, {
     json: options.json === true
   });
@@ -185,6 +201,10 @@ Examples:
 
 export {
   recentSearchRef,
+  SEARCH_TYPES,
+  parseTypes,
+  appendCsv,
+  pointAtDescribe,
   registerDeprecatedSearchCommand,
   registerSearchCommand
 };

package/dist/cli/{chunk-WB6Z2Q44.mjs → chunk-N5V2SBB2.mjs}

@@ -89,6 +89,7 @@ var PLAY_SQL_LISTENER_WHERE_OPERATOR_SET = new Set(
 );
 var PLAY_AUTHORING_BINDING_FIELDS = {
   root: [
+    "displayName",
     "billing",
     "compatibility",
     "cron",
@@ -185,6 +186,22 @@ var SqlListenerFilterScalarSchema = Type.Union([
   Type.Null()
 ]);
 var PLAY_AUTHORING_FIELD_REGISTRY = {
+  displayName: {
+    schema: Type.String(),
+    fixtures: {
+      valid: "Find verified emails",
+      invalid: 42,
+      absent: void 0,
+      unresolved: { expression: "displayName" },
+      edition1: "Legacy play"
+    },
+    referenceType: "string",
+    required: false,
+    resolution: "static-required",
+    issueCode: "play_authoring_binding_invalid",
+    description: "Optional human-readable Play name; empty uses the derived identifier.",
+    errorMessage: "displayName must be a static string."
+  },
   description: {
     schema: Type.String({ minLength: 1 }),
     fixtures: {
@@ -1532,6 +1549,7 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "};",
   "export type PlayCronInput<TInput> = TInput extends readonly unknown[] ? never : TInput extends object ? TInput : never;",
   "export type PlayBindings<TInput = Record<string, unknown>> = {",
+  `  displayName?: ${cloudReferenceType("displayName")};`,
   `  description?: ${cloudReferenceType("description")};`,
   `  compatibility?: { toolErrorSchemaVersion?: ${cloudReferenceType("compatibility.toolErrorSchemaVersion")}; toolResponseReceiptRevision?: ${cloudReferenceType("compatibility.toolResponseReceiptRevision")} };`,
   `  inline?: ${cloudReferenceType("inline")};`,
@@ -1610,7 +1628,7 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "  log(message: string, options?: { level?: 'debug' | 'info' | 'warn' | 'error'; context?: Readonly<Record<string, string | number | boolean>> }): void;",
   `  sleep(ms: ${cloudReferenceType("ctx.sleep.ms")}): Promise<void>;`,
   "}",
-  "export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = { id: string; description?: string; input: PlayInputContract<TInput>; run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>; bindings?: PlayBindings<TInput>; billing?: PlayBindings<TInput>['billing']; runtime?: PlayBindings<TInput>['runtime']; compatibility?: PlayBindings<TInput>['compatibility'] };",
+  "export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = { id: string; displayName?: string; description?: string; input: PlayInputContract<TInput>; run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>; bindings?: PlayBindings<TInput>; billing?: PlayBindings<TInput>['billing']; runtime?: PlayBindings<TInput>['runtime']; compatibility?: PlayBindings<TInput>['compatibility'] };",
   "export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>) & { readonly name: string; readonly __inputType?: TInput; readonly __outputType?: TOutput; readonly bindings?: PlayBindings<TInput>; readonly runtime?: PlayBindings<TInput>['runtime']; readonly compatibility?: PlayBindings<TInput>['compatibility'] };",
   "export type PlayHandlerInput<THandler> = THandler extends (context: DeeplinePlayRuntimeContext, input: infer TInput) => Promise<PlayReturnObject> ? TInput : never;",
   "export type PlayHandlerOutput<THandler> = THandler extends (context: DeeplinePlayRuntimeContext, input: unknown) => Promise<infer TOutput extends PlayReturnObject> ? TOutput : never;"

package/dist/cli/{chunk-TBX7AA7Y.mjs → chunk-NJNYWVEF.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-GAMFK2ZP.mjs";
 import {
   printCommandEnvelope
-} from "./chunk-SPUTBCUR.mjs";
+} from "./chunk-ZH7KTVAB.mjs";
 import {
   DEFAULT_SKILL_AGENTS,
   KNOWN_SKILL_AGENTS,
@@ -22,7 +22,7 @@ import {
   sdkCliStateDirPath,
   skillsAgentPathSegment,
   writeSdkSkillsLocalVersion
-} from "./chunk-Q3LYQTSO.mjs";
+} from "./chunk-WPTUKXIF.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";

package/dist/cli/{chunk-QJA6SJHA.mjs → chunk-NMZPK7LM.mjs}

@@ -1,6 +1,6 @@
 import {
   resolveShellSpawn
-} from "./chunk-TBX7AA7Y.mjs";
+} from "./chunk-NJNYWVEF.mjs";
 
 // src/cli/npm-script-policy.ts
 import { spawnSync } from "child_process";

package/dist/cli/{chunk-5OVNL6LS.mjs → chunk-NWFE4PGX.mjs}

@@ -14,7 +14,7 @@ import {
   RETAINED_PIPELINE_RECEIVERS_HEADER,
   RUNTIME_ENVIRONMENT_TOKEN_HEADER,
   resolveConfig
-} from "./chunk-Q3LYQTSO.mjs";
+} from "./chunk-WPTUKXIF.mjs";
 import {
   PLAY_RUNTIME_BACKENDS,
   RAW_V2_TOOL_RESPONSE_CONTRACT,