deepline 0.2.70 → 0.2.71

package/dist/bundling-sources/sdk/src/client.ts

@@ -1156,16 +1156,16 @@ function isPrebuiltPlayDescription(
 function preferPrebuiltPlayDescriptions<T extends PlayDescription>(
   plays: T[],
 ): T[] {
-  const prebuilt: T[] = [];
-  const owned: T[] = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays
+    .map((play, index) => ({ play, index }))
+    .sort(
+      (left, right) =>
+        Number(right.play.pinned) - Number(left.play.pinned) ||
+        Number(isPrebuiltPlayDescription(right.play)) -
+          Number(isPrebuiltPlayDescription(left.play)) ||
+        left.index - right.index,
+    )
+    .map(({ play }) => play);
 }
 
 function isPlayRunPackage(value: unknown): value is PlayRunPackage {
@@ -1775,6 +1775,8 @@ export class DeeplineClient {
       ...(play.reference ? { reference: play.reference } : {}),
       ...(play.displayName ? { displayName: play.displayName } : {}),
       ...(description ? { description } : {}),
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -3778,9 +3780,24 @@ export class DeeplineClient {
     origin?: 'prebuilt' | 'owned';
     grep?: string;
     grepMode?: 'all' | 'any' | 'phrase';
+    categories?: string | string[];
+    includeToolCategories?: boolean;
+    includeArchived?: boolean;
   }): Promise<PlayListItem[]> {
     const params = new URLSearchParams();
     if (options?.origin) params.set('origin', options.origin);
+    if (options?.categories) {
+      params.set(
+        'categories',
+        Array.isArray(options.categories)
+          ? options.categories.join(',')
+          : options.categories,
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set('include_tool_categories', '1');
+    }
+    if (options?.includeArchived) params.set('include_archived', '1');
     if (options?.grep?.trim()) {
       params.set('grep', options.grep.trim());
       params.set('grep_mode', options.grepMode ?? 'all');
@@ -3793,6 +3810,16 @@ export class DeeplineClient {
     return response.plays ?? [];
   }
 
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(
+    playName: string,
+    pinned: boolean,
+  ): Promise<{ name: string; pinned: boolean }> {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned,
+    });
+  }
+
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings(): Promise<ProductNotificationSettings> {
     return this.http.get('/api/v2/settings/notifications');

package/dist/bundling-sources/sdk/src/release.ts

@@ -183,7 +183,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.70',
+  version: '0.2.71',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/sdk/src/types.ts

@@ -1010,6 +1010,10 @@ export interface PlayDefinitionDetail {
   name: string;
   /** Human-friendly display name for UI surfaces. */
   displayName?: string;
+  /** Whether this Play sorts before unpinned Plays. */
+  pinned?: boolean;
+  /** Canonical categories declared by tools used in this Play. */
+  toolCategories?: string[];
   /** Whether this entry comes from the Deepline prebuilt registry or the org-owned catalog. */
   origin?: 'prebuilt' | 'owned';
   /** Ownership class used for permissions and badges. */
@@ -1064,6 +1068,8 @@ export interface PlayListItem {
   name: string;
   displayName?: string;
   description?: string | null;
+  pinned?: boolean;
+  toolCategories?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   ownerSlug?: string;
@@ -1135,6 +1141,8 @@ export interface PlayDescription {
   reference?: string;
   displayName?: string;
   description?: string | null;
+  pinned?: boolean;
+  toolCategories?: string[];
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   canEdit?: boolean;

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -38,7 +38,7 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     changed:
       'Materializes the declared input schema in the admitted snapshot so launch never reparses current source.',
     compatibilityOwner: 'Plays Runtime',
-    newWritesEnd: null,
+    newWritesEnd: '2026-08-19',
     readerRemoval: null,
   },
 ] as const;

package/dist/bundling-sources/shared_libs/plays/enrich-play-compiler.ts

@@ -691,10 +691,20 @@ export function compileEnrichConfigToPlaySource(
   const runOptionsSource = options.failFast
     ? `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart), onRowError: 'fail' as const }`
     : `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart) }`;
+  const describedColumns = config.commands
+    .filter((command) => isWaterfall(command) || !command.disabled)
+    .map((command) =>
+      (isWaterfall(command) ? command.with_waterfall : command.alias)
+        .replace(/[_-]+/g, ' ')
+        .trim(),
+    )
+    .filter(Boolean)
+    .slice(0, 3);
+  const generatedDescription = describedColumns.length
+    ? `Enrich CSV rows with ${describedColumns.join(', ')}.`
+    : 'Prepare CSV rows for enrichment.';
   const playOptionsSource = [
-    `description: ${stringLiteral(
-      'Read a CSV file, run the configured Deepline enrich commands, and return enriched rows.',
-    )}`,
+    `description: ${stringLiteral(generatedDescription)}`,
     ...(options.maxCreditsPerRun === undefined
       ? []
       : [`billing: { maxCreditsPerRun: ${String(options.maxCreditsPerRun)} }`]),

package/dist/bundling-sources/shared_libs/plays/tool-category-descriptions.ts

@@ -49,3 +49,15 @@ export const TOOL_CATEGORY_DESCRIPTIONS: Readonly<Record<string, string>> = {
 export function describeToolCategory(category: string): string | null {
   return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
 }
+
+/** Human-readable label for a canonical tool-category slug. */
+export function formatToolCategoryLabel(category: string): string {
+  const normalized = category
+    .trim()
+    .replace(/[_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+  return normalized
+    ? `${normalized[0]?.toUpperCase() ?? ''}${normalized.slice(1)}`
+    : '';
+}

package/dist/cli/index.js

@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.70",
+  version: "0.2.71",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3983,16 +3983,9 @@ function isPrebuiltPlayDescription(play) {
   return play.origin === "prebuilt" || play.ownerType === "deepline";
 }
 function preferPrebuiltPlayDescriptions(plays) {
-  const prebuilt = [];
-  const owned = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays.map((play, index) => ({ play, index })).sort(
+    (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
+  ).map(({ play }) => play);
 }
 function isPlayRunPackage(value) {
   return Boolean(
@@ -4339,6 +4332,8 @@ var DeeplineClient = class {
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -5837,6 +5832,16 @@ var DeeplineClient = class {
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
+    if (options?.categories) {
+      params.set(
+        "categories",
+        Array.isArray(options.categories) ? options.categories.join(",") : options.categories
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set("include_tool_categories", "1");
+    }
+    if (options?.includeArchived) params.set("include_archived", "1");
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
       params.set("grep_mode", options.grepMode ?? "all");
@@ -5848,6 +5853,12 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(playName, pinned) {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned
+    });
+  }
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings() {
     return this.http.get("/api/v2/settings/notifications");
@@ -22848,6 +22859,29 @@ function resolvePlayCheckExportNames(sourceCode) {
   if (!exports2 || exports2.length === 0) return [PLAY_DEFAULT_EXPORT];
   return exports2.map((entry) => entry.name);
 }
+function artifactForProductionCompatibilityCheck(artifact) {
+  const rawEdition = process.env.DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION?.trim();
+  if (!rawEdition) return artifact;
+  if (!/^\d+$/.test(rawEdition)) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const edition = Number(rawEdition);
+  if (edition < 1) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const compatibility = isRecord10(artifact.compatibility) ? artifact.compatibility : {};
+  return {
+    ...artifact,
+    compatibility: {
+      ...compatibility,
+      authoringContractEdition: edition
+    }
+  };
+}
 async function checkOneExportedPlay(input2) {
   const { absolutePlayPath, sourceCode, exportName } = input2;
   const fallbackName = extractPlayName(sourceCode, absolutePlayPath);
@@ -22887,7 +22921,7 @@ async function checkOneExportedPlay(input2) {
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
     description: graph.root.playDescription ?? void 0,
-    artifact: graph.root.artifact,
+    artifact: artifactForProductionCompatibilityCheck(graph.root.artifact),
     ...exportName === PLAY_DEFAULT_EXPORT ? {} : { exportName },
     ...importedPlays.length > 0 ? { importedPlays } : {},
     ...integrationMode ? { integrationMode } : {}
@@ -24073,7 +24107,12 @@ async function handlePlayVersions(args) {
 async function handlePlayList(args) {
   const jsonOutput = argsWantJson(args);
   const client2 = new DeeplineClient();
-  const plays = await client2.listPlays();
+  const categoriesIndex = args.indexOf("--categories");
+  const categories = categoriesIndex >= 0 ? args[categoriesIndex + 1]?.trim() : void 0;
+  const plays = await client2.listPlays({
+    categories,
+    includeToolCategories: true
+  });
   if (jsonOutput) {
     process.stdout.write(`${JSON.stringify(plays)}
 `);
@@ -24084,6 +24123,8 @@ async function handlePlayList(args) {
 `);
   for (const play of plays) {
     const flags = [
+      play.pinned ? "pinned" : null,
+      ...(play.toolCategories ?? []).map((category) => `category:${category}`),
       play.origin === "prebuilt" || play.ownerType === "deepline" ? "prebuilt" : "owned",
       play.canEdit ? "editable" : "readonly",
       play.isDraftDirty ? "draft-dirty" : null
@@ -24113,6 +24154,36 @@ async function handlePlayList(args) {
   }
   return 0;
 }
+async function handlePlayPin(args, pinned) {
+  const target = args.find((arg) => !arg.startsWith("-"))?.trim();
+  const jsonOutput = argsWantJson(args);
+  const dryRun = args.includes("--dry-run");
+  if (!target) {
+    console.error(
+      `Usage: deepline plays ${pinned ? "pin" : "unpin"} <play> [--dry-run] [--json]`
+    );
+    return 2;
+  }
+  const parsedTarget = parseReferencedPlayTarget2(target);
+  if (parsedTarget.ownerSlug) {
+    console.error(
+      `deepline plays ${pinned ? "pin" : "unpin"} accepts an org-owned Play identifier without a namespace. Use "${parsedTarget.unqualifiedPlayName}" instead of "${target}".`
+    );
+    return 2;
+  }
+  const name = parsedTarget.playName;
+  const plan = { name, pinned, dryRun };
+  if (dryRun) {
+    process.stdout.write(`${JSON.stringify(plan)}
+`);
+    return 0;
+  }
+  const result = await new DeeplineClient().setPlayPinned(name, pinned);
+  if (jsonOutput) process.stdout.write(`${JSON.stringify(result)}
+`);
+  else console.log(`${result.pinned ? "Pinned" : "Unpinned"} ${result.name}.`);
+  return 0;
+}
 function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
@@ -24147,6 +24218,12 @@ function printPlayDescription(play) {
   if (play.description) {
     console.log(`  Description: ${play.description}`);
   }
+  if (play.pinned) {
+    console.log("  Pinned: yes");
+  }
+  if (play.toolCategories?.length) {
+    console.log(`  Tool categories: ${play.toolCategories.join(", ")}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -24252,6 +24329,8 @@ function summarizePlayListItemForCli(play, options) {
     name: play.name,
     ...play.reference ? { reference: play.reference } : {},
     ...play.displayName ? { displayName: play.displayName } : {},
+    pinned: Boolean(play.pinned),
+    toolCategories: play.toolCategories ?? [],
     origin: play.origin,
     ownerType: play.ownerType,
     canEdit: play.canEdit,
@@ -24382,6 +24461,7 @@ async function handlePlayGrep(args) {
         origin: play.origin,
         ownerType: play.ownerType,
         aliases: play.aliases,
+        toolCategories: play.toolCategories,
         inputSchema: play.inputSchema,
         outputSchema: play.outputSchema
       },
@@ -25045,11 +25125,35 @@ Examples:
   deepline plays list
   deepline plays search email --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+    "--categories <categories>",
+    "Filter by comma-separated canonical tool categories"
+  ).action(async (options) => {
     process.exitCode = await handlePlayList([
+      ...options.categories ? ["--categories", options.categories] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
+  play.command("pin <target>").description("Pin an org-owned play to the top of play listings.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      true
+    );
+  });
+  play.command("unpin <target>").description("Remove an org-owned play from the pinned group.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      false
+    );
+  });
   const addPlaySearchCommand = (command) => command.description("Search Deepline prebuilt plays by task.").option(
     "--prebuilt",
     "Only show Deepline-managed prebuilt plays (default)"
@@ -26404,10 +26508,12 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
   const metadataColumnSource = renderMetadataColumnStep(config);
   const generatedAliases = collectGeneratedAliases(config.commands);
   const runOptionsSource = options.failFast ? `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart), onRowError: 'fail' as const }` : `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart) }`;
+  const describedColumns = config.commands.filter((command) => isWaterfall(command) || !command.disabled).map(
+    (command) => (isWaterfall(command) ? command.with_waterfall : command.alias).replace(/[_-]+/g, " ").trim()
+  ).filter(Boolean).slice(0, 3);
+  const generatedDescription = describedColumns.length ? `Enrich CSV rows with ${describedColumns.join(", ")}.` : "Prepare CSV rows for enrichment.";
   const playOptionsSource = [
-    `description: ${stringLiteral(
-      "Read a CSV file, run the configured Deepline enrich commands, and return enriched rows."
-    )}`,
+    `description: ${stringLiteral(generatedDescription)}`,
     ...options.maxCreditsPerRun === void 0 ? [] : [`billing: { maxCreditsPerRun: ${String(options.maxCreditsPerRun)} }`]
   ].join(", ");
   const body = [

package/dist/cli/index.mjs

@@ -1030,7 +1030,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.70",
+  version: "0.2.71",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3969,16 +3969,9 @@ function isPrebuiltPlayDescription(play) {
   return play.origin === "prebuilt" || play.ownerType === "deepline";
 }
 function preferPrebuiltPlayDescriptions(plays) {
-  const prebuilt = [];
-  const owned = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays.map((play, index) => ({ play, index })).sort(
+    (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
+  ).map(({ play }) => play);
 }
 function isPlayRunPackage(value) {
   return Boolean(
@@ -4325,6 +4318,8 @@ var DeeplineClient = class {
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -5823,6 +5818,16 @@ var DeeplineClient = class {
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
+    if (options?.categories) {
+      params.set(
+        "categories",
+        Array.isArray(options.categories) ? options.categories.join(",") : options.categories
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set("include_tool_categories", "1");
+    }
+    if (options?.includeArchived) params.set("include_archived", "1");
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
       params.set("grep_mode", options.grepMode ?? "all");
@@ -5834,6 +5839,12 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(playName, pinned) {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned
+    });
+  }
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings() {
     return this.http.get("/api/v2/settings/notifications");
@@ -22900,6 +22911,29 @@ function resolvePlayCheckExportNames(sourceCode) {
   if (!exports || exports.length === 0) return [PLAY_DEFAULT_EXPORT];
   return exports.map((entry) => entry.name);
 }
+function artifactForProductionCompatibilityCheck(artifact) {
+  const rawEdition = process.env.DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION?.trim();
+  if (!rawEdition) return artifact;
+  if (!/^\d+$/.test(rawEdition)) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const edition = Number(rawEdition);
+  if (edition < 1) {
+    throw new Error(
+      "DEEPLINE_PROD_CHECK_AUTHORING_CONTRACT_EDITION must be a positive integer."
+    );
+  }
+  const compatibility = isRecord10(artifact.compatibility) ? artifact.compatibility : {};
+  return {
+    ...artifact,
+    compatibility: {
+      ...compatibility,
+      authoringContractEdition: edition
+    }
+  };
+}
 async function checkOneExportedPlay(input2) {
   const { absolutePlayPath, sourceCode, exportName } = input2;
   const fallbackName = extractPlayName(sourceCode, absolutePlayPath);
@@ -22939,7 +22973,7 @@ async function checkOneExportedPlay(input2) {
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
     description: graph.root.playDescription ?? void 0,
-    artifact: graph.root.artifact,
+    artifact: artifactForProductionCompatibilityCheck(graph.root.artifact),
     ...exportName === PLAY_DEFAULT_EXPORT ? {} : { exportName },
     ...importedPlays.length > 0 ? { importedPlays } : {},
     ...integrationMode ? { integrationMode } : {}
@@ -24125,7 +24159,12 @@ async function handlePlayVersions(args) {
 async function handlePlayList(args) {
   const jsonOutput = argsWantJson(args);
   const client2 = new DeeplineClient();
-  const plays = await client2.listPlays();
+  const categoriesIndex = args.indexOf("--categories");
+  const categories = categoriesIndex >= 0 ? args[categoriesIndex + 1]?.trim() : void 0;
+  const plays = await client2.listPlays({
+    categories,
+    includeToolCategories: true
+  });
   if (jsonOutput) {
     process.stdout.write(`${JSON.stringify(plays)}
 `);
@@ -24136,6 +24175,8 @@ async function handlePlayList(args) {
 `);
   for (const play of plays) {
     const flags = [
+      play.pinned ? "pinned" : null,
+      ...(play.toolCategories ?? []).map((category) => `category:${category}`),
       play.origin === "prebuilt" || play.ownerType === "deepline" ? "prebuilt" : "owned",
       play.canEdit ? "editable" : "readonly",
       play.isDraftDirty ? "draft-dirty" : null
@@ -24165,6 +24206,36 @@ async function handlePlayList(args) {
   }
   return 0;
 }
+async function handlePlayPin(args, pinned) {
+  const target = args.find((arg) => !arg.startsWith("-"))?.trim();
+  const jsonOutput = argsWantJson(args);
+  const dryRun = args.includes("--dry-run");
+  if (!target) {
+    console.error(
+      `Usage: deepline plays ${pinned ? "pin" : "unpin"} <play> [--dry-run] [--json]`
+    );
+    return 2;
+  }
+  const parsedTarget = parseReferencedPlayTarget2(target);
+  if (parsedTarget.ownerSlug) {
+    console.error(
+      `deepline plays ${pinned ? "pin" : "unpin"} accepts an org-owned Play identifier without a namespace. Use "${parsedTarget.unqualifiedPlayName}" instead of "${target}".`
+    );
+    return 2;
+  }
+  const name = parsedTarget.playName;
+  const plan = { name, pinned, dryRun };
+  if (dryRun) {
+    process.stdout.write(`${JSON.stringify(plan)}
+`);
+    return 0;
+  }
+  const result = await new DeeplineClient().setPlayPinned(name, pinned);
+  if (jsonOutput) process.stdout.write(`${JSON.stringify(result)}
+`);
+  else console.log(`${result.pinned ? "Pinned" : "Unpinned"} ${result.name}.`);
+  return 0;
+}
 function parsePlaySearchOptions(args) {
   const query = args[0]?.trim();
   if (!query) {
@@ -24199,6 +24270,12 @@ function printPlayDescription(play) {
   if (play.description) {
     console.log(`  Description: ${play.description}`);
   }
+  if (play.pinned) {
+    console.log("  Pinned: yes");
+  }
+  if (play.toolCategories?.length) {
+    console.log(`  Tool categories: ${play.toolCategories.join(", ")}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -24304,6 +24381,8 @@ function summarizePlayListItemForCli(play, options) {
     name: play.name,
     ...play.reference ? { reference: play.reference } : {},
     ...play.displayName ? { displayName: play.displayName } : {},
+    pinned: Boolean(play.pinned),
+    toolCategories: play.toolCategories ?? [],
     origin: play.origin,
     ownerType: play.ownerType,
     canEdit: play.canEdit,
@@ -24434,6 +24513,7 @@ async function handlePlayGrep(args) {
         origin: play.origin,
         ownerType: play.ownerType,
         aliases: play.aliases,
+        toolCategories: play.toolCategories,
         inputSchema: play.inputSchema,
         outputSchema: play.outputSchema
       },
@@ -25097,11 +25177,35 @@ Examples:
   deepline plays list
   deepline plays search email --json
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+    "--categories <categories>",
+    "Filter by comma-separated canonical tool categories"
+  ).action(async (options) => {
     process.exitCode = await handlePlayList([
+      ...options.categories ? ["--categories", options.categories] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
+  play.command("pin <target>").description("Pin an org-owned play to the top of play listings.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      true
+    );
+  });
+  play.command("unpin <target>").description("Remove an org-owned play from the pinned group.").option("--dry-run", "Print the planned change without saving it").option("--json", "Emit JSON output").action(async (target, options) => {
+    process.exitCode = await handlePlayPin(
+      [
+        target,
+        ...options.dryRun ? ["--dry-run"] : [],
+        ...options.json ? ["--json"] : []
+      ],
+      false
+    );
+  });
   const addPlaySearchCommand = (command) => command.description("Search Deepline prebuilt plays by task.").option(
     "--prebuilt",
     "Only show Deepline-managed prebuilt plays (default)"
@@ -26456,10 +26560,12 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
   const metadataColumnSource = renderMetadataColumnStep(config);
   const generatedAliases = collectGeneratedAliases(config.commands);
   const runOptionsSource = options.failFast ? `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart), onRowError: 'fail' as const }` : `{ key: (row, index) => __dlEnrichRowKey(row, index + rowStart) }`;
+  const describedColumns = config.commands.filter((command) => isWaterfall(command) || !command.disabled).map(
+    (command) => (isWaterfall(command) ? command.with_waterfall : command.alias).replace(/[_-]+/g, " ").trim()
+  ).filter(Boolean).slice(0, 3);
+  const generatedDescription = describedColumns.length ? `Enrich CSV rows with ${describedColumns.join(", ")}.` : "Prepare CSV rows for enrichment.";
   const playOptionsSource = [
-    `description: ${stringLiteral(
-      "Read a CSV file, run the configured Deepline enrich commands, and return enriched rows."
-    )}`,
+    `description: ${stringLiteral(generatedDescription)}`,
     ...options.maxCreditsPerRun === void 0 ? [] : [`billing: { maxCreditsPerRun: ${String(options.maxCreditsPerRun)} }`]
   ].join(", ");
   const body = [

package/dist/index.d.mts

@@ -1108,6 +1108,10 @@ interface PlayDefinitionDetail {
     name: string;
     /** Human-friendly display name for UI surfaces. */
     displayName?: string;
+    /** Whether this Play sorts before unpinned Plays. */
+    pinned?: boolean;
+    /** Canonical categories declared by tools used in this Play. */
+    toolCategories?: string[];
     /** Whether this entry comes from the Deepline prebuilt registry or the org-owned catalog. */
     origin?: 'prebuilt' | 'owned';
     /** Ownership class used for permissions and badges. */
@@ -1161,6 +1165,8 @@ interface PlayListItem {
     name: string;
     displayName?: string;
     description?: string | null;
+    pinned?: boolean;
+    toolCategories?: string[];
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -1240,6 +1246,8 @@ interface PlayDescription {
     reference?: string;
     displayName?: string;
     description?: string | null;
+    pinned?: boolean;
+    toolCategories?: string[];
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -3278,7 +3286,15 @@ declare class DeeplineClient {
         origin?: 'prebuilt' | 'owned';
         grep?: string;
         grepMode?: 'all' | 'any' | 'phrase';
+        categories?: string | string[];
+        includeToolCategories?: boolean;
+        includeArchived?: boolean;
     }): Promise<PlayListItem[]>;
+    /** Set whether an org-owned Play sorts before unpinned Plays. */
+    setPlayPinned(playName: string, pinned: boolean): Promise<{
+        name: string;
+        pinned: boolean;
+    }>;
     /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
     getNotificationSettings(): Promise<ProductNotificationSettings>;
     /** Start the Slack OAuth flow required by product notifications. */

package/dist/index.d.ts

@@ -1108,6 +1108,10 @@ interface PlayDefinitionDetail {
     name: string;
     /** Human-friendly display name for UI surfaces. */
     displayName?: string;
+    /** Whether this Play sorts before unpinned Plays. */
+    pinned?: boolean;
+    /** Canonical categories declared by tools used in this Play. */
+    toolCategories?: string[];
     /** Whether this entry comes from the Deepline prebuilt registry or the org-owned catalog. */
     origin?: 'prebuilt' | 'owned';
     /** Ownership class used for permissions and badges. */
@@ -1161,6 +1165,8 @@ interface PlayListItem {
     name: string;
     displayName?: string;
     description?: string | null;
+    pinned?: boolean;
+    toolCategories?: string[];
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -1240,6 +1246,8 @@ interface PlayDescription {
     reference?: string;
     displayName?: string;
     description?: string | null;
+    pinned?: boolean;
+    toolCategories?: string[];
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -3278,7 +3286,15 @@ declare class DeeplineClient {
         origin?: 'prebuilt' | 'owned';
         grep?: string;
         grepMode?: 'all' | 'any' | 'phrase';
+        categories?: string | string[];
+        includeToolCategories?: boolean;
+        includeArchived?: boolean;
     }): Promise<PlayListItem[]>;
+    /** Set whether an org-owned Play sorts before unpinned Plays. */
+    setPlayPinned(playName: string, pinned: boolean): Promise<{
+        name: string;
+        pinned: boolean;
+    }>;
     /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
     getNotificationSettings(): Promise<ProductNotificationSettings>;
     /** Start the Slack OAuth flow required by product notifications. */

package/dist/index.js

@@ -780,7 +780,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.70",
+  version: "0.2.71",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3719,16 +3719,9 @@ function isPrebuiltPlayDescription(play) {
   return play.origin === "prebuilt" || play.ownerType === "deepline";
 }
 function preferPrebuiltPlayDescriptions(plays) {
-  const prebuilt = [];
-  const owned = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays.map((play, index) => ({ play, index })).sort(
+    (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
+  ).map(({ play }) => play);
 }
 function isPlayRunPackage(value) {
   return Boolean(
@@ -4075,6 +4068,8 @@ var DeeplineClient = class {
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -5573,6 +5568,16 @@ var DeeplineClient = class {
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
+    if (options?.categories) {
+      params.set(
+        "categories",
+        Array.isArray(options.categories) ? options.categories.join(",") : options.categories
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set("include_tool_categories", "1");
+    }
+    if (options?.includeArchived) params.set("include_archived", "1");
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
       params.set("grep_mode", options.grepMode ?? "all");
@@ -5584,6 +5589,12 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(playName, pinned) {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned
+    });
+  }
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings() {
     return this.http.get("/api/v2/settings/notifications");

package/dist/index.mjs

@@ -703,7 +703,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.70",
+  version: "0.2.71",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -3642,16 +3642,9 @@ function isPrebuiltPlayDescription(play) {
   return play.origin === "prebuilt" || play.ownerType === "deepline";
 }
 function preferPrebuiltPlayDescriptions(plays) {
-  const prebuilt = [];
-  const owned = [];
-  for (const play of plays) {
-    if (isPrebuiltPlayDescription(play)) {
-      prebuilt.push(play);
-    } else {
-      owned.push(play);
-    }
-  }
-  return [...prebuilt, ...owned];
+  return plays.map((play, index) => ({ play, index })).sort(
+    (left, right) => Number(right.play.pinned) - Number(left.play.pinned) || Number(isPrebuiltPlayDescription(right.play)) - Number(isPrebuiltPlayDescription(left.play)) || left.index - right.index
+  ).map(({ play }) => play);
 }
 function isPlayRunPackage(value) {
   return Boolean(
@@ -3998,6 +3991,8 @@ var DeeplineClient = class {
       ...play.reference ? { reference: play.reference } : {},
       ...play.displayName ? { displayName: play.displayName } : {},
       ...description ? { description } : {},
+      pinned: Boolean(play.pinned),
+      toolCategories: play.toolCategories ?? [],
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -5496,6 +5491,16 @@ var DeeplineClient = class {
   async listPlays(options) {
     const params = new URLSearchParams();
     if (options?.origin) params.set("origin", options.origin);
+    if (options?.categories) {
+      params.set(
+        "categories",
+        Array.isArray(options.categories) ? options.categories.join(",") : options.categories
+      );
+    }
+    if (options?.categories || options?.includeToolCategories) {
+      params.set("include_tool_categories", "1");
+    }
+    if (options?.includeArchived) params.set("include_archived", "1");
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
       params.set("grep_mode", options.grepMode ?? "all");
@@ -5507,6 +5512,12 @@ var DeeplineClient = class {
     );
     return response.plays ?? [];
   }
+  /** Set whether an org-owned Play sorts before unpinned Plays. */
+  async setPlayPinned(playName, pinned) {
+    return this.http.post(`/api/v2/plays/${encodeURIComponent(playName)}/pin`, {
+      pinned
+    });
+  }
   /** Read product-notification destinations, subscriptions, event catalog, and DLQ health. */
   async getNotificationSettings() {
     return this.http.get("/api/v2/settings/notifications");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.2.70",
+  "version": "0.2.71",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",