deepline 0.2.70 → 0.2.72

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.72",
   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");
@@ -5967,9 +5978,10 @@ var DeeplineClient = class {
    * console.log(`Total runs: ${detail.play.runCount}`);
    * ```
    */
-  async getPlay(name) {
+  async getPlay(name, options) {
     const encodedName = encodeURIComponent(name);
-    return this.http.get(`/api/v2/plays/${encodedName}`);
+    const query = options?.source ? `?include=source&revision=${encodeURIComponent(options.source)}` : "";
+    return this.http.get(`/api/v2/plays/${encodedName}${query}`);
   }
   /**
    * Get a normalized play description suitable for agents and CLIs.
@@ -11012,6 +11024,7 @@ import { Option } from "commander";
 import { createHash as createHash4, randomUUID as randomUUID3 } from "crypto";
 import {
   existsSync as existsSync9,
+  mkdirSync as mkdirSync6,
   readFileSync as readFileSync8,
   readdirSync as readdirSync2,
   realpathSync as realpathSync2,
@@ -11025,7 +11038,14 @@ import {
   readFile as readFileAsync,
   unlink
 } from "fs/promises";
-import { basename as basename3, dirname as dirname9, join as join10, resolve as resolve11 } from "path";
+import {
+  basename as basename3,
+  dirname as dirname9,
+  isAbsolute as isAbsolute5,
+  join as join10,
+  relative as relative4,
+  resolve as resolve11
+} from "path";
 import { parse as parseCsvSync2 } from "csv-parse/sync";
 
 // src/cli/commands/plays/bootstrap.ts
@@ -18632,7 +18652,10 @@ async function assertCanonicalNamedPlayReference(client2, target, options = {})
   const parsed = parseReferencedPlayTarget2(target);
   let detail;
   try {
-    detail = await client2.getPlay(parsed.playName);
+    detail = await client2.getPlay(
+      parsed.playName,
+      options.source ? { source: options.source } : void 0
+    );
   } catch (error) {
     if (isPlayNotFoundError(error)) {
       throw await buildPlayReferenceNotFoundError({
@@ -18685,19 +18708,54 @@ function materializeRemotePlaySource(input2) {
   if (isFileTarget(input2.target)) {
     return null;
   }
-  if (!input2.sourceCode.trim()) {
+  const entrySource = input2.source.files[input2.source.entryFile];
+  if (!entrySource?.trim()) {
     return null;
   }
+  const files = Object.entries(input2.source.files);
+  if (files.length > 1) {
+    if (!input2.outPath) {
+      throw new Error(
+        `Play ${input2.playName} has ${files.length} source files. Use --out <directory> to write the complete bundle.`
+      );
+    }
+    const outputDirectory = resolve11(input2.outPath);
+    let created = 0;
+    let updated = 0;
+    for (const [logicalPath, sourceCode] of files) {
+      const outputPath2 = resolve11(outputDirectory, logicalPath);
+      const outputRelativePath = relative4(outputDirectory, outputPath2);
+      if (!outputRelativePath || outputRelativePath.startsWith("..") || isAbsolute5(outputRelativePath)) {
+        throw new Error(
+          `Refusing to materialize unsafe Play source path ${JSON.stringify(logicalPath)}.`
+        );
+      }
+      mkdirSync6(dirname9(outputPath2), { recursive: true });
+      if (!existsSync9(outputPath2)) {
+        writeFileSync9(outputPath2, sourceCode, "utf-8");
+        created += 1;
+      } else if (readFileSync8(outputPath2, "utf-8") !== sourceCode) {
+        writeFileSync9(outputPath2, sourceCode, "utf-8");
+        updated += 1;
+      }
+    }
+    return {
+      path: outputDirectory,
+      status: created > 0 ? "created" : updated > 0 ? "updated" : "unchanged",
+      created: created > 0,
+      fileCount: files.length
+    };
+  }
   const outputPath = input2.outPath ?? defaultMaterializedPlayPath(input2.playName);
   if (existsSync9(outputPath)) {
     const existingSource = readFileSync8(outputPath, "utf-8");
-    if (existingSource === input2.sourceCode) {
+    if (existingSource === entrySource) {
       return { path: outputPath, status: "unchanged", created: false };
     }
-    writeFileSync9(outputPath, input2.sourceCode, "utf-8");
+    writeFileSync9(outputPath, entrySource, "utf-8");
     return { path: outputPath, status: "updated", created: false };
   }
-  writeFileSync9(outputPath, input2.sourceCode, "utf-8");
+  writeFileSync9(outputPath, entrySource, "utf-8");
   return { path: outputPath, status: "created", created: true };
 }
 function formatLoadedPlayMessage(materializedFile) {
@@ -22570,6 +22628,47 @@ ${PLAY_PUBLISH_USAGE}`
     jsonOutput: argsWantJson(args)
   };
 }
+var PLAY_SAVE_USAGE = "Usage: deepline plays save <play-file.ts> [--expected-artifact <hash>] [--dry-run] [--json]";
+function parsePlaySaveOptions(args) {
+  const target = args[0];
+  if (!target) throw new Error(PLAY_SAVE_USAGE);
+  if (target.startsWith("-")) {
+    throw new Error(`${PLAY_SAVE_USAGE}
+The Play file is positional.`);
+  }
+  let expectedArtifactHash;
+  let dryRun = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--expected-artifact") {
+      expectedArtifactHash = args[++index];
+      if (!expectedArtifactHash) {
+        throw new Error("--expected-artifact requires an artifact hash.");
+      }
+      continue;
+    }
+    if (arg.startsWith("--expected-artifact=")) {
+      expectedArtifactHash = arg.slice("--expected-artifact=".length);
+      if (!expectedArtifactHash) {
+        throw new Error("--expected-artifact requires an artifact hash.");
+      }
+      continue;
+    }
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--json") continue;
+    throw new Error(`Unknown option: ${arg}
+${PLAY_SAVE_USAGE}`);
+  }
+  return {
+    target,
+    expectedArtifactHash,
+    dryRun,
+    jsonOutput: argsWantJson(args)
+  };
+}
 function formatByteBudget(usedBytes, limitBytes) {
   return `${usedBytes.toLocaleString()} B / ${limitBytes.toLocaleString()} B`;
 }
@@ -22900,6 +22999,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 +23061,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 } : {}
@@ -24010,24 +24132,63 @@ async function handlePlayGet(args) {
   const explicitJson = args.includes("--json");
   const sourceOutput = args.includes("--source");
   const jsonOutput = sourceOutput ? explicitJson : argsWantJson(args);
+  const requestedRevisionFlags = [
+    args.includes("--working"),
+    args.includes("--live"),
+    args.includes("--revision")
+  ].filter(Boolean).length;
+  if (requestedRevisionFlags > 1) {
+    console.error("Use only one of --working, --live, or --revision <number>.");
+    return 2;
+  }
+  let sourceSelector = "working";
+  if (args.includes("--live")) {
+    sourceSelector = "live";
+  }
   let outPath = null;
+  let requestedVersion = null;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--out" && args[index + 1]) {
       outPath = resolve11(args[++index]);
     }
+    if (arg === "--revision") {
+      const rawVersion = args[++index];
+      const version = Number(rawVersion);
+      if (!rawVersion || !Number.isInteger(version) || version < 1) {
+        console.error("--revision must be a positive integer.");
+        return 2;
+      }
+      requestedVersion = version;
+    }
+  }
+  if (requestedVersion !== null) {
+    sourceSelector = `version:${requestedVersion}`;
+  }
+  if (requestedRevisionFlags > 0 && !sourceOutput && !outPath) {
+    console.error(
+      "--working, --live, and --revision only apply when reading source with --source or --out."
+    );
+    return 2;
   }
   const playName = isFileTarget(target) ? extractPlayName(readFileSync8(resolve11(target), "utf-8"), resolve11(target)) : parseReferencedPlayTarget2(target).playName;
-  const detail = isFileTarget(target) ? await client2.getPlay(playName) : await assertCanonicalNamedPlayReference(client2, target, {
-    command: "get"
-  });
-  const resolvedSource = detail.play.workingRevision?.sourceCode ?? detail.play.liveRevision?.sourceCode ?? detail.play.currentRevision?.sourceCode ?? detail.play.sourceCode ?? "";
-  const materializedFile = outPath ? materializeRemotePlaySource({
-    target,
+  const includeSource = sourceOutput || outPath !== null;
+  const detail = isFileTarget(target) ? await client2.getPlay(
     playName,
-    sourceCode: resolvedSource,
-    outPath
-  }) : null;
+    includeSource ? { source: sourceSelector } : void 0
+  ) : await assertCanonicalNamedPlayReference(client2, target, {
+    command: "get",
+    ...includeSource ? { source: sourceSelector } : {}
+  });
+  const source = detail.source;
+  const resolvedSource = source?.files[source.entryFile] ?? "";
+  let materializedFile = null;
+  try {
+    materializedFile = outPath && source ? materializeRemotePlaySource({ target, playName, source, outPath }) : null;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
   const loadedMessage = materializedFile ? formatLoadedPlayMessage(materializedFile) : null;
   if (jsonOutput) {
     process.stdout.write(
@@ -24048,14 +24209,20 @@ async function handlePlayGet(args) {
     return 0;
   }
   if (sourceOutput) {
-    if (!resolvedSource.trim()) {
+    if (!source || !resolvedSource.trim()) {
       console.error(`No source code available for ${playName}.`);
-      return 1;
+      return 4;
     }
     if (materializedFile) {
       console.log(loadedMessage);
       return 0;
     }
+    if (Object.keys(source.files).length > 1) {
+      console.error(
+        `Play ${playName} has ${Object.keys(source.files).length} source files. Use --out <directory> to write the complete bundle.`
+      );
+      return 2;
+    }
     process.stdout.write(resolvedSource);
     if (!resolvedSource.endsWith("\n")) {
       process.stdout.write("\n");
@@ -24125,7 +24292,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 +24308,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 +24339,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 +24403,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 +24514,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 +24646,7 @@ async function handlePlayGrep(args) {
         origin: play.origin,
         ownerType: play.ownerType,
         aliases: play.aliases,
+        toolCategories: play.toolCategories,
         inputSchema: play.inputSchema,
         outputSchema: play.outputSchema
       },
@@ -24531,6 +24744,128 @@ async function handlePlayDescribe(args) {
   printPlayDescription(play);
   return 0;
 }
+async function handlePlaySave(args) {
+  let options;
+  try {
+    options = parsePlaySaveOptions(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
+  if (!isFileTarget(options.target)) {
+    console.error(
+      "plays save requires a local .play.ts file. Use plays publish <play-name> to promote an existing saved revision."
+    );
+    return 2;
+  }
+  let graph;
+  try {
+    graph = await traceCliSpan(
+      "cli.play_save_bundle_graph",
+      { targetKind: "file" },
+      () => collectBundledPlayGraph(resolve11(options.target))
+    );
+    assertBundledPlayGraphDescriptions(graph);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 7;
+  }
+  const playName = graph.root.playName ?? extractPlayName(graph.root.sourceCode, graph.root.filePath);
+  const artifactHash = graph.root.artifact.artifactHash;
+  if (options.expectedArtifactHash && options.expectedArtifactHash !== artifactHash) {
+    const result = {
+      ok: false,
+      code: "PLAY_ARTIFACT_HASH_MISMATCH",
+      message: "Refusing to save: the local file no longer produces the artifact checked earlier.",
+      expectedArtifactHash: options.expectedArtifactHash,
+      currentArtifactHash: artifactHash,
+      next: `deepline plays check ${shellQuote2(options.target)}`
+    };
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+    } else {
+      console.error(result.message);
+      console.error(`  checked artifact: ${result.expectedArtifactHash}`);
+      console.error(`  current artifact: ${result.currentArtifactHash}`);
+      console.error(`  run: ${result.next}`);
+    }
+    return 7;
+  }
+  const dryRun = {
+    ok: true,
+    dryRun: true,
+    name: playName,
+    sourcePath: graph.root.filePath,
+    sourceHash: graph.root.artifact.sourceHash,
+    artifactHash,
+    graphHash: graph.root.artifact.graphHash,
+    sourceFileCount: Object.keys(graph.root.sourceFiles).length,
+    plannedMutation: "save or update the mutable working draft; does not change the live revision"
+  };
+  if (options.dryRun) {
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(dryRun)}
+`);
+    } else {
+      console.log(`Dry run: ${playName}`);
+      console.log(`  source: ${dryRun.sourceHash}`);
+      console.log(`  artifact: ${dryRun.artifactHash}`);
+      console.log(`  would: ${dryRun.plannedMutation}`);
+    }
+    return 0;
+  }
+  const client2 = new DeeplineClient();
+  try {
+    await traceCliSpan(
+      "cli.play_save_compile_manifests",
+      { targetKind: "file", nodeCount: graph.nodes.size },
+      () => compileBundledPlayGraphManifests(client2, graph)
+    );
+    const saved = await traceCliSpan(
+      "cli.play_save_register_draft",
+      { targetKind: "file", playName, artifactHash },
+      () => client2.registerPlayArtifact({
+        name: playName,
+        sourceCode: graph.root.sourceCode,
+        sourceFiles: graph.root.sourceFiles,
+        description: graph.root.playDescription ?? void 0,
+        artifact: graph.root.artifact,
+        compilerManifest: requireCompilerManifest(graph.root),
+        publish: false
+      })
+    );
+    const result = {
+      success: true,
+      name: playName,
+      draft: true,
+      revisionId: saved.revisionId ?? null,
+      version: saved.version ?? null,
+      sourceHash: graph.root.artifact.sourceHash,
+      artifactHash,
+      graphHash: graph.root.artifact.graphHash,
+      artifactStorageKey: saved.artifactStorageKey,
+      next: {
+        publish: `deepline plays publish ${shellQuote2(options.target)} --expected-artifact ${artifactHash}`,
+        get: `deepline plays get ${playName} --source --out ./${playName}/ --working`
+      }
+    };
+    if (options.jsonOutput) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+    } else {
+      console.log(
+        `\u2713 Saved ${playName} working draft as v${result.version ?? "?"}`
+      );
+      console.log("  Live revision unchanged.");
+      console.log(`  publish: ${result.next.publish}`);
+    }
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 5;
+  }
+}
 async function handlePlayPublish(args) {
   let options;
   try {
@@ -25061,7 +25396,9 @@ Pass-through input flags:
     ]);
   });
   registerPlayBootstrapCommand(play);
-  play.command("get <target>").description("Fetch full play details.").addHelpText(
+  play.command("get <target>").description(
+    "Fetch full play details or materialize a saved source bundle."
+  ).addHelpText(
     "after",
     `
 Notes:
@@ -25073,17 +25410,24 @@ Examples:
   deepline plays get prebuilt/person-linkedin-to-email
   deepline plays get prebuilt/person-linkedin-to-email --json | jq '.play.liveRevision'
   deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source > email-waterfall.play.ts
-  deepline plays get prebuilt/name-and-domain-to-email-waterfall-batch --source --out ./email-waterfall.play.ts
+  deepline plays get my-play --source --out ./my-play/ --working
+  deepline plays get my-play --source --out ./my-play-v3/ --revision 3
 `
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
     "--source",
-    "Print raw source code; combine with --out to write a file"
-  ).option("--out <path>", "Write source to a specific path").action(async (target, options) => {
+    "Read source; prints single-file Plays or combines with --out to write the full bundle"
+  ).option(
+    "--out <path>",
+    "Write source to a file or, for multi-file Plays, a directory"
+  ).option("--working", "Read the current working draft source (default)").option("--live", "Read the live revision source").option("--revision <number>", "Read a specific revision source").action(async (target, options) => {
     process.exitCode = await handlePlayGet([
       target,
       ...options.json ? ["--json"] : [],
       ...options.source ? ["--source"] : [],
-      ...options.out ? ["--out", options.out] : []
+      ...options.out ? ["--out", options.out] : [],
+      ...options.working ? ["--working"] : [],
+      ...options.live ? ["--live"] : [],
+      ...options.revision ? ["--revision", options.revision] : []
     ]);
   });
   play.command("list").description("List saved and prebuilt plays.").addHelpText(
@@ -25097,11 +25441,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)"
@@ -25194,6 +25562,32 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
+  play.command("save <file>").description(
+    "Save or update a local Play working draft without publishing it."
+  ).addHelpText(
+    "after",
+    `
+Notes:
+  Mutates cloud state, but does not change the live revision or active triggers.
+  Repeated saves update one working draft. Publishing it, or running a named
+  draft revision, freezes it; the next save starts a new revision.
+
+Examples:
+  deepline plays save ./company-research.play.ts
+  deepline plays save ./company-research.play.ts --dry-run --json
+  deepline plays publish ./company-research.play.ts
+`
+  ).option("--expected-artifact <hash>", "Require the checked artifact hash").option(
+    "--dry-run",
+    "Bundle and show the planned draft save without mutation"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (file, options) => {
+    process.exitCode = await handlePlaySave([
+      file,
+      ...options.expectedArtifact ? ["--expected-artifact", options.expectedArtifact] : [],
+      ...options.dryRun ? ["--dry-run"] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
   const addPublishHelp = (command) => command.addHelpText(
     "after",
     `
@@ -26456,10 +26850,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 = [
@@ -31152,7 +31548,7 @@ Examples:
 // src/cli/commands/sessions.ts
 import {
   existsSync as existsSync10,
-  mkdirSync as mkdirSync6,
+  mkdirSync as mkdirSync7,
   readdirSync as readdirSync3,
   readFileSync as readFileSync9,
   statSync as statSync4,
@@ -31753,13 +32149,13 @@ async function handleSessionsRender(options) {
   let outputPath = options.output ? resolve13(options.output) : "";
   if (!outputPath) {
     const outputDir = join12(process.cwd(), "deepline", "data");
-    mkdirSync6(outputDir, { recursive: true });
+    mkdirSync7(outputDir, { recursive: true });
     outputPath = join12(
       outputDir,
       targets.length > 1 ? "session-viewer.html" : `session-${targets[0]?.sessionId}.html`
     );
   } else {
-    mkdirSync6(dirname11(outputPath), { recursive: true });
+    mkdirSync7(dirname11(outputPath), { recursive: true });
   }
   const sessions = targets.map((target) => ({
     label: target.label,
@@ -34013,18 +34409,18 @@ import { spawnSync } from "child_process";
 import {
   existsSync as existsSync12,
   lstatSync,
-  mkdirSync as mkdirSync8,
+  mkdirSync as mkdirSync9,
   readFileSync as readFileSync12,
   realpathSync as realpathSync3,
   rmSync as rmSync4,
   writeFileSync as writeFileSync12
 } from "fs";
 import { homedir as homedir10 } from "os";
-import { basename as basename6, dirname as dirname13, join as join14, relative as relative4, resolve as resolve14 } from "path";
+import { basename as basename6, dirname as dirname13, join as join14, relative as relative5, resolve as resolve14 } from "path";
 
 // src/cli/commands/skills.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir9 } from "os";
 import { dirname as dirname12, join as join13 } from "path";
 
@@ -34450,7 +34846,7 @@ async function runSkillsCommand(options, dependencies = {}) {
     );
     return 5;
   }
-  mkdirSync7(dirname12(plan.statePath), { recursive: true });
+  mkdirSync8(dirname12(plan.statePath), { recursive: true });
   writeFileSync11(
     plan.statePath,
     `${JSON.stringify(
@@ -34713,7 +35109,7 @@ function removeKnownLegacyPaths(baseUrl) {
   const installerCommandPath = safeRead(
     join14(hostDir, "sdk", ".command-path")
   ).trim();
-  const relativeInstallerCommandPath = installerCommandPath ? relative4(resolve14(hostDir), resolve14(installerCommandPath)) : "";
+  const relativeInstallerCommandPath = installerCommandPath ? relative5(resolve14(hostDir), resolve14(installerCommandPath)) : "";
   const isOwnedInstallerCommand = Boolean(installerCommandPath) && relativeInstallerCommandPath !== "" && !relativeInstallerCommandPath.startsWith(
     `..${process.platform === "win32" ? "\\" : "/"}`
   ) && relativeInstallerCommandPath !== ".." && basename6(installerCommandPath) === "deepline";
@@ -34827,7 +35223,7 @@ function inspectPathConflict() {
 }
 function writeSetupState(input2) {
   const path = setupStatePath(input2.baseUrl, input2.scope, input2.root);
-  mkdirSync8(dirname13(path), { recursive: true });
+  mkdirSync9(dirname13(path), { recursive: true });
   writeFileSync12(
     path,
     `${JSON.stringify(
@@ -36069,7 +36465,7 @@ chooses the connected Slack channel and the events it receives.
 }
 
 // src/cli/commands/switch.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync9, readFileSync as readFileSync13, writeFileSync as writeFileSync13 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync10, readFileSync as readFileSync13, writeFileSync as writeFileSync13 } from "fs";
 import { homedir as homedir11 } from "os";
 import { dirname as dirname14, join as join15 } from "path";
 function hostSlugFromBaseUrl(baseUrl) {
@@ -36111,7 +36507,7 @@ function readActiveFamily() {
 }
 function writeActiveFamily(family) {
   const path = activeFamilyPath();
-  mkdirSync9(dirname14(path), { recursive: true });
+  mkdirSync10(dirname14(path), { recursive: true });
   writeFileSync13(path, `${family}
 `, "utf-8");
   return path;
@@ -36242,7 +36638,7 @@ import { join as join17, resolve as resolve15 } from "path";
 // src/tool-output.ts
 import {
   closeSync as closeSync3,
-  mkdirSync as mkdirSync10,
+  mkdirSync as mkdirSync11,
   openSync as openSync3,
   writeFileSync as writeFileSync14,
   writeSync
@@ -36376,7 +36772,7 @@ function projectRowOutput(conversion) {
 }
 function ensureOutputDir() {
   const outputDir = join16(homedir12(), ".local", "share", "deepline", "data");
-  mkdirSync10(outputDir, { recursive: true });
+  mkdirSync11(outputDir, { recursive: true });
   return outputDir;
 }
 function writeJsonOutputFile(payload, stem) {
@@ -36387,7 +36783,7 @@ function writeJsonOutputFile(payload, stem) {
 }
 function writeCsvOutputFile(rows, stem, options) {
   const outputPath = options?.outPath ? options.outPath : join16(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
-  mkdirSync10(dirname15(outputPath), { recursive: true });
+  mkdirSync11(dirname15(outputPath), { recursive: true });
   const columns = columnsForRows(rows);
   const escapeCell = (value) => {
     const normalized = value == null ? "" : typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value);
@@ -38865,7 +39261,7 @@ Examples:
 import { spawn as spawn3 } from "child_process";
 import {
   existsSync as existsSync16,
-  mkdirSync as mkdirSync11,
+  mkdirSync as mkdirSync12,
   realpathSync as realpathSync4,
   readFileSync as readFileSync16,
   renameSync,
@@ -38874,12 +39270,12 @@ import {
   writeFileSync as writeFileSync16
 } from "fs";
 import { homedir as homedir13 } from "os";
-import { dirname as dirname16, isAbsolute as isAbsolute6, join as join19, relative as relative6, resolve as resolve17 } from "path";
+import { dirname as dirname16, isAbsolute as isAbsolute7, join as join19, relative as relative7, resolve as resolve17 } from "path";
 
 // src/cli/install-integrity.ts
 import { createRequire } from "module";
 import { existsSync as existsSync15, readFileSync as readFileSync15, statSync as statSync5 } from "fs";
-import { isAbsolute as isAbsolute5, join as join18, relative as relative5, resolve as resolve16 } from "path";
+import { isAbsolute as isAbsolute6, join as join18, relative as relative6, resolve as resolve16 } from "path";
 var SDK_SIDECAR_CRITICAL_PACKAGE_FILES = [
   "dist/cli/index.mjs",
   "dist/index.mjs",
@@ -38896,7 +39292,7 @@ var SDK_SIDECAR_CRITICAL_DEPENDENCY_FILES = [
   "esbuild/lib/main.js"
 ];
 function safeRelativePath(value) {
-  if (typeof value !== "string" || !value || isAbsolute5(value)) return false;
+  if (typeof value !== "string" || !value || isAbsolute6(value)) return false;
   const segments = value.split(/[\\/]+/);
   return segments.every(
     (segment) => Boolean(segment) && segment !== "." && segment !== ".."
@@ -38905,8 +39301,8 @@ function safeRelativePath(value) {
 function resolveContainedPath(root, value) {
   if (!safeRelativePath(value)) return null;
   const target = resolve16(root, value);
-  const relativeTarget = relative5(resolve16(root), target);
-  if (!relativeTarget || relativeTarget.startsWith("..") || isAbsolute5(relativeTarget)) {
+  const relativeTarget = relative6(resolve16(root), target);
+  if (!relativeTarget || relativeTarget.startsWith("..") || isAbsolute6(relativeTarget)) {
     return null;
   }
   return target;
@@ -39127,11 +39523,11 @@ function readOptionalText(path) {
 function resolvePythonSidecarUpdatePlan(options) {
   const stateDir = sidecarStateDir(options);
   if (!stateDir) return null;
-  const relativeEntrypoint = relative6(
+  const relativeEntrypoint = relative7(
     resolve17(stateDir),
     resolve17(options.entrypoint)
   );
-  if (!relativeEntrypoint || relativeEntrypoint.startsWith("..") || isAbsolute6(relativeEntrypoint)) {
+  if (!relativeEntrypoint || relativeEntrypoint.startsWith("..") || isAbsolute7(relativeEntrypoint)) {
     return null;
   }
   const installMethod = readOptionalText(join19(stateDir, ".install-method"));
@@ -39298,7 +39694,7 @@ function writeAutoUpdateFailure(plan, exitCode) {
     manualCommand: plan.manualCommand
   };
   try {
-    mkdirSync11(dirname16(path), { recursive: true });
+    mkdirSync12(dirname16(path), { recursive: true });
     writeFileSync16(path, `${JSON.stringify(marker, null, 2)}
 `, "utf8");
   } catch {
@@ -39478,7 +39874,7 @@ async function runNpmInstallWithRegistryFallback(input2) {
   return first.exitCode;
 }
 function writeSidecarLauncher(input2) {
-  mkdirSync11(dirname16(input2.path), { recursive: true });
+  mkdirSync12(dirname16(input2.path), { recursive: true });
   const packageRoot = dirname16(dirname16(dirname16(input2.entryPath)));
   const versionDir = dirname16(dirname16(packageRoot));
   const esbuildProbe = "const {createRequire}=require('node:module');const path=require('node:path');const req=createRequire(path.join(process.argv[1],'package.json'));const result=req('esbuild').transformSync('const value: number = 1;',{loader:'ts'});if(!result||typeof result.code!=='string')process.exit(3);";
@@ -39547,7 +39943,7 @@ async function runPythonSidecarUpdatePlan(plan) {
     `.tmp-sdk-update-${process.pid}-${Date.now()}`
   );
   rmSync5(tempDir, { recursive: true, force: true });
-  mkdirSync11(tempDir, { recursive: true });
+  mkdirSync12(tempDir, { recursive: true });
   writeFileSync16(join19(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
   const env = {
     ...process.env,
@@ -40556,7 +40952,7 @@ async function maybeAutoUpdateAndRelaunch(response) {
 import { spawn as spawn5, spawnSync as spawnSync2 } from "child_process";
 import {
   existsSync as existsSync17,
-  mkdirSync as mkdirSync12,
+  mkdirSync as mkdirSync13,
   readFileSync as readFileSync17,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync17
@@ -40609,7 +41005,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  mkdirSync12(dirname18(path), { recursive: true });
+  mkdirSync13(dirname18(path), { recursive: true });
   writeFileSync17(path, `${version}
 `, "utf-8");
 }
@@ -40619,7 +41015,7 @@ function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
     if (existsSync17(path) && readFileSync17(path, "utf-8").trim() === remoteVersion) {
       return;
     }
-    mkdirSync12(dirname18(path), { recursive: true });
+    mkdirSync13(dirname18(path), { recursive: true });
     writeFileSync17(path, `${remoteVersion}
 `, "utf-8");
   } catch {