deepline 0.1.106 → 0.1.108

package/dist/cli/index.mjs

@@ -219,12 +219,24 @@ var SDK_RELEASE = {
   // 0.1.105 ships the billing catalog surface: billing plans, subscribe,
   // subscription status/cancel, invoices, and the client.billing namespace.
   // 0.1.106 ships play cell provenance metadata and v2 preview retry hardening.
-  version: "0.1.106",
+  // 0.1.107 ships the v2 quickstart command, the deepline-plays-quickstart
+  // skill on the sdk sync surface, and the people-search-to-email prebuilt.
+  // 0.1.108 ships explicit dataset column/tool recompute policy and removes
+  // the SDK enrich generator's one-second stale policy.
+  version: "0.1.108",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.106",
+    latest: "0.1.108",
     minimumSupported: "0.1.53",
-    deprecatedBelow: "0.1.53"
+    deprecatedBelow: "0.1.53",
+    commandMinimumSupported: [
+      {
+        command: "enrich",
+        minimumSupported: "0.1.108",
+        reason: "Older SDK CLI enrich generated stale play source for the current dataset API."
+      }
+    ],
+    autoUpdatePatchLag: 2
   }
 };
 
@@ -824,6 +836,8 @@ function normalizeStepProgress(value) {
         value.artifactTableNamespace
       )
     } : {},
+    ...finiteNumber(value.startedAt) !== null ? { startedAt: finiteNumber(value.startedAt) } : {},
+    ...finiteNumber(value.completedAt) !== null ? { completedAt: finiteNumber(value.completedAt) } : {},
     ...finiteNumber(value.updatedAt) !== null ? { updatedAt: finiteNumber(value.updatedAt) } : {}
   };
 }
@@ -3146,7 +3160,7 @@ function shouldSkipCompatibilityCheck() {
   const value = process.env.DEEPLINE_SKIP_SDK_COMPAT_CHECK?.trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes";
 }
-async function checkSdkCompatibility(baseUrl) {
+async function checkSdkCompatibility(baseUrl, options = {}) {
   if (shouldSkipCompatibilityCheck()) {
     return { response: null, error: null };
   }
@@ -3155,6 +3169,9 @@ async function checkSdkCompatibility(baseUrl) {
   try {
     const url = new URL("/api/v2/sdk/compat", baseUrl);
     url.searchParams.set("version", SDK_VERSION);
+    if (options.command?.trim()) {
+      url.searchParams.set("command", options.command.trim());
+    }
     const response = await fetch(url, {
       method: "GET",
       headers: {
@@ -3175,9 +3192,8 @@ async function checkSdkCompatibility(baseUrl) {
     clearTimeout(timeout);
   }
 }
-async function enforceSdkCompatibility(baseUrl) {
-  const { response, error } = await checkSdkCompatibility(baseUrl);
-  if (error || !response) {
+function enforceSdkCompatibilityResponse(response) {
+  if (!response) {
     return;
   }
   if (response.update_required) {
@@ -15496,7 +15512,7 @@ function renderIdiomaticExecuteStep(command, options) {
     `    tool: ${tool},`,
     `    input: ${input2} as any,`,
     `    description: ${stringLiteral((command.description ?? "").trim() || `Run ${command.alias} via ${command.tool}.`)},`,
-    ...options.force ? [`    staleAfterSeconds: 1,`] : [],
+    ...options.force ? [`    force: true,`] : [],
     `  });`,
     `  return ${extraction};`,
     `}`
@@ -15528,17 +15544,13 @@ function renderPlayStep(command, options) {
 ${indent(renderJavascriptBody(command.run_if_js), 6)}
     }` : "null";
   const runIfLines = command.run_if_js ? [`  const __dlRunIf = ${runIfJs};`, `  if (!__dlRunIf(row)) return null;`] : [];
-  const playOptions = [
-    `      description: ${stringLiteral(command.description ?? command.alias)}`,
-    ...options.force ? [`      staleAfterSeconds: 1`] : []
-  ].join(",\n");
   return [
     `async (row, stepCtx) => {`,
     ...options.precheck ? [`  if (${options.precheck}) return null;`] : [],
     ...runIfLines,
     `  const payload = __dlTemplate(${payload}, row) as Record<string, unknown>;`,
     `  const result = await stepCtx.runPlay(${callId}, ${playRef}, payload, {`,
-    playOptions,
+    `      description: ${stringLiteral(command.description ?? command.alias)}`,
     `  });`,
     `  return __dlPlayResultValue(${alias}, result);`,
     `}`
@@ -15555,12 +15567,17 @@ function renderJavascriptBody(source) {
   }
   return source;
 }
-function renderColumnStep(alias, resolverSource, force) {
+function renderColumnStep(alias, resolverSource, options = {}) {
   const resolver = indent(resolverSource, 8);
+  const optionFields = [
+    ...options.recompute === true ? ["recompute: true"] : [],
+    ...options.recomputeOnError === true ? ["recomputeOnError: true"] : []
+  ];
+  const optionSource = optionFields.length > 0 ? `{ ${optionFields.join(", ")} }` : null;
   return [
     `      .withColumn(${stringLiteral(alias)},`,
-    force ? `${resolver},` : resolver,
-    ...force ? [`        { staleAfterSeconds: 1 }`] : [],
+    `${resolver}${optionSource ? "," : ""}`,
+    ...optionSource ? [`        ${optionSource},`] : [],
     `      )`
   ].join("\n");
 }
@@ -15609,6 +15626,29 @@ function collectMetadataColumns(commands, waterfallGroupId) {
   }
   return columns;
 }
+function collectGeneratedAliases(commands) {
+  const aliases = [];
+  const addAlias = (alias) => {
+    if (alias && !aliases.includes(alias)) {
+      aliases.push(alias);
+    }
+  };
+  for (const command of commands) {
+    if (isWaterfall(command)) {
+      const before = aliases.length;
+      collectGeneratedAliases(command.commands).forEach(addAlias);
+      if (aliases.length > before) {
+        addAlias(command.with_waterfall);
+        addAlias(`${command.with_waterfall}_source`);
+      }
+      continue;
+    }
+    if (!command.disabled) {
+      addAlias(command.alias);
+    }
+  }
+  return aliases;
+}
 function renderMetadataColumnStep(config) {
   const columns = collectMetadataColumns(config.commands);
   if (Object.keys(columns).length === 0) {
@@ -15616,8 +15656,8 @@ function renderMetadataColumnStep(config) {
   }
   return [
     `      .withColumn('_metadata',`,
-    `        (row) => __dlMergeMetadata(row._metadata, ${stableJson({ columns })}),`,
-    `        { staleAfterSeconds: 1 }`,
+    `        (row) => __dlMergeMetadata(__dlMetadataFromRow(row), ${stableJson({ columns })}),`,
+    `        { recompute: true },`,
     `      )`
   ].join("\n");
 }
@@ -15644,7 +15684,7 @@ function renderWaterfallColumns(command, forceAliases, inlineRunJavascript, idio
         inlineRunJavascript,
         idiomaticGetters
       }),
-      force
+      { recompute: force, recomputeOnError: true }
     );
   }).filter((line) => line !== null);
   const aliases = activeChildren.map((nested) => nested.alias);
@@ -15660,15 +15700,13 @@ function renderWaterfallColumns(command, forceAliases, inlineRunJavascript, idio
   }
   return [
     ...columnSteps,
-    renderColumnStep(
-      command.with_waterfall,
-      `(row) => ${returnExpr}`,
-      forceParent
-    ),
+    renderColumnStep(command.with_waterfall, `(row) => ${returnExpr}`, {
+      recompute: forceParent
+    }),
     renderColumnStep(
       `${command.with_waterfall}_source`,
       typeof command.min_results === "number" ? `(row) => __dlContributingAliases(row, ${stableJson(aliases)})` : `(row) => __dlFirstMeaningfulAlias(row, ${stableJson(aliases)})`,
-      forceParent
+      { recompute: forceParent }
     )
   ];
 }
@@ -15705,18 +15743,20 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
           inlineRunJavascript,
           idiomaticGetters
         }),
-        force
+        { recompute: force, recomputeOnError: true }
       )
     );
   });
   const columnStepSource = columnSteps.length > 0 ? columnSteps.join("\n") : `      .withColumn('noop', () => null)`;
   const metadataColumnSource = renderMetadataColumnStep(config);
+  const generatedAliases = collectGeneratedAliases(config.commands);
   const body = [
     `export default definePlay(${stringLiteral(playName)}, async (ctx, input: EnrichInput) => {`,
     `  const sourceRows = await ctx.csv<Record<string, unknown>>(input.file);`,
     `  const rowStart = __dlNonNegativeInteger(input.rowStart, 0);`,
     `  const rowEndExclusive = Number.isFinite(input.rowEnd) ? Math.max(rowStart, __dlWholeNumber(input.rowEnd, rowStart) + 1) : undefined;`,
-    `  const rows = sourceRows.slice(rowStart, rowEndExclusive, { key: 'deepline_enrich_selected_rows', sourceLabel: 'Selected enrich rows' });`,
+    `  const selectedRows = sourceRows.slice(rowStart, rowEndExclusive, { key: 'deepline_enrich_selected_rows', sourceLabel: 'Selected enrich rows' });`,
+    `  const rows = selectedRows.map((row) => __dlStripErroredGeneratedColumns(row, ${stableJson(generatedAliases)}), { key: 'deepline_enrich_repair_rows', sourceLabel: 'Selected enrich rows' });`,
     `  const enriched = await ctx`,
     `    .dataset(${stringLiteral(mapName)}, rows)`,
     columnStepSource,
@@ -15802,6 +15842,18 @@ function helperSource() {
     `  return null;`,
     `}`,
     ``,
+    `function __dlMetadataFromRow(row: Record<string, unknown>): unknown {`,
+    `  const direct = __dlParseMetadata(row._metadata);`,
+    `  if (direct) return direct;`,
+    `  const relocated = __dlParseMetadata(row.metadata);`,
+    `  if (relocated) return relocated;`,
+    `  const dotted = __dlParseMetadata(row['metadata.columns']);`,
+    `  if (dotted) return { columns: dotted };`,
+    `  const underscored = __dlParseMetadata(row.metadata__columns);`,
+    `  if (underscored) return { columns: underscored };`,
+    `  return row._metadata;`,
+    `}`,
+    ``,
     `function __dlMergeMetadata(existing: unknown, patch: Record<string, unknown>): Record<string, unknown> {`,
     `  const base = __dlParseMetadata(existing) ?? {};`,
     `  const baseColumns = __dlRecord(base.columns) ? base.columns : {};`,
@@ -15876,6 +15928,40 @@ function helperSource() {
     `  return status === 'error' || status === 'failed' || (typeof record.error === 'string' && record.error.trim() !== '') || (typeof resultError === 'string' && resultError.trim() !== '');`,
     `}`,
     ``,
+    `function __dlGeneratedCellError(value: unknown): boolean {`,
+    `  if (typeof value === 'string') {`,
+    `    const lower = value.trim().toLowerCase();`,
+    `    if (!lower) return false;`,
+    `    if (lower.startsWith('error:') || lower.includes(': error:') || lower.includes('"error"')) return true;`,
+    `    try {`,
+    `      return __dlGeneratedCellError(JSON.parse(value));`,
+    `    } catch {`,
+    `      return false;`,
+    `    }`,
+    `  }`,
+    `  if (!__dlRecord(value)) return false;`,
+    `  const status = typeof value.status === 'string' ? value.status.toLowerCase() : '';`,
+    `  if (status === 'error' || status === 'failed') return true;`,
+    `  if (typeof value.error === 'string' && value.error.trim() !== '') return true;`,
+    `  const raw = __dlGetByPath(value, 'toolResponse.raw') ?? __dlGetByPath(value, 'toolOutput.raw');`,
+    `  if (raw !== undefined && raw !== value && __dlGeneratedCellError(raw)) return true;`,
+    `  const result = value.result;`,
+    `  return result !== undefined && result !== value && __dlGeneratedCellError(result);`,
+    `}`,
+    ``,
+    `function __dlStripErroredGeneratedColumns(row: Record<string, unknown>, aliases: string[]): Record<string, unknown> {`,
+    `  let next: Record<string, unknown> | null = null;`,
+    `  for (const alias of aliases) {`,
+    `    for (const key of __dlAliasCandidates(alias)) {`,
+    `      if (key in row && __dlGeneratedCellError(row[key])) {`,
+    `        if (next === null) next = { ...row };`,
+    `        delete next[key];`,
+    `      }`,
+    `    }`,
+    `  }`,
+    `  return next ?? row;`,
+    `}`,
+    ``,
     `function __dlRawToolOutput(result: unknown): unknown {`,
     `  if (!result || typeof result !== 'object') return result;`,
     `  const record = result as Record<string, unknown>;`,
@@ -16286,7 +16372,7 @@ function helperSource() {
     `    tool: input.tool,`,
     `    input: payload,`,
     `    ...(input.description ? { description: input.description } : {}),`,
-    `    ...(input.force ? { staleAfterSeconds: 1 } : {}),`,
+    `    ...(input.force ? { force: true } : {}),`,
     `  });`,
     `  return __dlExtract(input.alias, result, input.row, input.extract, Boolean(input.legacyEnvelope));`,
     `}`
@@ -17968,6 +18054,244 @@ Examples:
   ).option("--org-id <id>", "Switch using an explicit organization id").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleOrgSwitch);
 }
 
+// src/cli/commands/quickstart.ts
+import { spawn, spawnSync } from "child_process";
+import { randomBytes } from "crypto";
+import { createServer } from "http";
+var EXIT_OK2 = 0;
+var EXIT_AUTH2 = 1;
+var EXIT_SERVER3 = 2;
+var MAX_PROMPT_LENGTH = 8e3;
+var MAX_BODY_BYTES = 64 * 1024;
+function shellQuote(arg) {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function hasClaudeBinary() {
+  try {
+    const result = spawnSync("claude", ["--version"], {
+      stdio: "ignore",
+      shell: process.platform === "win32"
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+function launchClaude(prompt) {
+  return new Promise((resolve16) => {
+    const child = spawn("claude", [prompt], {
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    child.on("error", () => resolve16(EXIT_SERVER3));
+    child.on("close", (status) => resolve16(status ?? EXIT_OK2));
+  });
+}
+function readBody(req) {
+  return new Promise((resolve16, reject) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > MAX_BODY_BYTES) {
+        reject(new Error("Request body too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve16(raw));
+    req.on("error", reject);
+  });
+}
+function writeJson(res, status, payload) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(payload));
+}
+function startCallbackServer(input2) {
+  const server = createServer((req, res) => {
+    res.setHeader("Access-Control-Allow-Origin", req.headers.origin ?? "*");
+    res.setHeader("Vary", "Origin");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "content-type");
+    res.setHeader("Access-Control-Allow-Private-Network", "true");
+    res.setHeader("Access-Control-Max-Age", "600");
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    if (req.method !== "POST" || req.url !== "/submit") {
+      writeJson(res, 404, { error: "Not found." });
+      return;
+    }
+    void readBody(req).then((raw) => {
+      let body = null;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        body = null;
+      }
+      const state = typeof body?.state === "string" ? body.state : "";
+      const prompt = typeof body?.prompt === "string" ? body.prompt.trim() : "";
+      const workflowId = typeof body?.workflow_id === "string" && body.workflow_id.trim() ? body.workflow_id.trim() : null;
+      if (!state || state !== input2.state) {
+        writeJson(res, 403, { error: "Invalid quickstart state token." });
+        return;
+      }
+      if (!prompt) {
+        writeJson(res, 400, { error: "prompt is required." });
+        return;
+      }
+      if (prompt.length > MAX_PROMPT_LENGTH) {
+        writeJson(res, 400, {
+          error: `prompt exceeds ${MAX_PROMPT_LENGTH} characters.`
+        });
+        return;
+      }
+      writeJson(res, 200, { ok: true });
+      setImmediate(() => input2.onSelection({ prompt, workflowId }));
+    }).catch(() => {
+      writeJson(res, 400, { error: "Invalid request body." });
+    });
+  });
+  return new Promise((resolve16, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Failed to bind quickstart callback server."));
+        return;
+      }
+      resolve16({ server, port: address.port });
+    });
+  });
+}
+async function handleQuickstart(options) {
+  const jsonOutput = shouldEmitJson(options.json === true);
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  let apiKey = resolveApiKeyForBaseUrl(baseUrl);
+  if (!apiKey) {
+    if (interactive) {
+      console.error("Not connected yet \u2014 registering this device first.");
+      const registerExit = await handleRegister([]);
+      if (registerExit !== EXIT_OK2) return registerExit;
+      apiKey = resolveApiKeyForBaseUrl(baseUrl);
+    }
+    if (!apiKey) {
+      console.error("Not connected. Run: deepline auth register");
+      return EXIT_AUTH2;
+    }
+  }
+  const state = randomBytes(32).toString("hex");
+  let resolveSelection;
+  const selectionPromise = new Promise((resolve16) => {
+    resolveSelection = resolve16;
+  });
+  let callback;
+  try {
+    callback = await startCallbackServer({
+      state,
+      onSelection: (selection) => resolveSelection(selection)
+    });
+  } catch (error) {
+    console.error(
+      `Could not start the local quickstart listener: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return EXIT_SERVER3;
+  }
+  const quickstartUrl = `${baseUrl}/cli/quickstart?cb=${callback.port}&state=${state}`;
+  console.error("  Opening the recipe picker in your browser.");
+  console.error(`  If it didn't open, cmd+click: ${quickstartUrl}`);
+  if (options.open !== false) {
+    openInBrowser(quickstartUrl);
+  }
+  const timeoutSeconds = Number.parseInt(options.timeout ?? "300", 10);
+  const timeoutMs = (Number.isFinite(timeoutSeconds) && timeoutSeconds > 0 ? timeoutSeconds : 300) * 1e3;
+  const timeoutHandle = setTimeout(
+    () => resolveSelection("timeout"),
+    timeoutMs
+  );
+  const progress = createCliProgress(!jsonOutput);
+  progress.phase("waiting for your pick in the browser (Ctrl+C to skip)");
+  const onSigint = () => resolveSelection("sigint");
+  process.once("SIGINT", onSigint);
+  const outcome = await selectionPromise;
+  clearTimeout(timeoutHandle);
+  process.removeListener("SIGINT", onSigint);
+  callback.server.close();
+  if (outcome === "sigint") {
+    progress.fail();
+    console.error("\nSkipped \u2014 run `deepline quickstart` anytime.");
+    return EXIT_OK2;
+  }
+  if (outcome === "timeout") {
+    progress.fail();
+    console.error(
+      "Timed out waiting for a selection. Run: deepline quickstart"
+    );
+    return EXIT_AUTH2;
+  }
+  progress.complete();
+  const { prompt, workflowId } = outcome;
+  const claudeCommand = `claude ${shellQuote(prompt)}`;
+  const claudeAvailable = hasClaudeBinary();
+  const willLaunch = options.launch !== false && !jsonOutput && interactive && claudeAvailable;
+  printCommandEnvelope(
+    {
+      status: "submitted",
+      workflowId,
+      prompt,
+      claudeCommand,
+      url: quickstartUrl,
+      launched: willLaunch,
+      render: {
+        sections: [
+          {
+            title: "quickstart",
+            lines: [
+              ...workflowId ? [`Recipe: ${workflowId}`] : [],
+              willLaunch ? "Launching Claude Code with your recipe..." : claudeAvailable ? "Run the command below to start your recipe." : "Claude Code not found. Install it (https://code.claude.com/docs/en/overview), then run the command below."
+            ]
+          }
+        ],
+        actions: [{ label: "Run", command: claudeCommand }]
+      }
+    },
+    { json: jsonOutput }
+  );
+  if (willLaunch) {
+    return launchClaude(prompt);
+  }
+  return EXIT_OK2;
+}
+function registerQuickstartCommands(program) {
+  program.command("quickstart").description(
+    "Pick a starter recipe in the browser and launch it with Claude Code."
+  ).addHelpText(
+    "after",
+    `
+Notes:
+  Opens the hosted recipe picker in your browser. The picker sends your
+  selection back to a temporary listener on 127.0.0.1, so the browser must run
+  on the same machine as the CLI. Once a recipe arrives, the CLI prints the
+  matching claude command and, when Claude Code is installed and the shell is
+  interactive, launches it directly. Press Ctrl+C while waiting to skip.
+
+Examples:
+  deepline quickstart
+  deepline quickstart --no-open
+  deepline quickstart --no-launch --json
+  deepline quickstart --timeout 120
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--no-open", "Do not open the browser; print the URL only").option("--no-launch", "Print the claude command instead of launching it").option(
+    "--timeout <seconds>",
+    "Maximum seconds to wait for a selection",
+    "300"
+  ).action(async (options) => {
+    process.exitCode = await handleQuickstart(options);
+  });
+}
+
 // src/cli/commands/secrets.ts
 import { stdin as input, stdout as output } from "process";
 var hiddenInputBuffer = "";
@@ -19985,7 +20309,7 @@ function parseExecuteOptions(args) {
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
 }
-function shellQuote(value) {
+function shellQuote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function powerShellQuote(value) {
@@ -20037,7 +20361,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     path: scriptPath,
     sourceCode: script,
     projectDir,
-    macCopyCommand: `mkdir -p ${shellQuote(projectDir)} && cp ${shellQuote(scriptPath)} ${shellQuote(`${projectDir}/${fileName}`)}`,
+    macCopyCommand: `mkdir -p ${shellQuote2(projectDir)} && cp ${shellQuote2(scriptPath)} ${shellQuote2(`${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
@@ -20056,7 +20380,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     summary: input2.summary
   };
   const envelopeHasCanonicalOutput = isRecord7(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
-  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote(JSON.stringify(input2.params))} --json`;
+  const inspectCommand = `deepline tools execute ${input2.toolId} --input ${shellQuote2(JSON.stringify(input2.params))} --json`;
   const actions = input2.listConversion ? [
     {
       label: "next",
@@ -20775,7 +21099,7 @@ Notes:
 }
 
 // src/cli/commands/update.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync10 } from "fs";
 import { dirname as dirname11, join as join13, resolve as resolve15 } from "path";
 function posixShellQuote(value) {
@@ -20784,14 +21108,14 @@ function posixShellQuote(value) {
 function windowsCmdQuote(value) {
   return `"${value.replace(/"/g, '""')}"`;
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   if (process.platform === "win32") {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
   }
   return posixShellQuote(value);
 }
 function buildSourceUpdateCommand(sourceRoot) {
-  const quotedRoot = shellQuote2(sourceRoot);
+  const quotedRoot = shellQuote3(sourceRoot);
   const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
@@ -20822,12 +21146,12 @@ function resolveUpdatePlan() {
     kind: "npm-global",
     command,
     args,
-    manualCommand: `${command} ${args.map(shellQuote2).join(" ")}`
+    manualCommand: `${command} ${args.map(shellQuote3).join(" ")}`
   };
 }
 function runCommand(command, args) {
   return new Promise((resolveExitCode) => {
-    const child = spawn(command, args, {
+    const child = spawn2(command, args, {
       stdio: "inherit",
       shell: process.platform === "win32",
       env: process.env
@@ -20842,6 +21166,12 @@ function runCommand(command, args) {
     });
   });
 }
+async function runNpmGlobalUpdatePlan(plan) {
+  if (plan.kind !== "npm-global") {
+    return 1;
+  }
+  return runCommand(plan.command, plan.args);
+}
 async function handleUpdate(options) {
   const plan = resolveUpdatePlan();
   const render = {
@@ -20988,16 +21318,27 @@ function skillsIndexUrl(baseUrl) {
   return `${normalizeBaseUrl2(baseUrl)}${INSTALL_COMMANDS.skills.index_path}`;
 }
 function buildSkillsAddArgs(baseUrl, skillName, options = {}) {
+  const skillNames = Array.isArray(skillName) ? skillName : [skillName];
+  const [firstSkillName, ...extraSkillNames] = skillNames;
   const values = {
     skills_index_url: skillsIndexUrl(baseUrl),
     agents: INSTALL_COMMANDS.skills.default_agents.join(" "),
-    skill_name: skillName
+    skill_name: firstSkillName ?? ""
   };
   const rendered = INSTALL_COMMANDS.skills.npx_add_args_template.flatMap(
     (arg, index) => {
       const next = index === 0 && options.firstArg ? options.firstArg : arg;
       const value = renderTemplate(next, values);
-      return arg === "{agents}" ? INSTALL_COMMANDS.skills.default_agents : value;
+      if (arg === "{agents}") {
+        return INSTALL_COMMANDS.skills.default_agents;
+      }
+      if (arg === "{skill_name}") {
+        return [
+          value,
+          ...extraSkillNames.flatMap((name) => ["--skill", name])
+        ];
+      }
+      return value;
     }
   );
   return rendered;
@@ -21068,8 +21409,72 @@ function unknownCommandNameFromMessage(message) {
   return command ? command : null;
 }
 
+// src/cli/self-update.ts
+import { spawn as spawn3 } from "child_process";
+function envTruthy(name) {
+  const value = process.env[name]?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+function isCi() {
+  return envTruthy("CI") || envTruthy("GITHUB_ACTIONS");
+}
+function shouldSkipSelfUpdate() {
+  return envTruthy("DEEPLINE_SKIP_SELF_UPDATE") || envTruthy("DEEPLINE_NO_AUTO_UPDATE") || envTruthy("DEEPLINE_SKIP_SDK_AUTO_UPDATE") || envTruthy("DEEPLINE_DISABLE_AUTO_UPDATE") || isCi();
+}
+function relaunchCurrentCommand() {
+  return new Promise((resolve16) => {
+    const child = spawn3(process.execPath, process.argv.slice(1), {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        DEEPLINE_NO_AUTO_UPDATE: "1"
+      }
+    });
+    child.on("error", (error) => {
+      process.stderr.write(
+        `Deepline SDK/CLI updated, but relaunch failed: ${error.message}
+`
+      );
+      resolve16(1);
+    });
+    child.on("close", (code) => resolve16(code ?? 1));
+  });
+}
+async function maybeAutoUpdateAndRelaunch(response) {
+  const autoUpdate = response?.auto_update;
+  if (!response || !autoUpdate?.should_auto_update || shouldSkipSelfUpdate()) {
+    return false;
+  }
+  const plan = resolveUpdatePlan();
+  if (plan.kind !== "npm-global") {
+    return false;
+  }
+  const label = autoUpdate.required ? "requires an update" : "is more than the supported auto-update lag behind";
+  process.stderr.write(
+    `Deepline SDK/CLI ${label}; running ${plan.manualCommand}
+`
+  );
+  const updateExitCode = await runNpmGlobalUpdatePlan(plan);
+  if (updateExitCode !== 0) {
+    if (autoUpdate.required) {
+      throw new Error(
+        `Automatic Deepline SDK/CLI update failed with exit code ${updateExitCode}. ${response.message}`
+      );
+    }
+    process.stderr.write(
+      `Deepline SDK/CLI auto-update failed with exit code ${updateExitCode}; continuing with ${response.current ?? "current version"}.
+`
+    );
+    return false;
+  }
+  process.stderr.write("Deepline SDK/CLI updated; rerunning command.\n");
+  const exitCode = await relaunchCurrentCommand();
+  process.exit(exitCode);
+  return true;
+}
+
 // src/cli/skills-sync.ts
-import { spawn as spawn2, spawnSync } from "child_process";
+import { spawn as spawn4, spawnSync as spawnSync2 } from "child_process";
 import {
   existsSync as existsSync11,
   mkdirSync as mkdirSync6,
@@ -21082,6 +21487,7 @@ import { homedir as homedir7 } from "os";
 import { dirname as dirname12, join as join14 } from "path";
 var CHECK_TIMEOUT_MS2 = 3e3;
 var SDK_SKILL_NAME = "deepline-plays";
+var SDK_SKILL_NAMES = [SDK_SKILL_NAME, "deepline-plays-quickstart"];
 var attemptedSync = false;
 function shouldSkipSkillsSync() {
   const value = process.env.DEEPLINE_SKIP_SKILLS_SYNC?.trim().toLowerCase();
@@ -21198,19 +21604,19 @@ async function fetchSkillsUpdate(baseUrl, localVersion) {
   }
 }
 function buildSkillsInstallArgs(baseUrl) {
-  return buildSkillsAddArgs(baseUrl, SDK_SKILL_NAME);
+  return buildSkillsAddArgs(baseUrl, SDK_SKILL_NAMES);
 }
 function buildBunxSkillsInstallArgs(baseUrl) {
-  return buildSkillsAddArgs(baseUrl, SDK_SKILL_NAME, { firstArg: "--bun" });
+  return buildSkillsAddArgs(baseUrl, SDK_SKILL_NAMES, { firstArg: "--bun" });
 }
 function hasCommand(command) {
-  const result = spawnSync(command, ["--version"], {
+  const result = spawnSync2(command, ["--version"], {
     stdio: "ignore",
     shell: process.platform === "win32"
   });
   return result.status === 0;
 }
-function shellQuote3(arg) {
+function shellQuote4(arg) {
   return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
 function resolveSkillsInstallCommands(baseUrl) {
@@ -21218,7 +21624,7 @@ function resolveSkillsInstallCommands(baseUrl) {
   const npxInstall = {
     command: "npx",
     args: npxArgs,
-    manualCommand: `npx ${npxArgs.map(shellQuote3).join(" ")}`
+    manualCommand: `npx ${npxArgs.map(shellQuote4).join(" ")}`
   };
   if (hasCommand("bunx")) {
     const bunxArgs = buildBunxSkillsInstallArgs(baseUrl);
@@ -21226,7 +21632,7 @@ function resolveSkillsInstallCommands(baseUrl) {
       {
         command: "bunx",
         args: bunxArgs,
-        manualCommand: `bunx ${bunxArgs.map(shellQuote3).join(" ")}`
+        manualCommand: `bunx ${bunxArgs.map(shellQuote4).join(" ")}`
       },
       npxInstall
     ];
@@ -21235,7 +21641,7 @@ function resolveSkillsInstallCommands(baseUrl) {
 }
 function runOneSkillsInstall(install) {
   return new Promise((resolve16) => {
-    const child = spawn2(install.command, install.args, {
+    const child = spawn4(install.command, install.args, {
       stdio: ["ignore", "ignore", "pipe"],
       env: process.env
     });
@@ -21303,7 +21709,7 @@ async function syncSdkSkillsIfNeeded(baseUrl) {
   if (!update?.needsUpdate && !hasStaleInstalledSkill || !update?.remoteVersion) {
     return;
   }
-  writeSdkSkillsStatusLine("SDK skills changed; syncing deepline-plays skill...");
+  writeSdkSkillsStatusLine("SDK skills changed; syncing Deepline SDK skills...");
   const installed = await runSkillsInstall(baseUrl);
   if (!installed) return;
   if (installedSdkSkillHasStalePositionalExecuteExamples()) {
@@ -21526,7 +21932,9 @@ async function main() {
     progress?.phase("loading deepline cli");
   }
   const program = new Command3();
-  program.name("deepline").description("Deepline CLI (TypeScript SDK)").version(SDK_VERSION, "-v, --version", "Show version").exitOverride().showHelpAfterError().showSuggestionAfterError(true).addHelpText(
+  program.name("deepline").description(
+    "Deepline CLI \u2014 GTM enrichment tools, plays, and runs from your terminal."
+  ).version(SDK_VERSION, "-v, --version", "Show version").exitOverride().showHelpAfterError().showSuggestionAfterError(true).addHelpText(
     "after",
     `
 Common commands:
@@ -21567,11 +21975,23 @@ Exit codes:
       progress?.phase("checking sdk compatibility");
     }
     const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
-    await traceCliSpan(
+    const compatibility = await traceCliSpan(
       "cli.sdk_compatibility",
-      { baseUrl },
-      () => enforceSdkCompatibility(baseUrl)
+      { baseUrl, command: actionCommand.name() },
+      () => checkSdkCompatibility(baseUrl, {
+        command: actionCommand.name()
+      })
+    );
+    if (compatibility.error) {
+      return;
+    }
+    const relaunched = await maybeAutoUpdateAndRelaunch(
+      compatibility.response
     );
+    if (relaunched) {
+      return;
+    }
+    enforceSdkCompatibilityResponse(compatibility.response);
     if (printStartupPhase) {
       progress?.phase("checking sdk skills");
     }
@@ -21596,6 +22016,7 @@ Exit codes:
   registerDbCommands(program);
   registerFeedbackCommands(program);
   registerUpdateCommand(program);
+  registerQuickstartCommands(program);
   program.command("preflight").description("Run compact health, auth, and Deepline billing checks.").option("--json", "Force JSON output.").addHelpText(
     "after",
     `
@@ -21671,6 +22092,29 @@ Examples:
     process.stdout.write(`deepline ${SDK_VERSION}
 `);
   });
+  if (process.argv.slice(2).length === 0) {
+    if (!process.stdout.isTTY) {
+      printJson({
+        ok: false,
+        exitCode: 2,
+        code: "MISSING_COMMAND",
+        message: "No command provided.",
+        next: "deepline --help"
+      });
+      console.error("error: missing command (see: deepline --help)");
+    } else {
+      program.outputHelp({ error: true });
+      console.error("\nerror: missing command (see usage above)");
+    }
+    recordCliTrace({
+      phase: "cli.main_total",
+      ms: Date.now() - mainStartedAt,
+      ok: false,
+      error: "missing command"
+    });
+    process.exitCode = 2;
+    return;
+  }
   try {
     await program.parseAsync(process.argv);
     recordCliTrace({