deepline 0.1.259 → 0.1.261

package/dist/cli/index.mjs

@@ -159,7 +159,7 @@ configureProxyFromEnv();
 
 // src/cli/index.ts
 import { mkdtemp as mkdtemp2, rm as rm2, writeFile as writeFile5 } from "fs/promises";
-import { join as join15 } from "path";
+import { join as join18 } from "path";
 import { tmpdir as tmpdir4 } from "os";
 import { Command as Command4 } from "commander";
 
@@ -174,7 +174,7 @@ import {
   writeFileSync
 } from "fs";
 import { homedir } from "os";
-import { dirname, join, resolve } from "path";
+import { dirname, isAbsolute, join, resolve } from "path";
 
 // src/errors.ts
 var DeeplineError = class extends Error {
@@ -484,6 +484,21 @@ function resolveApiKeyForBaseUrl(baseUrl, explicitApiKey) {
     cliEnv[API_KEY_ENV]
   );
 }
+function resolveProjectApiKeyForBaseUrl(baseUrl, startDir = process.cwd()) {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  return firstNonEmpty(
+    ...loadProjectEnvCandidates(startDir).map(({ env }) => {
+      const projectBaseUrl = normalizeBaseUrl(env[HOST_URL_ENV] ?? "");
+      return projectBaseUrl === normalizedBaseUrl ? env[API_KEY_ENV] : "";
+    })
+  );
+}
+function resolveGlobalApiKeyForBaseUrl(baseUrl) {
+  return firstNonEmpty(
+    process.env[API_KEY_ENV],
+    loadCliEnv(normalizeBaseUrl(baseUrl) || baseUrl)[API_KEY_ENV]
+  );
+}
 function getResolvedProjectAuthSource(baseUrl, apiKey, startDir = process.cwd()) {
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
   const normalizedApiKey = apiKey.trim();
@@ -527,14 +542,79 @@ function mergeProjectEnvFile(filePath, values) {
 `, "utf-8");
 }
 function ensureProjectEnvIsIgnored(dir) {
+  ensureProjectPrivatePathsIgnored(dir, [
+    PROJECT_DEEPLINE_ENV_FILE,
+    ".deepline/"
+  ]);
+}
+function ensureProjectPrivatePathsIgnored(dir, entries) {
+  const gitDir = findNearestGitCommonDir(dir);
+  if (gitDir) {
+    const excludePath = join(gitDir, "info", "exclude");
+    const existing2 = existsSync(excludePath) ? readFileSync(excludePath, "utf-8") : "";
+    const existingEntries2 = new Set(
+      existing2.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+    );
+    const missing2 = entries.filter(
+      (entry) => !existingEntries2.has(entry) && !existingEntries2.has(`/${entry}`)
+    );
+    if (missing2.length === 0) return;
+    mkdirSync(dirname(excludePath), { recursive: true });
+    const prefix2 = existing2 && !existing2.endsWith("\n") ? "\n" : "";
+    writeFileSync(
+      excludePath,
+      `${existing2}${prefix2}${missing2.join("\n")}
+`,
+      "utf-8"
+    );
+    return;
+  }
   const gitignorePath = join(dir, ".gitignore");
-  const entry = PROJECT_DEEPLINE_ENV_FILE;
   const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
-  const alreadyIgnored = existing.split(/\r?\n/).map((line) => line.trim()).some((line) => line === entry || line === `/${entry}`);
-  if (alreadyIgnored) return;
+  const existingEntries = new Set(
+    existing.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+  );
+  const missing = entries.filter(
+    (entry) => !existingEntries.has(entry) && !existingEntries.has(`/${entry}`)
+  );
+  if (missing.length === 0) return;
   const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
-  writeFileSync(gitignorePath, `${existing}${prefix}${entry}
-`, "utf-8");
+  writeFileSync(
+    gitignorePath,
+    `${existing}${prefix}${missing.join("\n")}
+`,
+    "utf-8"
+  );
+}
+function findNearestGitCommonDir(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    const candidate = join(current, ".git");
+    if (existsSync(candidate)) {
+      try {
+        const stat2 = statSync(candidate);
+        if (stat2.isDirectory()) return candidate;
+        if (stat2.isFile()) {
+          const match = readFileSync(candidate, "utf8").match(
+            /^gitdir:\s*(.+)$/m
+          );
+          const rawGitDir = match?.[1]?.trim();
+          if (rawGitDir) {
+            const gitDir = isAbsolute(rawGitDir) ? rawGitDir : resolve(dirname(candidate), rawGitDir);
+            const commonDirPath = join(gitDir, "commondir");
+            if (!existsSync(commonDirPath)) return gitDir;
+            const rawCommonDir = readFileSync(commonDirPath, "utf8").trim();
+            return rawCommonDir ? isAbsolute(rawCommonDir) ? rawCommonDir : resolve(gitDir, rawCommonDir) : gitDir;
+          }
+        }
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
 }
 function saveProjectDeeplineEnvValues(values, startDir = process.cwd()) {
   const target = resolveProjectPinTarget(startDir);
@@ -621,7 +701,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.259",
+  version: "0.1.261",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",
@@ -1306,7 +1386,7 @@ function decodeSseFrame(frame) {
   return parsed;
 }
 function sleep(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
+  return new Promise((resolve15) => setTimeout(resolve15, ms));
 }
 function withCoworkNetworkHint(message) {
   if (!isCoworkLikeSandbox2() || message.includes(COWORK_NETWORK_HINT)) {
@@ -2278,14 +2358,14 @@ async function* observeRunEvents(options) {
   try {
     for (; ; ) {
       if (queue.length === 0) {
-        const waitForItem = new Promise((resolve14) => {
-          wake = resolve14;
+        const waitForItem = new Promise((resolve15) => {
+          wake = resolve15;
         });
         if (!sawFirstSnapshot) {
           const timedOut = await Promise.race([
             waitForItem.then(() => false),
             new Promise(
-              (resolve14) => setTimeout(() => resolve14(true), OBSERVE_BOOTSTRAP_TIMEOUT_MS)
+              (resolve15) => setTimeout(() => resolve15(true), OBSERVE_BOOTSTRAP_TIMEOUT_MS)
             )
           ]);
           if (timedOut && queue.length === 0) {
@@ -2503,7 +2583,7 @@ function parseEnvTestPolicyOverrides() {
   return normalizeTestPolicyOverrides(parsed, "DEEPLINE_TEST_POLICY_OVERRIDES");
 }
 function sleep2(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
+  return new Promise((resolve15) => setTimeout(resolve15, ms));
 }
 function isTransientCompileManifestError(error) {
   if (error instanceof DeeplineError && typeof error.statusCode === "number") {
@@ -5669,37 +5749,93 @@ import {
   writeFileSync as writeFileSync4
 } from "fs";
 import { hostname } from "os";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname4, join as join5 } from "path";
 var EXIT_OK = 0;
 var EXIT_AUTH = 3;
 var EXIT_SERVER = 5;
 function envFilePath(baseUrl) {
   return hostEnvFilePath(baseUrl);
 }
-function pendingClaimTokenPath(baseUrl) {
+function normalizeAuthScope(value) {
+  if (!value || value === "global") return "global";
+  if (value === "folder") return "folder";
+  throw new Error("--auth-scope must be one of: folder, global");
+}
+function parseAuthScope(args) {
+  const index = args.indexOf("--auth-scope");
+  return normalizeAuthScope(index >= 0 ? args[index + 1] : void 0);
+}
+function pendingClaimPath(baseUrl, scope) {
+  if (scope === "folder") {
+    const target = resolveProjectPinTarget();
+    if (!target.ok) {
+      throw new Error(
+        `Cowork project folder is ambiguous. Candidate folders: ${target.candidates.join(
+          ", "
+        )}. Set CLAUDE_PROJECT_DIR or cd into the intended project folder.`
+      );
+    }
+    return join5(target.dir, ".deepline", "setup", "pending-auth.json");
+  }
+  return `${hostConfigDirPath(baseUrl)}/pending-auth.json`;
+}
+function legacyPendingClaimTokenPath(baseUrl) {
   return `${hostConfigDirPath(baseUrl)}/pending-claim-token`;
 }
-function savePendingClaimToken(baseUrl, claimToken) {
-  const filePath = pendingClaimTokenPath(baseUrl);
+function savePendingClaim(baseUrl, claim) {
+  const filePath = pendingClaimPath(baseUrl, claim.scope);
   const dir = dirname4(filePath);
   if (!existsSync5(dir)) {
     mkdirSync4(dir, { recursive: true });
   }
-  writeFileSync4(filePath, `${claimToken}
-`, "utf-8");
+  writeFileSync4(filePath, `${JSON.stringify(claim, null, 2)}
+`, {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
-function readPendingClaimToken(baseUrl) {
-  const filePath = pendingClaimTokenPath(baseUrl);
-  if (!existsSync5(filePath)) return "";
+function readPendingAuthClaim(baseUrl, scope) {
+  let filePath;
   try {
-    return readFileSync5(filePath, "utf-8").trim();
+    filePath = pendingClaimPath(baseUrl, scope);
   } catch {
-    return "";
+    return null;
+  }
+  if (!existsSync5(filePath)) {
+    if (scope !== "global") return null;
+    try {
+      const claimToken = readFileSync5(
+        legacyPendingClaimTokenPath(baseUrl),
+        "utf-8"
+      ).trim();
+      return claimToken ? {
+        claimToken,
+        claimUrl: `${baseUrl}/api/v2/auth/cli/claim/${encodeURIComponent(claimToken)}`,
+        scope
+      } : null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const parsed = JSON.parse(readFileSync5(filePath, "utf-8"));
+    const claimToken = typeof parsed.claimToken === "string" ? parsed.claimToken.trim() : "";
+    if (!claimToken) return null;
+    return {
+      claimToken,
+      claimUrl: typeof parsed.claimUrl === "string" ? parsed.claimUrl.trim() : "",
+      scope
+    };
+  } catch {
+    return null;
   }
 }
-function clearPendingClaimToken(baseUrl) {
+function clearPendingClaim(baseUrl, scope) {
   try {
-    rmSync2(pendingClaimTokenPath(baseUrl), { force: true });
+    rmSync2(pendingClaimPath(baseUrl, scope), { force: true });
+    if (scope === "global") {
+      rmSync2(legacyPendingClaimTokenPath(baseUrl), { force: true });
+    }
   } catch {
   }
 }
@@ -5724,12 +5860,16 @@ function shouldWaitForRegisterClaim(mode) {
   if (mode === "no") return false;
   return detectAgentRuntime() !== "claude_cowork";
 }
-function saveEnvValues(values, baseUrl) {
+function saveEnvValues(values, baseUrl, scope) {
   const filtered = {
     ...values[HOST_URL_ENV] ? { [HOST_URL_ENV]: values[HOST_URL_ENV] } : {},
     ...values[API_KEY_ENV] ? { [API_KEY_ENV]: values[API_KEY_ENV] } : {}
   };
-  saveHostEnvValues(baseUrl, filtered);
+  if (scope === "folder") {
+    saveProjectDeeplineEnvValues(filtered);
+  } else {
+    saveHostEnvValues(baseUrl, filtered);
+  }
 }
 async function httpJson(method, url, apiKey, body) {
   const headers = {
@@ -5792,7 +5932,7 @@ function buildCandidateUrls2(url) {
   }
 }
 function sleep4(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
+  return new Promise((resolve15) => setTimeout(resolve15, ms));
 }
 function printDeeplineLogo() {
   if (process.stdout.isTTY && (process.stdout.columns ?? 80) >= 70) {
@@ -5853,8 +5993,13 @@ async function handleRegister(args) {
   let orgName = "";
   let agentName = "";
   let waitMode;
+  let authScope;
   try {
     waitMode = parseRegisterWaitMode(args);
+    authScope = parseAuthScope(args);
+    if (authScope === "folder") {
+      pendingClaimPath(baseUrl, authScope);
+    }
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     return 2;
@@ -5887,18 +6032,22 @@ async function handleRegister(args) {
   const claimUrl = String(data.claim_url || "");
   const claimToken = String(data.claim_token || "");
   if (claimToken) {
-    savePendingClaimToken(baseUrl, claimToken);
+    savePendingClaim(baseUrl, { claimToken, claimUrl, scope: authScope });
     saveEnvValues(
       {
         [HOST_URL_ENV]: baseUrl
       },
-      baseUrl
+      baseUrl,
+      authScope
     );
   }
   if (claimUrl) {
-    console.log("  Opening approval page in your browser.");
-    console.log(`  If it didn't open, cmd+click: ${claimUrl}`);
-    openInBrowser(claimUrl);
+    const shouldOpen = waitMode !== "no" && detectAgentRuntime() !== "claude_cowork";
+    console.log(
+      shouldOpen ? "  Opening approval page in your browser." : "  Open this approval page in your browser:"
+    );
+    console.log(`  ${claimUrl}`);
+    if (shouldOpen) openInBrowser(claimUrl);
   }
   if (data.cli_message) {
     console.log(String(data.cli_message));
@@ -5916,7 +6065,7 @@ async function handleRegister(args) {
       { claim_token: claimToken, reveal: true }
     );
     if (s === 401 || s === 403) {
-      clearPendingClaimToken(baseUrl);
+      clearPendingClaim(baseUrl, authScope);
       console.log("Status: unauthorized");
       return EXIT_AUTH;
     }
@@ -5937,15 +6086,16 @@ async function handleRegister(args) {
             [HOST_URL_ENV]: baseUrl,
             [API_KEY_ENV]: apiKey
           },
-          baseUrl
+          baseUrl,
+          authScope
         );
-        clearPendingClaimToken(baseUrl);
+        clearPendingClaim(baseUrl, authScope);
         await printClaimSuccessBanner(baseUrl, apiKey, statusData);
         return EXIT_OK;
       }
     }
     if (state === "expired") {
-      clearPendingClaimToken(baseUrl);
+      clearPendingClaim(baseUrl, authScope);
       console.log(
         "That approval link expired. Please run: deepline auth register"
       );
@@ -5957,6 +6107,13 @@ async function handleRegister(args) {
 async function handleWait(args) {
   const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
   let timeoutSeconds = 300;
+  let authScope;
+  try {
+    authScope = parseAuthScope(args);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 2;
+  }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--timeout" && args[i + 1]) {
       const parsed = Number.parseInt(args[++i], 10);
@@ -5965,9 +6122,11 @@ async function handleWait(args) {
       }
     }
   }
-  const claimToken = readPendingClaimToken(baseUrl);
-  if (!claimToken) {
-    if (resolveApiKeyForBaseUrl(baseUrl)) {
+  const pendingClaim = readPendingAuthClaim(baseUrl, authScope);
+  const claimToken = pendingClaim?.claimToken ?? "";
+  if (!pendingClaim) {
+    const scopedApiKey = authScope === "folder" ? resolveProjectApiKeyForBaseUrl(baseUrl) : resolveGlobalApiKeyForBaseUrl(baseUrl);
+    if (scopedApiKey) {
       console.log("Already connected.");
       return EXIT_OK;
     }
@@ -5983,7 +6142,7 @@ async function handleWait(args) {
       { claim_token: claimToken, reveal: true }
     );
     if (status === 401 || status === 403) {
-      clearPendingClaimToken(baseUrl);
+      clearPendingClaim(baseUrl, authScope);
       console.error("Claim is invalid. Run: deepline auth register");
       return EXIT_AUTH;
     }
@@ -6004,15 +6163,16 @@ async function handleWait(args) {
             [HOST_URL_ENV]: baseUrl,
             [API_KEY_ENV]: apiKey
           },
-          baseUrl
+          baseUrl,
+          authScope
         );
-        clearPendingClaimToken(baseUrl);
+        clearPendingClaim(baseUrl, authScope);
         await printClaimSuccessBanner(baseUrl, apiKey, data);
         return EXIT_OK;
       }
     }
     if (state === "expired") {
-      clearPendingClaimToken(baseUrl);
+      clearPendingClaim(baseUrl, authScope);
       console.error("That approval link expired. Run: deepline auth register");
       return EXIT_AUTH;
     }
@@ -6027,6 +6187,16 @@ async function handleStatus(args) {
   const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
   const reveal = args.includes("--reveal");
   const jsonOutput = argsWantJson(args);
+  const hasExplicitAuthScope = args.includes("--auth-scope");
+  let authScope = null;
+  if (hasExplicitAuthScope) {
+    try {
+      authScope = parseAuthScope(args);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 2;
+    }
+  }
   let hostStatusPayload = null;
   const hostLines = [];
   try {
@@ -6053,14 +6223,16 @@ async function handleStatus(args) {
     };
     hostLines.push(`Host: ${baseUrl} (unreachable)`);
   }
-  const apiKey = resolveApiKeyForBaseUrl(baseUrl);
+  const apiKey = authScope === "folder" ? resolveProjectApiKeyForBaseUrl(baseUrl) : authScope === "global" ? resolveGlobalApiKeyForBaseUrl(baseUrl) : resolveApiKeyForBaseUrl(baseUrl);
   if (!apiKey) {
-    if (readPendingClaimToken(baseUrl)) {
+    const pendingClaim = authScope ? readPendingAuthClaim(baseUrl, authScope) : readPendingAuthClaim(baseUrl, "folder") ?? readPendingAuthClaim(baseUrl, "global");
+    if (pendingClaim) {
       printCommandEnvelope(
         {
           ...hostStatusPayload ?? { host: baseUrl },
           status: "pending",
           connected: false,
+          authorization_url: pendingClaim.claimUrl || null,
           next: "deepline auth wait",
           render: {
             sections: [
@@ -6142,7 +6314,8 @@ async function handleStatus(args) {
     console.error(`Auth status error (status ${status}).`);
     return EXIT_SERVER;
   }
-  clearPendingClaimToken(baseUrl);
+  const resolvedAuthScope = authScope ?? (getResolvedProjectAuthSource(baseUrl, apiKey) ? "folder" : "global");
+  clearPendingClaim(baseUrl, resolvedAuthScope);
   const payload = {
     ...hostStatusPayload ?? { host: baseUrl },
     status: data.status || "(unknown)",
@@ -6167,9 +6340,15 @@ async function handleStatus(args) {
           [HOST_URL_ENV]: baseUrl,
           [API_KEY_ENV]: apiKeyResp
         },
-        baseUrl
+        baseUrl,
+        resolvedAuthScope
       );
-      savedApiKeyPath = envFilePath(baseUrl);
+      if (resolvedAuthScope === "folder") {
+        const target = resolveProjectPinTarget();
+        savedApiKeyPath = target.ok ? join5(target.dir, ".env.deepline") : null;
+      } else {
+        savedApiKeyPath = envFilePath(baseUrl);
+      }
     }
   }
   printCommandEnvelope(
@@ -6234,12 +6413,19 @@ Examples:
   deepline auth register
   deepline auth register --org-name Acme --agent-name local-cli
   deepline auth register --wait no
+  deepline auth register --auth-scope folder --wait no
 `
-  ).option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--wait <mode>", "Wait mode: auto, yes, or no", "auto").option("--no-wait", "Alias for --wait no").action(async (options) => {
+  ).option("--org-name <name>", "Workspace name to prefill").option("--agent-name <name>", "Agent name to register").option("--wait <mode>", "Wait mode: auto, yes, or no", "auto").option("--no-wait", "Alias for --wait no").option(
+    "--auth-scope <scope>",
+    "Credential scope: global or folder",
+    "global"
+  ).action(async (options) => {
     process.exitCode = await handleRegister([
       ...options.orgName ? ["--org-name", options.orgName] : [],
       ...options.agentName ? ["--agent-name", options.agentName] : [],
-      ...options.noWait || options.wait === false ? ["--wait", "no"] : ["--wait", String(options.wait ?? "auto")]
+      ...options.noWait || options.wait === false ? ["--wait", "no"] : ["--wait", String(options.wait ?? "auto")],
+      "--auth-scope",
+      String(options.authScope ?? "global")
     ]);
   });
   auth.command("wait").description("Wait for a pending browser approval and save the API key.").addHelpText(
@@ -6252,10 +6438,17 @@ Notes:
 Examples:
   deepline auth wait
   deepline auth wait --timeout 120
+  deepline auth wait --auth-scope folder --timeout 120
 `
-  ).option("--timeout <seconds>", "Maximum seconds to wait", "300").action(async (options) => {
+  ).option("--timeout <seconds>", "Maximum seconds to wait", "300").option(
+    "--auth-scope <scope>",
+    "Credential scope: global or folder",
+    "global"
+  ).action(async (options) => {
     process.exitCode = await handleWait([
-      ...options.timeout ? ["--timeout", options.timeout] : []
+      ...options.timeout ? ["--timeout", options.timeout] : [],
+      "--auth-scope",
+      String(options.authScope ?? "global")
     ]);
   });
   auth.command("status").description("Show the current CLI auth and workspace status.").addHelpText(
@@ -6268,14 +6461,16 @@ Notes:
 
 Examples:
   deepline auth status
+  deepline auth status --auth-scope folder
   deepline auth status --json
 `
   ).option(
     "--reveal",
     "Persist the revealed API key back to the host auth file"
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--auth-scope <scope>", "Read only folder or global auth").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleStatus([
       ...options.reveal ? ["--reveal"] : [],
+      ...options.authScope ? ["--auth-scope", String(options.authScope)] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
@@ -7486,7 +7681,7 @@ import {
   writeFileSync as writeFileSync6
 } from "fs";
 import { homedir as homedir6 } from "os";
-import { join as join5, resolve as resolve5 } from "path";
+import { join as join6, resolve as resolve5 } from "path";
 
 // src/cli/dataset-stats.ts
 import { writeFileSync as writeFileSync5 } from "fs";
@@ -8252,13 +8447,13 @@ async function handleCsvShow(options) {
   );
 }
 function csvRenderStatePath() {
-  return join5(homedir6(), ".local", "deepline", "runtime", "csv-render.json");
+  return join6(homedir6(), ".local", "deepline", "runtime", "csv-render.json");
 }
 function csvRenderLogPath() {
-  return join5(homedir6(), ".local", "deepline", "runtime", "csv-render.log");
+  return join6(homedir6(), ".local", "deepline", "runtime", "csv-render.log");
 }
 function ensureCsvRenderStateDir() {
-  mkdirSync5(join5(homedir6(), ".local", "deepline", "runtime"), {
+  mkdirSync5(join6(homedir6(), ".local", "deepline", "runtime"), {
     recursive: true
   });
 }
@@ -9037,7 +9232,7 @@ import {
   writeFile as writeFile3
 } from "fs/promises";
 import { homedir as homedir7, tmpdir as tmpdir2 } from "os";
-import { basename as basename2, dirname as dirname7, extname, join as join7, resolve as resolve9 } from "path";
+import { basename as basename2, dirname as dirname7, extname, join as join8, resolve as resolve9 } from "path";
 import { Option } from "commander";
 
 // src/cli/commands/play.ts
@@ -9050,7 +9245,7 @@ import {
   statSync as statSync3,
   writeFileSync as writeFileSync9
 } from "fs";
-import { basename, dirname as dirname6, join as join6, resolve as resolve8 } from "path";
+import { basename, dirname as dirname6, join as join7, resolve as resolve8 } from "path";
 import { parse as parseCsvSync2 } from "csv-parse/sync";
 
 // src/cli/commands/plays/bootstrap.ts
@@ -9061,7 +9256,7 @@ import {
   statSync as statSync2,
   writeFileSync as writeFileSync8
 } from "fs";
-import { isAbsolute, relative, resolve as resolve7 } from "path";
+import { isAbsolute as isAbsolute2, relative, resolve as resolve7 } from "path";
 import { parse as parseCsvSync } from "csv-parse/sync";
 
 // ../shared_libs/plays/bootstrap-routes.ts
@@ -9709,7 +9904,7 @@ function packagedCsvPathForPlay(csvPath) {
   const playDir = process.cwd();
   const absoluteCsvPath = resolve7(csvPath);
   const relativePath = relative(playDir, absoluteCsvPath);
-  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute2(relativePath)) {
     throw new PlayBootstrapUsageError(
       `--from csv:${csvPath} must point to a file inside the directory where you run plays bootstrap. Run bootstrap from the intended play directory and write the play with --out there.`
     );
@@ -11331,7 +11526,7 @@ function traceCliSync(phase, fields, run) {
   }
 }
 function sleep5(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
+  return new Promise((resolve15) => setTimeout(resolve15, ms));
 }
 function parseReferencedPlayTarget2(target) {
   const trimmed = target.trim();
@@ -15985,7 +16180,7 @@ async function handlePlayRun(args, hooks) {
         if (siblings.length > 0) {
           console.error(`Did you mean one of these?`);
           for (const s of siblings.slice(0, 5)) {
-            console.error(`  ${join6(dir, s)}`);
+            console.error(`  ${join7(dir, s)}`);
           }
         }
       } catch {
@@ -19646,7 +19841,7 @@ function emitEnrichDebug(message) {
   );
 }
 function sleep6(ms) {
-  return new Promise((resolve14) => setTimeout(resolve14, ms));
+  return new Promise((resolve15) => setTimeout(resolve15, ms));
 }
 function enrichExportBackingRowsWaitMs() {
   const raw = process.env.DEEPLINE_ENRICH_EXPORT_BACKING_ROWS_WAIT_MS?.trim();
@@ -19678,7 +19873,7 @@ function expandAtFilePath(rawPath) {
     return homedir7();
   }
   if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
-    return join7(homedir7(), expanded.slice(2));
+    return join8(homedir7(), expanded.slice(2));
   }
   return expanded;
 }
@@ -22048,7 +22243,7 @@ function sidecarEnrichRowsExportPath(outputPath) {
   const resolved = resolve9(outputPath);
   const ext = extname(resolved) || ".csv";
   const stem = basename2(resolved, ext);
-  return join7(dirname7(resolved), `${stem}.deepline-enrich-rows${ext}`);
+  return join8(dirname7(resolved), `${stem}.deepline-enrich-rows${ext}`);
 }
 function collectDatasetFollowUpCommands(value, state) {
   if (state.depth > 12 || !value || typeof value !== "object" || state.commands.length >= 8) {
@@ -22129,10 +22324,10 @@ async function persistEnrichFailureReport(input2) {
   if (input2.jobs.length === 0 && input2.issues.length === 0) {
     return null;
   }
-  const stateDir = join7(homedir7(), ".local", "deepline", "runtime", "state");
+  const stateDir = join8(homedir7(), ".local", "deepline", "runtime", "state");
   const reportPrefix = input2.jobs.length > 0 ? "run-block-failures" : "enrich-issues";
   await mkdir3(stateDir, { recursive: true });
-  const reportPath = join7(
+  const reportPath = join8(
     stateDir,
     `${reportPrefix}-${Math.floor(Date.now() / 1e3)}-${process.pid}.json`
   );
@@ -23036,9 +23231,9 @@ function registerEnrichCommand(program) {
       sdkEnrichTelemetryCompleted = true;
       await completeSdkEnrichTelemetry(sdkEnrichTelemetry, input2);
     };
-    const tempDir = await mkdtemp(join7(tmpdir2(), "deepline-enrich-play-"));
+    const tempDir = await mkdtemp(join8(tmpdir2(), "deepline-enrich-play-"));
     await emitSdkEnrichTelemetry(sdkEnrichTelemetry, "enrich_started");
-    const tempPlay = join7(tempDir, "deepline-enrich.play.ts");
+    const tempPlay = join8(tempDir, "deepline-enrich.play.ts");
     let inPlaceTempDir = null;
     let inPlaceTempOutputPath = null;
     const inPlaceFinalOutputPath = options.inPlace ? resolve9(inputCsv) : null;
@@ -23066,12 +23261,12 @@ function registerEnrichCommand(program) {
         await rm(inPlaceTempDir, { recursive: true, force: true });
       }
       inPlaceTempDir = await mkdtemp(
-        join7(
+        join8(
           dirname7(inPlaceCommitOutputPath ?? resolve9(inputCsv)),
           ".deepline-enrich-in-place-"
         )
       );
-      inPlaceTempOutputPath = join7(inPlaceTempDir, "output.csv");
+      inPlaceTempOutputPath = join8(inPlaceTempDir, "output.csv");
       await copyFile(resolve9(inputCsv), inPlaceTempOutputPath);
       outputPath = inPlaceTempOutputPath;
     };
@@ -23352,7 +23547,7 @@ import {
   writeFileSync as writeFileSync10
 } from "fs";
 import { homedir as homedir8, platform } from "os";
-import { basename as basename3, dirname as dirname8, join as join8, resolve as resolve10 } from "path";
+import { basename as basename3, dirname as dirname8, join as join9, resolve as resolve10 } from "path";
 import { gzipSync } from "zlib";
 import { randomUUID as randomUUID3 } from "crypto";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -23378,10 +23573,10 @@ function detectShellContext() {
   };
 }
 function claudeProjectsRoot() {
-  return join8(homeDir(), ".claude", "projects");
+  return join9(homeDir(), ".claude", "projects");
 }
 function codexSessionsRoot() {
-  return join8(homeDir(), ".codex", "sessions");
+  return join9(homeDir(), ".codex", "sessions");
 }
 function listClaudeSessionFiles() {
   const root = claudeProjectsRoot();
@@ -23389,10 +23584,10 @@ function listClaudeSessionFiles() {
   const projectDirs = readDirectoryNames(root);
   const files = [];
   for (const projectDir of projectDirs) {
-    const fullProjectDir = join8(root, projectDir);
+    const fullProjectDir = join9(root, projectDir);
     for (const fileName of readDirectoryNames(fullProjectDir)) {
       if (fileName.endsWith(".jsonl")) {
-        const filePath = join8(fullProjectDir, fileName);
+        const filePath = join9(fullProjectDir, fileName);
         const sessionId = sessionIdFromClaudeFilePath(filePath);
         const stat2 = statIfReadable(filePath);
         if (sessionId && stat2) {
@@ -23449,7 +23644,7 @@ function listJsonlFilesRecursive(root, maxDepth) {
       return;
     }
     for (const entry of entries) {
-      const fullPath = join8(dir, entry.name);
+      const fullPath = join9(dir, entry.name);
       if (entry.isDirectory()) {
         visit(fullPath, depth + 1);
       } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
@@ -23864,8 +24059,8 @@ function loadViewerAssets() {
   const cliEntry = process.argv[1]?.trim() ? resolve10(process.argv[1]) : null;
   const candidateRoots2 = [
     ...cliEntry ? [
-      join8(dirname8(dirname8(cliEntry)), "viewer"),
-      join8(
+      join9(dirname8(dirname8(cliEntry)), "viewer"),
+      join9(
         dirname8(dirname8(dirname8(cliEntry))),
         "src",
         "lib",
@@ -23873,12 +24068,12 @@ function loadViewerAssets() {
         "viewer"
       )
     ] : [],
-    join8(process.cwd(), "src", "lib", "cli", "viewer")
+    join9(process.cwd(), "src", "lib", "cli", "viewer")
   ];
   for (const root of candidateRoots2) {
     try {
-      const cssPath = join8(root, "viewer.css");
-      const jsPath = join8(root, "viewer.js");
+      const cssPath = join9(root, "viewer.css");
+      const jsPath = join9(root, "viewer.js");
       if (!existsSync8(cssPath) || !existsSync8(jsPath)) continue;
       return {
         css: readFileSync8(cssPath, "utf8"),
@@ -23908,9 +24103,9 @@ async function handleSessionsRender(options) {
   });
   let outputPath = options.output ? resolve10(options.output) : "";
   if (!outputPath) {
-    const outputDir = join8(process.cwd(), "deepline", "data");
+    const outputDir = join9(process.cwd(), "deepline", "data");
     mkdirSync6(outputDir, { recursive: true });
-    outputPath = join8(
+    outputPath = join9(
       outputDir,
       targets.length > 1 ? "session-viewer.html" : `session-${targets[0]?.sessionId}.html`
     );
@@ -25080,7 +25275,7 @@ Examples:
 async function fetchOrganizations(http2, apiKey) {
   return http2.post("/api/v2/auth/cli/organizations", { api_key: apiKey });
 }
-function normalizeAuthScope(value) {
+function normalizeAuthScope2(value) {
   if (!value) return "auto";
   if (value === "auto" || value === "folder" || value === "global") {
     return value;
@@ -25283,7 +25478,7 @@ async function handleOrgStatus(options) {
   );
 }
 async function handleOrgSwitch(selection, options) {
-  const authScope = normalizeAuthScope(options.authScope);
+  const authScope = normalizeAuthScope2(options.authScope);
   const config = resolveConfig();
   const http2 = new HttpClient(config);
   const payload = await fetchOrganizations(http2, config.apiKey);
@@ -25660,17 +25855,17 @@ function hasClaudeBinary() {
   }
 }
 function launchClaude(prompt) {
-  return new Promise((resolve14) => {
+  return new Promise((resolve15) => {
     const child = spawn2("claude", [prompt], {
       stdio: "inherit",
       shell: process.platform === "win32"
     });
-    child.on("error", () => resolve14(EXIT_SERVER3));
-    child.on("close", (status) => resolve14(status ?? EXIT_OK2));
+    child.on("error", () => resolve15(EXIT_SERVER3));
+    child.on("close", (status) => resolve15(status ?? EXIT_OK2));
   });
 }
 function readBody(req) {
-  return new Promise((resolve14, reject) => {
+  return new Promise((resolve15, reject) => {
     let raw = "";
     req.setEncoding("utf8");
     req.on("data", (chunk) => {
@@ -25680,7 +25875,7 @@ function readBody(req) {
         req.destroy();
       }
     });
-    req.on("end", () => resolve14(raw));
+    req.on("end", () => resolve15(raw));
     req.on("error", reject);
   });
 }
@@ -25735,7 +25930,7 @@ function startCallbackServer(input2) {
       writeJson(res, 400, { error: "Invalid request body." });
     });
   });
-  return new Promise((resolve14, reject) => {
+  return new Promise((resolve15, reject) => {
     server.once("error", reject);
     server.listen(0, "127.0.0.1", () => {
       const address = server.address();
@@ -25743,7 +25938,7 @@ function startCallbackServer(input2) {
         reject(new Error("Failed to bind quickstart callback server."));
         return;
       }
-      resolve14({ server, port: address.port });
+      resolve15({ server, port: address.port });
     });
   });
 }
@@ -25769,8 +25964,8 @@ async function handleQuickstart(options) {
   }
   const state = randomBytes(32).toString("hex");
   let resolveSelection;
-  const selectionPromise = new Promise((resolve14) => {
-    resolveSelection = resolve14;
+  const selectionPromise = new Promise((resolve15) => {
+    resolveSelection = resolve15;
   });
   let callback;
   try {
@@ -25909,7 +26104,7 @@ async function readHiddenLine(prompt, streams = {}) {
   }
   let value = "";
   inputStream.resume();
-  return await new Promise((resolve14, reject) => {
+  return await new Promise((resolve15, reject) => {
     let settled = false;
     const cleanup = () => {
       inputStream.off("data", onData);
@@ -25927,7 +26122,7 @@ async function readHiddenLine(prompt, streams = {}) {
       settled = true;
       outputStream.write("\n");
       cleanup();
-      resolve14(line);
+      resolve15(line);
     };
     const fail = (error) => {
       if (settled) return;
@@ -26100,7 +26295,7 @@ Examples:
 // src/cli/commands/switch.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir9 } from "os";
-import { dirname as dirname9, join as join9 } from "path";
+import { dirname as dirname9, join as join10 } from "path";
 function hostSlugFromBaseUrl(baseUrl) {
   try {
     const url = new URL(baseUrl);
@@ -26121,7 +26316,7 @@ function resolveConfigScope() {
 }
 function activeFamilyPath() {
   const home = process.env.HOME || process.env.USERPROFILE || homedir9();
-  return join9(
+  return join10(
     home,
     ".local",
     "deepline",
@@ -26266,7 +26461,7 @@ import {
   writeFileSync as writeFileSync13
 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
-import { join as join11, resolve as resolve11 } from "path";
+import { join as join12, resolve as resolve11 } from "path";
 
 // src/tool-output.ts
 import {
@@ -26277,7 +26472,7 @@ import {
   writeSync
 } from "fs";
 import { homedir as homedir10 } from "os";
-import { dirname as dirname10, join as join10 } from "path";
+import { dirname as dirname10, join as join11 } from "path";
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -26404,18 +26599,18 @@ function projectRowOutput(conversion) {
   };
 }
 function ensureOutputDir() {
-  const outputDir = join10(homedir10(), ".local", "share", "deepline", "data");
+  const outputDir = join11(homedir10(), ".local", "share", "deepline", "data");
   mkdirSync8(outputDir, { recursive: true });
   return outputDir;
 }
 function writeJsonOutputFile(payload, stem) {
   const outputDir = ensureOutputDir();
-  const outputPath = join10(outputDir, `${stem}_${Date.now()}.json`);
+  const outputPath = join11(outputDir, `${stem}_${Date.now()}.json`);
   writeFileSync12(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
 function writeCsvOutputFile(rows, stem, options) {
-  const outputPath = options?.outPath ? options.outPath : join10(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
+  const outputPath = options?.outPath ? options.outPath : join11(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
   mkdirSync8(dirname10(outputPath), { recursive: true });
   const columns = columnsForRows(rows);
   const escapeCell = (value) => {
@@ -27812,9 +28007,9 @@ function starterScriptJson(script) {
 function seedToolListScript(input2) {
   const stem = safeFileStem(input2.toolId);
   const fileName = `${stem}-workflow-seed-${Date.now()}.play.ts`;
-  const scriptDir = mkdtempSync(join11(tmpdir3(), "deepline-workflow-seed-"));
+  const scriptDir = mkdtempSync(join12(tmpdir3(), "deepline-workflow-seed-"));
   chmodSync(scriptDir, 448);
-  const scriptPath = join11(scriptDir, fileName);
+  const scriptPath = join12(scriptDir, fileName);
   const projectDir = `deepline/projects/${stem}-workflow`;
   const playName = `${stem}-workflow`;
   const sampleRows = input2.rows.length > 0 ? `${JSON.stringify(input2.rows.slice(0, 2)).replace(/\]$/, "")}, ...]` : "[]";
@@ -28200,7 +28395,7 @@ async function executeTool(args) {
 
 // src/cli/commands/workflow.ts
 import { mkdir as mkdir4, readFile as readFile2, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname11, join as join12, resolve as resolve12 } from "path";
+import { dirname as dirname11, join as join13, resolve as resolve12 } from "path";
 
 // src/cli/workflow-to-play.ts
 import { createHash as createHash3 } from "crypto";
@@ -28489,7 +28684,7 @@ async function transformOne(api, workflowId, outDir, publish) {
       revision.config,
       { workflowName: workflow.name, version: revision.version }
     );
-    const file = join12(resolve12(outDir), `${compiled.playName}.play.ts`);
+    const file = join13(resolve12(outDir), `${compiled.playName}.play.ts`);
     await mkdir4(dirname11(file), { recursive: true });
     await writeFile4(file, compiled.sourceCode, "utf8");
     let published = false;
@@ -28748,22 +28943,17 @@ import {
   readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
-  unlinkSync as unlinkSync2,
+  unlinkSync,
   writeFileSync as writeFileSync15
 } from "fs";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname13, isAbsolute as isAbsolute2, join as join14, relative as relative2, resolve as resolve13 } from "path";
+import { homedir as homedir12 } from "os";
+import { dirname as dirname13, isAbsolute as isAbsolute3, join as join15, relative as relative2, resolve as resolve13 } from "path";
 
-// src/cli/skills-sync.ts
-import { spawn as spawn3, spawnSync as spawnSync2 } from "child_process";
-import {
-  existsSync as existsSync11,
-  mkdirSync as mkdirSync9,
-  readFileSync as readFileSync12,
-  unlinkSync,
-  writeFileSync as writeFileSync14
-} from "fs";
-import { dirname as dirname12, join as join13 } from "path";
+// src/cli/commands/skills.ts
+import { spawn as spawn3 } from "child_process";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
+import { homedir as homedir11 } from "os";
+import { dirname as dirname12, join as join14 } from "path";
 
 // ../shared_libs/cli/install-commands.json
 var install_commands_default = {
@@ -28779,7 +28969,7 @@ var install_commands_default = {
     npx_binary: "npx",
     npx_add_args_template: [
       "--yes",
-      "skills",
+      "skills@latest",
       "add",
       "{skills_index_url}",
       "--agent",
@@ -28869,311 +29059,380 @@ function sdkNpmGlobalInstallCommand() {
   return INSTALL_COMMANDS.cli.sdk_npm_global;
 }
 
-// src/cli/skills-sync.ts
-var CHECK_TIMEOUT_MS2 = 3e3;
-var attemptedSync = false;
-function shouldSkipSkillsSync() {
-  if (detectAgentRuntime() === "claude_cowork") {
-    return true;
-  }
-  const value = process.env.DEEPLINE_SKIP_SKILLS_SYNC?.trim().toLowerCase();
-  return value === "1" || value === "true" || value === "yes" || value === "on";
+// src/cli/commands/skills.ts
+var RUNTIME_TO_SKILLS_AGENT = {
+  antigravity: "antigravity",
+  claude_code: "claude-code",
+  claude_cowork: "claude-code",
+  cline: "cline",
+  codex: "codex",
+  cursor: "cursor",
+  gemini: "gemini-cli",
+  windsurf: "windsurf"
+};
+var AGENT_MARKERS = [
+  { agent: "codex", paths: [".codex"] },
+  { agent: "claude-code", paths: [".claude"] },
+  { agent: "cursor", paths: [".cursor"] },
+  { agent: "gemini-cli", paths: [".gemini", ".gemini-cli"] },
+  { agent: "antigravity", paths: [".antigravity"] }
+];
+var WORKSPACE_SKILL_ROOTS_BY_AGENT = {
+  antigravity: [".agents"],
+  "claude-code": [".claude"],
+  cline: [".agents"],
+  codex: [".agents"],
+  cursor: [".agents"],
+  "gemini-cli": [".agents"],
+  windsurf: [".windsurf"],
+  "*": [".agents", ".claude", ".windsurf"]
+};
+function workspaceSkillRootsForAgents(agents) {
+  return [
+    ...new Set(
+      agents.flatMap((agent) => WORKSPACE_SKILL_ROOTS_BY_AGENT[agent] ?? [])
+    )
+  ].sort((a, b) => a.localeCompare(b));
 }
-function activePluginSkillsDir() {
-  const pluginMode = process.env.DEEPLINE_PLUGIN_MODE?.trim().toLowerCase();
-  if (pluginMode !== "true" && pluginMode !== "1" && pluginMode !== "yes" && pluginMode !== "on") {
-    return "";
-  }
-  const dir = process.env.DEEPLINE_PLUGIN_SKILLS_DIR?.trim() ?? "";
-  return dir && existsSync11(dir) ? dir : "";
+function normalizeScope(value) {
+  if (value === "global") return "global";
+  if (value === "local") return "local";
+  if (!value) return inferActiveSkillsScope();
+  throw new Error("--scope must be one of: global, local");
 }
-function readPluginSkillsVersion() {
-  const dir = activePluginSkillsDir();
-  if (!dir) return "";
-  try {
-    return readFileSync12(join13(dir, ".version"), "utf-8").trim();
-  } catch {
-    return "";
+function inferActiveSkillsScope(entrypoint = process.argv[1] ?? "") {
+  return /[\\/]\.deepline[\\/]runtime[\\/]/.test(entrypoint) ? "local" : "global";
+}
+function resolveLocalRoot() {
+  const target = resolveProjectPinTarget();
+  if (!target.ok) {
+    throw new Error(
+      `Cowork project folder is ambiguous. Candidate folders: ${target.candidates.join(
+        ", "
+      )}. Set CLAUDE_PROJECT_DIR or cd into the intended project folder.`
+    );
   }
+  return target.dir;
 }
-function sdkSkillsVersionPath(baseUrl) {
-  return join13(sdkCliStateDirPath(baseUrl), "skills-version");
+function detectSkillsAgents(input2) {
+  const runtime = input2.runtime ?? detectAgentRuntime();
+  const knownAgent = RUNTIME_TO_SKILLS_AGENT[runtime];
+  if (knownAgent) return [knownAgent];
+  const roots = [
+    ...input2.scope === "local" && input2.root ? [input2.root] : [],
+    input2.homeDir ?? homedir11()
+  ];
+  const detected = AGENT_MARKERS.filter(
+    (marker) => roots.some(
+      (root) => marker.paths.some((path) => existsSync11(join14(root, path)))
+    )
+  ).map((marker) => marker.agent);
+  return detected.length > 0 ? detected : ["*"];
 }
-function legacySdkSkillsVersionPath(baseUrl) {
-  return join13(dirname12(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
+async function fetchSkillCatalog(baseUrl) {
+  const response = await fetch(skillsIndexUrl(baseUrl));
+  if (!response.ok) {
+    throw new Error(
+      `Skill catalog request failed (status ${response.status}).`
+    );
+  }
+  const index = await response.json();
+  const skillNames = (index.skills ?? []).filter((skill) => skill.install_surface === "v1").map((skill) => skill.name).filter((name) => typeof name === "string" && Boolean(name)).sort((a, b) => a.localeCompare(b));
+  if (skillNames.length === 0) {
+    throw new Error(
+      "The Deepline skill catalog contains no installable skills."
+    );
+  }
+  return {
+    skillNames,
+    version: typeof index.version === "string" && index.version.trim() ? index.version.trim() : "unversioned"
+  };
 }
-function unavailableSkillsNoticePath(baseUrl) {
-  return join13(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+function skillsStatePathForScope(baseUrl, scope, root) {
+  return scope === "local" && root ? join14(root, ".deepline", "setup", "skills.json") : join14(sdkCliStateDirPath(baseUrl), "skills-install.json");
 }
-function readSdkSkillsLocalVersion(baseUrl) {
-  const pluginVersion = readPluginSkillsVersion();
-  if (pluginVersion) return pluginVersion;
-  const path = existsSync11(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
-  if (!existsSync11(path)) return "";
-  try {
-    return readFileSync12(path, "utf-8").trim();
-  } catch {
-    return "";
-  }
+function buildSkillsPlan(input2) {
+  const scopeArgs = input2.scope === "global" ? ["--global"] : [];
+  const allManagedNames = [
+    .../* @__PURE__ */ new Set([...input2.skillNames, ...LEGACY_SKILL_NAMES_TO_REMOVE])
+  ].sort((a, b) => a.localeCompare(b));
+  return {
+    scope: input2.scope,
+    root: input2.root,
+    agents: input2.agents,
+    skillNames: input2.skillNames,
+    version: input2.version,
+    remove: {
+      command: "npm",
+      args: [
+        "exec",
+        "--yes",
+        "--package=skills@latest",
+        "--",
+        "skills",
+        "remove",
+        ...scopeArgs,
+        "--agent",
+        ...input2.agents,
+        "-y",
+        ...allManagedNames
+      ]
+    },
+    install: {
+      command: "npm",
+      args: [
+        "exec",
+        "--yes",
+        "--package=skills@latest",
+        "--",
+        "skills",
+        "add",
+        skillsIndexUrl(input2.baseUrl),
+        "--agent",
+        ...input2.agents,
+        ...scopeArgs,
+        "--yes",
+        ...input2.skillNames.flatMap((name) => ["--skill", name]),
+        "--full-depth"
+      ]
+    },
+    statePath: skillsStatePathForScope(input2.baseUrl, input2.scope, input2.root)
+  };
 }
-function writeLocalSkillsVersion(baseUrl, version) {
-  const path = sdkSkillsVersionPath(baseUrl);
-  mkdirSync9(dirname12(path), { recursive: true });
-  writeFileSync14(path, `${version}
-`, "utf-8");
+function sortedStrings(value) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    return null;
+  }
+  return [...value].sort((a, b) => a.localeCompare(b));
 }
-function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
-  const path = unavailableSkillsNoticePath(baseUrl);
-  try {
-    if (existsSync11(path) && readFileSync12(path, "utf-8").trim() === remoteVersion) {
-      return;
-    }
-    mkdirSync9(dirname12(path), { recursive: true });
-    writeFileSync14(path, `${remoteVersion}
-`, "utf-8");
-  } catch {
+function isSkillsPlanCurrent(plan, state) {
+  if (!state || state.scope !== plan.scope || state.skillsVersion !== plan.version) {
+    return false;
   }
-  const manualCommand = `npx ${buildSkillsInstallArgs(baseUrl, skillNames).join(" ")}`;
-  writeSdkSkillsStatusLine(
-    `Deepline agent skills are out of date, but neither \`bunx\` nor \`npx\` is available. Install Node.js/npm or Bun, then run:
-${manualCommand}`
-  );
+  const installedAgents = sortedStrings(state.agents);
+  const installedSkillNames = sortedStrings(state.skillNames);
+  if (!installedAgents || !installedSkillNames) return false;
+  return installedAgents.join("\0") === [...plan.agents].sort((a, b) => a.localeCompare(b)).join("\0") && installedSkillNames.join("\0") === [...plan.skillNames].sort((a, b) => a.localeCompare(b)).join("\0");
 }
-function clearUnavailableSkillsNotice(baseUrl) {
+function readSkillsInstallState(path) {
   try {
-    unlinkSync(unavailableSkillsNoticePath(baseUrl));
+    const parsed = JSON.parse(readFileSync12(path, "utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
   } catch {
+    return null;
   }
 }
-function sortedUniqueSkillNames(names) {
-  return [...new Set(names.map((name) => name.trim()).filter(Boolean))].sort(
-    (a, b) => a.localeCompare(b)
-  );
+function runProcess(command, args, cwd) {
+  return new Promise((resolve15, reject) => {
+    const child = spawn3(command, args, {
+      cwd,
+      env: process.env,
+      stdio: ["ignore", "ignore", "pipe"],
+      shell: process.platform === "win32"
+    });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+      process.stderr.write(chunk);
+    });
+    child.once("error", reject);
+    child.once("close", (code) => {
+      if (code && stderr.trim()) {
+        process.stderr.write(`skills@latest exited ${code}.
+`);
+      }
+      resolve15(code ?? 1);
+    });
+  });
 }
-async function fetchV1SkillNames(baseUrl) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS2);
+async function runSkillsCommand(options, dependencies = {}) {
+  let scope;
+  let root;
   try {
-    const response = await fetch(
-      new URL("/.well-known/skills/index.json", baseUrl),
-      { signal: controller.signal }
-    );
-    if (!response.ok) return [];
-    const data = await response.json().catch(() => null);
-    const names = (data?.skills ?? []).filter((skill) => skill.install_surface === "v1").map((skill) => skill.name).filter(
-      (name) => typeof name === "string" && name.length > 0
+    scope = normalizeScope(options.scope);
+    root = scope === "local" ? resolveLocalRoot() : null;
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "INVALID_SKILLS_SCOPE",
+        exitCode: 2,
+        message: error instanceof Error ? error.message : String(error)
+      },
+      { json: options.json }
     );
-    return sortedUniqueSkillNames(names);
-  } catch {
-    return [];
-  } finally {
-    clearTimeout(timeout);
+    return 2;
   }
-}
-function buildSdkSkillNames(v1SkillNames) {
-  return sortedUniqueSkillNames(v1SkillNames);
-}
-async function fetchSkillsUpdate(baseUrl, localVersion) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS2);
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  let catalog;
   try {
-    const response = await fetch(new URL("/api/v2/cli/update-check", baseUrl), {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        skills: {
-          version: localVersion
-        }
-      }),
-      signal: controller.signal
-    });
-    if (!response.ok) return null;
-    const data = await response.json().catch(() => null);
-    const skills = data?.skills;
-    if (!skills) return null;
-    return {
-      needsUpdate: skills.needs_update === true,
-      remoteVersion: typeof skills.remote?.version === "string" ? skills.remote.version.trim() : ""
-    };
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
+    catalog = options.dryRun ? { skillNames: [...DEFAULT_SDK_SKILL_NAMES], version: "latest" } : await (dependencies.fetchCatalog ?? fetchSkillCatalog)(baseUrl);
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "SKILLS_CATALOG_UNAVAILABLE",
+        exitCode: 5,
+        message: error instanceof Error ? error.message : String(error),
+        next: "Retry: deepline skills"
+      },
+      { json: options.json }
+    );
+    return 5;
   }
-}
-function buildSkillsInstallArgs(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
-  return buildSkillsAddArgs(baseUrl, sortedUniqueSkillNames(skillNames));
-}
-function buildBunxSkillsInstallArgs(baseUrl, skillNames) {
-  return buildSkillsAddArgs(baseUrl, sortedUniqueSkillNames(skillNames), {
-    firstArg: "--bun"
-  });
-}
-function hasCommand(command) {
-  const result = spawnSync2(command, ["--version"], {
-    stdio: "ignore",
-    shell: process.platform === "win32"
-  });
-  return result.status === 0;
-}
-function shellQuote5(arg) {
-  return `'${arg.replace(/'/g, `'\\''`)}'`;
-}
-function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
-  const commands = [];
-  if (hasCommand("bunx")) {
-    const bunxArgs = buildBunxSkillsInstallArgs(baseUrl, skillNames);
-    commands.push({
-      command: "bunx",
-      args: bunxArgs,
-      manualCommand: `bunx ${bunxArgs.map(shellQuote5).join(" ")}`
-    });
+  const agents = options.agent ? [options.agent] : detectSkillsAgents({ scope, root });
+  const plan = buildSkillsPlan({ baseUrl, scope, root, agents, ...catalog });
+  if (options.dryRun) {
+    printCommandEnvelope(
+      { ok: true, status: "planned", dryRun: true, ...plan },
+      { json: options.json }
+    );
+    return 0;
   }
-  if (hasCommand("npx")) {
-    const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
-    commands.push({
-      command: "npx",
-      args: npxArgs,
-      manualCommand: `npx ${npxArgs.map(shellQuote5).join(" ")}`
-    });
+  if (isSkillsPlanCurrent(plan, readSkillsInstallState(plan.statePath))) {
+    printCommandEnvelope(
+      {
+        ok: true,
+        status: "current",
+        complete: true,
+        changed: false,
+        skipped: true,
+        skipReason: "skills_version_current",
+        scope,
+        agents,
+        skillsVersion: plan.version,
+        skillCount: plan.skillNames.length,
+        statePath: plan.statePath,
+        render: {
+          sections: [
+            {
+              title: "skills",
+              lines: [
+                `Scope: ${scope}`,
+                `Agents: ${agents.join(", ")}`,
+                `Current: ${plan.skillNames.length}`
+              ]
+            }
+          ]
+        }
+      },
+      { json: options.json }
+    );
+    return 0;
   }
-  return commands;
-}
-function runOneSkillsInstall(install) {
-  return new Promise((resolve14) => {
-    const child = spawn3(install.command, install.args, {
-      stdio: ["ignore", "ignore", "pipe"],
-      env: process.env
-    });
-    let stderr = "";
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString("utf-8");
-    });
-    child.on("error", (error) => {
-      resolve14({
-        ok: false,
-        detail: `failed to start ${install.command}: ${error.message}`,
-        manualCommand: install.manualCommand
-      });
-    });
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve14({ ok: true, detail: "", manualCommand: install.manualCommand });
-        return;
-      }
-      const detail = stderr.trim();
-      resolve14({
-        ok: false,
-        detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
-        manualCommand: install.manualCommand
-      });
-    });
-  });
-}
-async function runSkillsInstall(installs) {
-  const failures = [];
-  for (const install of installs) {
-    const result = await runOneSkillsInstall(install);
-    if (result.ok) return true;
-    failures.push(result);
+  if (scope === "local" && root) {
+    const managedNames = [
+      .../* @__PURE__ */ new Set([...plan.skillNames, ...LEGACY_SKILL_NAMES_TO_REMOVE])
+    ];
+    const agentRoots = workspaceSkillRootsForAgents(plan.agents);
+    ensureProjectPrivatePathsIgnored(root, [
+      ".deepline/",
+      ...agentRoots.flatMap(
+        (agentRoot) => managedNames.map((name) => `${agentRoot}/skills/${name}/`)
+      )
+    ]);
   }
-  const details = failures.map((failure) => failure.detail).filter(Boolean).join("\n");
-  const manualCommand = failures.at(-1)?.manualCommand;
   process.stderr.write(
-    `SDK skills sync failed${details ? `:
-${details}` : ""}
-` + (manualCommand ? `Run manually: ${manualCommand}
-` : "")
+    `Replacing Deepline skills for ${agents.join(", ")} (${scope})...
+`
   );
-  return false;
-}
-function runLegacySkillsCleanup() {
-  const candidates = hasCommand("bunx") ? [
-    {
-      command: "bunx",
-      args: [
-        "--bun",
-        "skills",
-        "remove",
-        "--global",
-        "-y",
-        ...LEGACY_SKILL_NAMES_TO_REMOVE
-      ]
-    },
-    {
-      command: "npx",
-      args: [
-        "--yes",
-        "skills",
-        "remove",
-        "--global",
-        "-y",
-        ...LEGACY_SKILL_NAMES_TO_REMOVE
-      ]
+  try {
+    const execute = dependencies.runProcess ?? runProcess;
+    const removeCode = await execute(
+      plan.remove.command,
+      plan.remove.args,
+      root ?? void 0
+    );
+    if (removeCode !== 0) {
+      throw new Error("Could not remove the existing Deepline skills.");
     }
-  ] : [
-    {
-      command: "npx",
-      args: [
-        "--yes",
-        "skills",
-        "remove",
-        "--global",
-        "-y",
-        ...LEGACY_SKILL_NAMES_TO_REMOVE
-      ]
+    const installCode = await execute(
+      plan.install.command,
+      plan.install.args,
+      root ?? void 0
+    );
+    if (installCode !== 0) {
+      throw new Error("Could not install the current Deepline skills.");
     }
-  ];
-  for (const candidate of candidates) {
-    const result = spawnSync2(candidate.command, candidate.args, {
-      stdio: "ignore",
-      env: process.env,
-      shell: process.platform === "win32"
-    });
-    if (result.status === 0) return;
-  }
-}
-function writeSdkSkillsStatusLine(line) {
-  const progress = getActiveCliProgress();
-  if (progress) {
-    progress.writeLine(line);
-    return;
-  }
-  process.stderr.write(`${line}
-`);
-}
-async function syncSdkSkillsIfNeeded(baseUrl, options = {}) {
-  if (attemptedSync || shouldSkipSkillsSync()) return;
-  attemptedSync = true;
-  const usingPluginSkills = Boolean(activePluginSkillsDir());
-  if (usingPluginSkills) {
-    return;
-  }
-  const localVersion = readSdkSkillsLocalVersion(baseUrl);
-  const update = options.update === void 0 ? await fetchSkillsUpdate(baseUrl, localVersion) : options.update ? {
-    needsUpdate: options.update.needs_update,
-    remoteVersion: options.update.remote.version
-  } : null;
-  if (!update?.needsUpdate || !update.remoteVersion) {
-    return;
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "SKILLS_INSTALL_FAILED",
+        exitCode: 5,
+        scope,
+        agents,
+        message: error instanceof Error ? error.message : String(error),
+        next: `deepline skills --scope ${scope} --json`
+      },
+      { json: options.json }
+    );
+    return 5;
   }
-  const remoteSkillNames = await fetchV1SkillNames(baseUrl);
-  const skillNames = buildSdkSkillNames(
-    remoteSkillNames.length > 0 ? remoteSkillNames : DEFAULT_SDK_SKILL_NAMES
+  mkdirSync9(dirname12(plan.statePath), { recursive: true });
+  writeFileSync14(
+    plan.statePath,
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        cliVersion: SDK_VERSION,
+        scope,
+        agents,
+        skillsVersion: plan.version,
+        skillNames: plan.skillNames
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
   );
-  if (skillNames.length === 0) return;
-  const installs = resolveSkillsInstallCommands(baseUrl, skillNames);
-  if (installs.length === 0) {
-    writeUnavailableSkillsNotice(baseUrl, update.remoteVersion, skillNames);
-    return;
-  }
-  writeSdkSkillsStatusLine("Deepline skills changed; syncing agent skills...");
-  const installed = await runSkillsInstall(installs);
-  if (!installed) return;
-  runLegacySkillsCleanup();
-  writeLocalSkillsVersion(baseUrl, update.remoteVersion);
-  clearUnavailableSkillsNotice(baseUrl);
-  writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
+  printCommandEnvelope(
+    {
+      ok: true,
+      status: "complete",
+      scope,
+      agents,
+      skillsVersion: plan.version,
+      skillCount: plan.skillNames.length,
+      statePath: plan.statePath,
+      render: {
+        sections: [
+          {
+            title: "skills",
+            lines: [
+              `Scope: ${scope}`,
+              `Agents: ${agents.join(", ")}`,
+              `Installed: ${plan.skillNames.length}`
+            ]
+          }
+        ]
+      }
+    },
+    { json: options.json }
+  );
+  return 0;
+}
+function registerSkillsCommand(program) {
+  program.command("skills").description("Replace Deepline agent skills with the current release.").option("--scope <scope>", "Install scope: global or local").option("--agent <agent>", "Override the detected agent target").option("--dry-run", "Print the install plan without changing files").option("--json", "Emit one JSON result envelope").addHelpText(
+    "after",
+    `
+Notes:
+  This command removes and reinstalls only Deepline-managed skill names using
+  skills@latest. Local scope writes into the resolved persistent project.
+
+Examples:
+  deepline skills --json
+  deepline skills --scope local --json
+  deepline skills --agent codex --dry-run --json
+`
+  ).action(async (options) => {
+    process.exitCode = await runSkillsCommand(options);
+  });
 }
 
 // src/cli/commands/update.ts
@@ -29205,14 +29464,14 @@ function posixShellQuote(value) {
 function windowsCmdQuote(value) {
   return `"${value.replace(/"/g, '""')}"`;
 }
-function shellQuote6(value) {
+function shellQuote5(value) {
   if (process.platform === "win32") {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : windowsCmdQuote(value);
   }
   return posixShellQuote(value);
 }
 function buildSourceUpdateCommand(sourceRoot) {
-  const quotedRoot = shellQuote6(sourceRoot);
+  const quotedRoot = shellQuote5(sourceRoot);
   const cdCommand = process.platform === "win32" ? `cd /d ${quotedRoot}` : `cd ${quotedRoot}`;
   return `${cdCommand} && git fetch origin main --tags && git merge --ff-only origin/main`;
 }
@@ -29224,14 +29483,14 @@ function buildSidecarProjectConfigCommand(versionDir, nodeBin) {
     "fs.mkdirSync(dir,{recursive:true});",
     `fs.writeFileSync(path.join(dir,'package.json'),${JSON.stringify(NPM_SDK_SIDECAR_PACKAGE_JSON)});`
   ].join("");
-  return `${shellQuote6(nodeBin)} -e ${shellQuote6(script)} ${shellQuote6(versionDir)}`;
+  return `${shellQuote5(nodeBin)} -e ${shellQuote5(script)} ${shellQuote5(versionDir)}`;
 }
 function sidecarStateDir(input2) {
   const scope = input2.env.DEEPLINE_CONFIG_SCOPE?.trim();
   if (!scope || scope.includes("/") || scope.includes("\\")) {
     return null;
   }
-  return join14(input2.homeDir, ".local", "deepline", scope, "sdk-cli");
+  return join15(input2.homeDir, ".local", "deepline", scope, "sdk-cli");
 }
 function sidecarRegistryUrl(hostUrl) {
   let url;
@@ -29270,15 +29529,15 @@ function resolvePythonSidecarUpdatePlan(options) {
     resolve13(stateDir),
     resolve13(options.entrypoint)
   );
-  if (!relativeEntrypoint || relativeEntrypoint.startsWith("..") || isAbsolute2(relativeEntrypoint)) {
+  if (!relativeEntrypoint || relativeEntrypoint.startsWith("..") || isAbsolute3(relativeEntrypoint)) {
     return null;
   }
-  const installMethod = readOptionalText(join14(stateDir, ".install-method"));
+  const installMethod = readOptionalText(join15(stateDir, ".install-method"));
   if (installMethod !== "python-sidecar") return null;
   const scope = options.env.DEEPLINE_CONFIG_SCOPE?.trim() || "";
   const hostUrl = options.env.DEEPLINE_HOST_URL?.trim() || "";
-  const nodeBin = readOptionalText(join14(stateDir, ".node-bin")) || process.execPath;
-  const sidecarPath = readOptionalText(join14(stateDir, ".command-path")) || join14(
+  const nodeBin = readOptionalText(join15(stateDir, ".node-bin")) || process.execPath;
+  const sidecarPath = readOptionalText(join15(stateDir, ".command-path")) || join15(
     stateDir,
     "bin",
     process.platform === "win32" ? "deepline-sdk.cmd" : "deepline-sdk"
@@ -29286,8 +29545,8 @@ function resolvePythonSidecarUpdatePlan(options) {
   const packageSpec = options.packageSpec || "deepline@latest";
   const npmCommand = "npm";
   const registryUrl = sidecarRegistryUrl(hostUrl);
-  const versionDir = join14(stateDir, "versions", "<version>");
-  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote6(versionDir)} --registry ${shellQuote6(registryUrl)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote6).join(" ")} ${shellQuote6(packageSpec)}`;
+  const versionDir = join15(stateDir, "versions", "<version>");
+  const manualCommand = `${buildSidecarProjectConfigCommand(versionDir, nodeBin)} && ${npmCommand} install --prefix ${shellQuote5(versionDir)} --registry ${shellQuote5(registryUrl)} ${NPM_SDK_INSTALL_COMMON_FLAGS.map(shellQuote5).join(" ")} ${shellQuote5(packageSpec)}`;
   return {
     kind: "python-sidecar",
     stateDir,
@@ -29304,7 +29563,7 @@ function resolvePythonSidecarUpdatePlan(options) {
 function findRepoBackedSdkRoot(startPath) {
   let current = resolve13(startPath);
   while (true) {
-    if (existsSync12(join14(current, "sdk", "package.json")) && existsSync12(join14(current, "sdk", "bin", "deepline-dev.ts"))) {
+    if (existsSync12(join15(current, "sdk", "package.json")) && existsSync12(join15(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
     }
     const parent = dirname13(current);
@@ -29335,7 +29594,7 @@ function inferNpmGlobalPrefixFromEntrypoint(entrypoint) {
 }
 function resolveUpdatePlan(options = {}) {
   const env = options.env ?? process.env;
-  const homeDir2 = options.homeDir ?? homedir11();
+  const homeDir2 = options.homeDir ?? homedir12();
   const entrypoint = options.entrypoint ?? (process.argv[1] ? resolve13(process.argv[1]) : "");
   const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname13(entrypoint)) : null;
   if (sourceRoot) {
@@ -29371,17 +29630,17 @@ function resolveUpdatePlan(options = {}) {
     fallbackRegistryUrl: publicNpmFallbackRegistryUrl(
       env.DEEPLINE_HOST_URL?.trim() || autoDetectBaseUrl()
     ),
-    manualCommand: `${command} ${args.map(shellQuote6).join(" ")}`
+    manualCommand: `${command} ${args.map(shellQuote5).join(" ")}`
   };
 }
 var AUTO_UPDATE_FAILURE_FILE = ".auto-update-failure.json";
 function autoUpdateFailurePath(plan) {
   if (plan.kind === "source") return null;
   if (plan.kind === "python-sidecar") {
-    return join14(plan.stateDir, AUTO_UPDATE_FAILURE_FILE);
+    return join15(plan.stateDir, AUTO_UPDATE_FAILURE_FILE);
   }
-  return join14(
-    homedir11(),
+  return join15(
+    homedir12(),
     ".local",
     "deepline",
     "sdk-cli",
@@ -29429,7 +29688,7 @@ function clearAutoUpdateFailure(plan) {
   const path = autoUpdateFailurePath(plan);
   if (!path) return;
   try {
-    unlinkSync2(path);
+    unlinkSync(path);
   } catch {
   }
 }
@@ -29465,7 +29724,7 @@ function safeVersionSegment(value) {
   return /^[0-9A-Za-z._-]+$/.test(normalized) ? normalized : "";
 }
 function entryPathInVersionDir(versionDir) {
-  return join14(
+  return join15(
     versionDir,
     "node_modules",
     "deepline",
@@ -29475,7 +29734,7 @@ function entryPathInVersionDir(versionDir) {
   );
 }
 function installedPackageVersion(versionDir) {
-  const packageJsonPath = join14(
+  const packageJsonPath = join15(
     versionDir,
     "node_modules",
     "deepline",
@@ -29576,23 +29835,23 @@ function writeSidecarLauncher(input2) {
     input2.path,
     [
       "#!/usr/bin/env sh",
-      `export DEEPLINE_HOST_URL=${shellQuote6(input2.hostUrl)}`,
-      `export DEEPLINE_CONFIG_SCOPE=${shellQuote6(input2.scope)}`,
-      `exec ${shellQuote6(input2.nodeBin)} ${shellQuote6(input2.entryPath)} "$@"`,
+      `export DEEPLINE_HOST_URL=${shellQuote5(input2.hostUrl)}`,
+      `export DEEPLINE_CONFIG_SCOPE=${shellQuote5(input2.scope)}`,
+      `exec ${shellQuote5(input2.nodeBin)} ${shellQuote5(input2.entryPath)} "$@"`,
       ""
     ].join("\n"),
     { encoding: "utf8", mode: 493 }
   );
 }
 async function runPythonSidecarUpdatePlan(plan) {
-  const versionsDir = join14(plan.stateDir, "versions");
-  const tempDir = join14(
+  const versionsDir = join15(plan.stateDir, "versions");
+  const tempDir = join15(
     versionsDir,
     `.tmp-sdk-update-${process.pid}-${Date.now()}`
   );
   rmSync4(tempDir, { recursive: true, force: true });
   mkdirSync10(tempDir, { recursive: true });
-  writeFileSync15(join14(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
+  writeFileSync15(join15(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
   const env = {
     ...process.env,
     PATH: `${dirname13(plan.nodeBin)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
@@ -29623,7 +29882,7 @@ async function runPythonSidecarUpdatePlan(plan) {
     rmSync4(tempDir, { recursive: true, force: true });
     return 1;
   }
-  const finalDir = join14(versionsDir, installedVersion);
+  const finalDir = join15(versionsDir, installedVersion);
   const finalEntryPath = entryPathInVersionDir(finalDir);
   if (existsSync12(finalEntryPath)) {
     rmSync4(tempDir, { recursive: true, force: true });
@@ -29655,27 +29914,27 @@ async function runPythonSidecarUpdatePlan(plan) {
     entryPath: finalEntryPath
   });
   writeFileSync15(
-    join14(plan.stateDir, ".version"),
+    join15(plan.stateDir, ".version"),
     `${installedVersion}
 `,
     "utf8"
   );
   writeFileSync15(
-    join14(plan.stateDir, ".install-method"),
+    join15(plan.stateDir, ".install-method"),
     "python-sidecar\n",
     "utf8"
   );
   writeFileSync15(
-    join14(plan.stateDir, ".command-path"),
+    join15(plan.stateDir, ".command-path"),
     `${plan.sidecarPath}
 `,
     "utf8"
   );
-  writeFileSync15(join14(plan.stateDir, ".runner"), "node\n", "utf8");
-  writeFileSync15(join14(plan.stateDir, ".node-bin"), `${plan.nodeBin}
+  writeFileSync15(join15(plan.stateDir, ".runner"), "node\n", "utf8");
+  writeFileSync15(join15(plan.stateDir, ".node-bin"), `${plan.nodeBin}
 `, "utf8");
   writeFileSync15(
-    join14(plan.stateDir, ".entry-path"),
+    join15(plan.stateDir, ".entry-path"),
     `${finalEntryPath}
 `,
     "utf8"
@@ -29708,7 +29967,20 @@ async function runUpdateCommand(options, dependencies = {}) {
   const detectBaseUrl = dependencies.detectBaseUrl ?? autoDetectBaseUrl;
   const resolvePlan = dependencies.resolvePlan ?? resolveUpdatePlan;
   const runPlan = dependencies.runPlan ?? runUpdatePlan;
-  const syncSkills = dependencies.syncSkillsIfNeeded ?? syncSdkSkillsIfNeeded;
+  const syncSkills = dependencies.syncSkillsIfNeeded ?? (async () => {
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (() => true);
+    try {
+      const exitCode = await runSkillsCommand({ json: true });
+      if (exitCode !== 0) {
+        throw new Error(
+          `Deepline skills update failed with exit ${exitCode}.`
+        );
+      }
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+  });
   const stderr = dependencies.stderr ?? process.stderr;
   const plan = resolvePlan();
   const render = {
@@ -29776,210 +30048,1409 @@ Examples:
   });
 }
 
-// ../shared_libs/cli/command-compatibility.json
-var command_compatibility_default = {
-  enrich: {
-    family: "python",
-    label: "a legacy Python CLI enrichment command",
-    sdk_alternative: "Use `deepline plays ...` for durable workflows or `deepline tools execute ...` for one tool call."
-  },
-  session: {
-    family: "python",
-    label: "a legacy Python CLI session/playground command",
-    sdk_alternative: "Use `deepline sessions send ...` or `deepline sessions render ...` for transcript workflows."
-  },
-  workflows: {
-    family: "python",
-    label: "a legacy Python CLI workflow command",
-    sdk_alternative: "Use `deepline plays ...` in the SDK CLI."
-  },
-  events: {
-    family: "python",
-    label: "a legacy Python CLI event command"
-  },
-  plays: {
-    family: "sdk",
-    label: "an SDK CLI play command",
-    python_alternative: "Use `deepline workflows ...` only for legacy workflows."
-  },
-  runs: {
-    family: "sdk",
-    label: "an SDK CLI run inspection command"
-  },
-  sessions: {
-    family: "sdk",
-    label: "an SDK CLI session transcript command"
-  },
-  health: {
-    family: "sdk",
-    label: "an SDK CLI health command"
+// src/cli/commands/setup.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import {
+  existsSync as existsSync13,
+  lstatSync,
+  mkdirSync as mkdirSync11,
+  readFileSync as readFileSync14,
+  realpathSync as realpathSync4,
+  rmSync as rmSync5,
+  writeFileSync as writeFileSync16
+} from "fs";
+import { homedir as homedir13 } from "os";
+import { dirname as dirname14, join as join16, resolve as resolve14 } from "path";
+var SETUP_PHASE_NAMES = [
+  "cli",
+  "cleanup",
+  "skills",
+  "auth",
+  "verify"
+];
+function initialSetupPhases() {
+  return {
+    cli: { status: "pending" },
+    cleanup: { status: "pending" },
+    skills: { status: "pending" },
+    auth: { status: "pending" },
+    verify: { status: "pending" }
+  };
+}
+function isSetupPhaseStatus(value) {
+  return value === "pending" || value === "in_progress" || value === "complete" || value === "waiting" || value === "failed";
+}
+function parseSetupPhases(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const source = value;
+  const phases = initialSetupPhases();
+  for (const name of SETUP_PHASE_NAMES) {
+    const phase = source[name];
+    if (!phase || typeof phase !== "object" || Array.isArray(phase)) {
+      return null;
+    }
+    const record = phase;
+    if (!isSetupPhaseStatus(record.status)) return null;
+    phases[name] = {
+      status: record.status,
+      ...typeof record.outcome === "string" ? { outcome: record.outcome } : {},
+      ...typeof record.code === "string" ? { code: record.code } : {}
+    };
   }
-};
-
-// src/cli/command-compatibility.ts
-var COMMAND_COMPATIBILITY = command_compatibility_default;
-function cliFamilyLabel(family) {
-  return family === "sdk" ? "SDK CLI" : "legacy Python CLI";
+  return phases;
 }
-function commandCompatibilityHint(currentFamily, commandName, baseUrl) {
-  const compatibility = COMMAND_COMPATIBILITY[commandName];
-  if (!compatibility || compatibility.family === currentFamily) {
-    return null;
+function phasesFromLegacyStatus(status) {
+  const phases = initialSetupPhases();
+  if (status === "skills_installed" || status === "authorization_pending" || status === "complete") {
+    phases.cli = { status: "complete" };
+    phases.cleanup = { status: "complete" };
+    phases.skills = { status: "complete" };
   }
-  const expectedFamily = compatibility.family;
-  const currentLabel = cliFamilyLabel(currentFamily);
-  const expectedLabel = cliFamilyLabel(expectedFamily);
-  const lines = [
-    "",
-    "Command compatibility:",
-    `  \`deepline ${commandName}\` is ${compatibility.label}.`,
-    `  Current binary: ${currentLabel}. Required binary: ${expectedLabel}.`,
-    "  If this came from an agent skill, the installed skill likely targets the other Deepline CLI."
-  ];
-  if (currentFamily === "sdk") {
-    lines.push(
-      "",
-      "  To stay on the SDK CLI, refresh the Deepline agent skills:",
-      `    ${skillsInstallCommand(baseUrl, DEFAULT_SDK_SKILL_NAMES)}`,
-      "  To use the legacy Python CLI instead:",
-      `    ${legacyPythonInstallCommand(baseUrl)}`,
-      "  `deepline update` updates this SDK CLI, but it will not switch CLI families."
-    );
-    if (compatibility.sdk_alternative) {
-      lines.push(`  SDK alternative: ${compatibility.sdk_alternative}`);
-    }
-  } else {
-    lines.push(
-      "",
-      "  To use SDK commands, install the SDK CLI and refresh Deepline agent skills:",
-      `    ${sdkNpmGlobalInstallCommand()}`,
-      `    ${skillsInstallCommand(baseUrl, DEFAULT_SDK_SKILL_NAMES)}`,
-      "  `deepline update` updates this Python CLI and its skills, but it will not switch CLI families."
+  if (status === "authorization_pending") {
+    phases.auth = { status: "waiting", outcome: "authorization_pending" };
+  } else if (status === "complete") {
+    phases.auth = { status: "complete" };
+    phases.verify = { status: "complete" };
+  }
+  return phases;
+}
+function readSetupState(input2) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync14(
+        setupStatePath(input2.baseUrl, input2.scope, input2.root),
+        "utf8"
+      )
     );
-    if (compatibility.python_alternative) {
-      lines.push(`  Python alternative: ${compatibility.python_alternative}`);
+    if (parsed.host !== input2.baseUrl || parsed.scope !== input2.scope || parsed.root !== input2.root || typeof parsed.status !== "string") {
+      return null;
     }
+    return {
+      status: parsed.status,
+      phases: parseSetupPhases(parsed.phases) ?? phasesFromLegacyStatus(parsed.status)
+    };
+  } catch {
+    return null;
   }
-  return lines.join("\n");
 }
-function unknownCommandNameFromMessage(message) {
-  const match = message.match(/unknown command ['"]([^'"]+)['"]/i);
-  const command = match?.[1]?.trim();
-  return command ? command : null;
+function selectSetupProgress(previousState) {
+  const resumed = Boolean(previousState && previousState.status !== "complete");
+  return {
+    resumed,
+    phases: resumed ? previousState.phases : initialSetupPhases()
+  };
 }
-
-// src/cli/self-update.ts
-import { spawn as spawn5 } from "child_process";
-function envTruthy(name) {
-  const value = process.env[name]?.trim().toLowerCase();
-  return value === "1" || value === "true" || value === "yes";
+function normalizeScope2(value) {
+  if (!value || value === "global") return "global";
+  if (value === "local") return "local";
+  throw new Error("--scope must be one of: global, local");
 }
-function isCi() {
-  return envTruthy("CI") || envTruthy("GITHUB_ACTIONS");
+function resolveScopeRoot(scope) {
+  if (scope === "global") return null;
+  const target = resolveProjectPinTarget();
+  if (!target.ok) {
+    throw new Error(
+      `Cowork project folder is ambiguous. Candidate folders: ${target.candidates.join(
+        ", "
+      )}. Set CLAUDE_PROJECT_DIR or cd into the intended project folder.`
+    );
+  }
+  return target.dir;
 }
-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 authScopeForSetup(scope) {
+  return scope === "local" ? "folder" : "global";
 }
-function parseSemver(version) {
-  const trimmed = version?.trim();
-  if (!trimmed) return null;
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(
-    trimmed
-  );
-  if (!match) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] ?? ""
-  };
+function setupStatePath(baseUrl, scope, root) {
+  return scope === "local" && root ? join16(root, ".deepline", "setup", "state.json") : join16(sdkCliStateDirPath(baseUrl), "setup.json");
 }
-function compareSemver(left, right) {
-  const a = parseSemver(left);
-  const b = parseSemver(right);
-  if (!a || !b) {
-    return left.localeCompare(right);
+async function captureStdout2(run) {
+  let stdout = "";
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk) => {
+    stdout += typeof chunk === "string" ? chunk : String(chunk);
+    return true;
+  });
+  try {
+    return { exitCode: await run(), stdout, error: null };
+  } catch (error) {
+    return { exitCode: 4, stdout, error };
+  } finally {
+    process.stdout.write = originalWrite;
   }
-  for (const key of ["major", "minor", "patch"]) {
-    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
+}
+function parseCapturedJson(stdout) {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    return null;
   }
-  if (a.prerelease === b.prerelease) return 0;
-  if (!a.prerelease) return 1;
-  if (!b.prerelease) return -1;
-  return a.prerelease.localeCompare(b.prerelease);
 }
-function isDowngradeAutoUpdateResponse(response) {
-  const target = response?.latest?.trim();
-  const current = response?.current?.trim() || SDK_VERSION;
-  if (!target) return false;
-  return compareSemver(target, current) < 0;
+function asRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function relaunchCurrentCommand(plan) {
-  return new Promise((resolve14) => {
-    const command = plan.kind === "python-sidecar" ? plan.sidecarPath : process.execPath;
-    const args = plan.kind === "python-sidecar" ? process.argv.slice(2) : process.argv.slice(1);
-    const child = spawn5(command, args, {
-      stdio: "inherit",
-      shell: process.platform === "win32",
-      env: {
-        ...process.env,
-        DEEPLINE_NO_AUTO_UPDATE: "1"
-      }
-    });
-    child.on("error", (error) => {
-      process.stderr.write(
-        `Deepline SDK/CLI updated, but relaunch failed: ${error.message}
-`
-      );
-      resolve14(1);
-    });
-    child.on("close", (code) => resolve14(code ?? 1));
-  });
+function printCapturedAuthorizationUrl(stdout) {
+  const urls = stdout.match(/https:\/\/[^\s]+/g) ?? [];
+  for (const url of new Set(
+    urls.map((value) => value.replace(/[).,]+$/, ""))
+  )) {
+    process.stderr.write(`Authorize Deepline: ${url}
+`);
+  }
 }
-async function maybeAutoUpdateAndRelaunch(response) {
-  const autoUpdate = response?.auto_update;
-  if (!response || !autoUpdate?.should_auto_update || shouldSkipSelfUpdate()) {
-    return false;
+function safeRead(path) {
+  try {
+    return readFileSync14(path, "utf8");
+  } catch {
+    return "";
   }
-  if (isDowngradeAutoUpdateResponse(response)) {
-    const target = response.latest;
-    const current = response.current?.trim() || SDK_VERSION;
-    process.stderr.write(
-      `Deepline SDK/CLI auto-update refused: server advertised older ${target} than current ${current}. Continuing without mutating the CLI.
-`
-    );
+}
+function isNpmManagedDeeplinePath(path) {
+  try {
+    return realpathSync4(path).includes(`${join16("node_modules", "deepline")}`);
+  } catch {
     return false;
   }
-  const packageSpec = response.latest ? `deepline@${response.latest}` : void 0;
-  const plan = resolveUpdatePlan({ packageSpec });
-  if (plan.kind === "source") {
-    return false;
+}
+function removeKnownLegacyPaths(baseUrl) {
+  const home = homedir13();
+  const hostDir = join16(home, ".local", "deepline", baseUrlSlug(baseUrl));
+  const installerCommandPath = safeRead(
+    join16(hostDir, "sdk", ".command-path")
+  ).trim();
+  const candidates = [
+    join16(home, ".local", "bin", "deepline-real"),
+    join16(hostDir, "bin", "deepline"),
+    join16(hostDir, "bin", "deepline-real"),
+    join16(hostDir, "cli", ".install-method"),
+    join16(hostDir, "cli", ".version"),
+    join16(hostDir, "sdk", ".install-method"),
+    join16(hostDir, "sdk", ".command-path"),
+    ...installerCommandPath ? [
+      installerCommandPath,
+      join16(dirname14(installerCommandPath), "deepline-sdk")
+    ] : []
+  ];
+  const removed = [];
+  for (const path of candidates) {
+    if (!existsSync13(path)) continue;
+    if (path === installerCommandPath && isNpmManagedDeeplinePath(path)) {
+      continue;
+    }
+    rmSync5(path, { force: true });
+    removed.push(path);
   }
-  const label = autoUpdate.reason === "rollback_forced" ? "has a server rollback pending and needs the latest rollback-aware CLI" : autoUpdate.reason === "deprecated" ? "is deprecated and will update automatically" : autoUpdate.required ? "requires an update" : "is more than the supported auto-update lag behind";
-  process.stderr.write(
-    `Deepline SDK/CLI ${label}; running ${plan.manualCommand}
-`
+  return removed;
+}
+function resolvePathCommands(command) {
+  const lookup = spawnSync2(
+    process.platform === "win32" ? "where" : "which",
+    process.platform === "win32" ? [command] : ["-a", command],
+    { encoding: "utf8", shell: process.platform === "win32" }
   );
-  const updateResult = await runAutomaticUpdatePlan(plan);
-  if (updateResult.status === "skipped_previous_failure") {
-    return false;
+  return [
+    ...new Set(
+      String(lookup.stdout ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((path) => resolve14(path))
+    )
+  ];
+}
+function resolvePathCommand(command) {
+  return resolvePathCommands(command)[0] ?? null;
+}
+function resolvePersistentGlobalCommand() {
+  const prefix = spawnSync2("npm", ["prefix", "-g"], { encoding: "utf8" });
+  if (prefix.status !== 0) return null;
+  const root = String(prefix.stdout ?? "").trim();
+  if (!root) return null;
+  const candidates = process.platform === "win32" ? [join16(root, "deepline.cmd"), join16(root, "deepline")] : [join16(root, "bin", "deepline")];
+  return candidates.find((candidate) => existsSync13(candidate)) ?? null;
+}
+function inspectGlobalCliAvailability(input2) {
+  const persistentPath = input2 && "persistentGlobalCli" in input2 ? input2.persistentGlobalCli ?? null : resolvePersistentGlobalCommand();
+  const pathClis = input2?.pathClis ?? resolvePathCommands("deepline");
+  const path = persistentPath ? pathClis.find(
+    (candidate) => pathsResolveToSameFile(candidate, persistentPath)
+  ) ?? null : null;
+  return { ok: Boolean(path), persistentPath, path };
+}
+function pathsResolveToSameFile(left, right) {
+  try {
+    return realpathSync4(left) === realpathSync4(right);
+  } catch {
+    return resolve14(left) === resolve14(right);
   }
-  if (updateResult.exitCode !== 0) {
-    if (autoUpdate.required) {
-      throw new Error(
-        `Automatic Deepline SDK/CLI update failed with exit code ${updateResult.exitCode}. ${response.message}`
-      );
+}
+function isKnownDeeplineCommand(path) {
+  const entrypoint = process.argv[1] ? resolve14(process.argv[1]) : "";
+  let resolvedPath = path;
+  try {
+    resolvedPath = realpathSync4(path);
+  } catch {
+  }
+  if (entrypoint && resolvedPath === entrypoint) return true;
+  if (resolvedPath.includes(`${join16("node_modules", "deepline")}`)) return true;
+  const content = safeRead(path);
+  return content.includes("node_modules/deepline") || content.includes("node_modules\\deepline") || content.includes("DEEPLINE_CONFIG_SCOPE") || content.includes("deepline-real");
+}
+function inspectPathConflict() {
+  const commandPath = resolvePathCommand("deepline");
+  if (!commandPath || isKnownDeeplineCommand(commandPath)) return null;
+  try {
+    if (lstatSync(commandPath).isSymbolicLink()) {
+      const target = realpathSync4(commandPath);
+      if (target.includes(`${join16("node_modules", "deepline")}`)) return null;
     }
-    process.stderr.write(
-      `Deepline SDK/CLI auto-update failed with exit code ${updateResult.exitCode}; continuing with ${response.current ?? "current version"}.
-`
-    );
-    return false;
+  } catch {
   }
-  process.stderr.write("Deepline SDK/CLI updated; rerunning command.\n");
-  const exitCode = await relaunchCurrentCommand(plan);
-  process.exit(exitCode);
-  return true;
+  return commandPath;
+}
+function writeSetupState(input2) {
+  const path = setupStatePath(input2.baseUrl, input2.scope, input2.root);
+  mkdirSync11(dirname14(path), { recursive: true });
+  writeFileSync16(
+    path,
+    `${JSON.stringify(
+      {
+        schemaVersion: 2,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        cliVersion: SDK_VERSION,
+        host: input2.baseUrl,
+        scope: input2.scope,
+        root: input2.root,
+        status: input2.status,
+        phases: input2.phases
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+  return path;
+}
+function persistSetupProgress(input2) {
+  return writeSetupState({
+    ...input2,
+    status: input2.status ?? "in_progress"
+  });
+}
+function completeSetupPhase(phases, phase, outcome) {
+  phases[phase] = {
+    status: "complete",
+    ...outcome ? { outcome } : {}
+  };
+}
+function beginSetupPhase(phases, phase) {
+  phases[phase] = { status: "in_progress" };
+}
+function failSetupPhase(phases, phase, code) {
+  phases[phase] = { status: "failed", code };
+}
+function rollbackCommand(scope, root) {
+  const prefix = scope === "local" && root ? ` --prefix ${JSON.stringify(join16(root, ".deepline", "runtime"))}` : "";
+  return `npm install -g${prefix} --no-audit --no-fund --include=optional --allow-scripts=esbuild deepline@${SDK_VERSION}`;
+}
+function setupQuickstartCommand(baseUrl) {
+  return baseUrl === "https://code.deepline.com" ? "deepline quickstart" : `DEEPLINE_HOST_URL=${JSON.stringify(baseUrl)} deepline quickstart`;
+}
+function setupResumeCommand(baseUrl, scope) {
+  const hostPrefix = baseUrl === "https://code.deepline.com" ? "" : `DEEPLINE_HOST_URL=${JSON.stringify(baseUrl)} `;
+  return `${hostPrefix}deepline setup --scope ${scope} --json`;
+}
+function setupRetry(input2) {
+  return {
+    phase: input2.phase,
+    command: setupResumeCommand(input2.baseUrl, input2.scope),
+    automatic: true
+  };
+}
+function reportSetupPhaseFailure(input2) {
+  failSetupPhase(input2.phases, input2.phase, input2.code);
+  const statePath = persistSetupProgress({
+    baseUrl: input2.baseUrl,
+    scope: input2.scope,
+    root: input2.root,
+    phases: input2.phases,
+    status: "failed"
+  });
+  const retry = setupRetry(input2);
+  printCommandEnvelope(
+    {
+      ok: false,
+      status: "failed",
+      code: input2.code,
+      exitCode: input2.exitCode,
+      scope: input2.scope,
+      message: input2.message,
+      phases: input2.phases,
+      failedPhase: input2.phase,
+      retry,
+      statePath,
+      next: retry.command,
+      ...input2.extra ?? {}
+    },
+    { json: input2.json }
+  );
+  return input2.exitCode;
+}
+async function readAuthStatus(authScope) {
+  try {
+    const captured = await captureStdout2(
+      () => handleStatus([
+        "--json",
+        ...authScope ? ["--auth-scope", authScope] : []
+      ])
+    );
+    return {
+      exitCode: captured.exitCode,
+      payload: parseCapturedJson(captured.stdout),
+      error: captured.error
+    };
+  } catch (error) {
+    return { exitCode: 4, payload: null, error };
+  }
+}
+function reportSetupAuthStatusFailure(input2) {
+  if (!input2.auth.error) return null;
+  return reportSetupPhaseFailure({
+    baseUrl: input2.baseUrl,
+    scope: input2.scope,
+    root: input2.root,
+    phases: input2.phases,
+    phase: "auth",
+    code: "AUTH_STATUS_FAILED",
+    exitCode: 4,
+    message: "Deepline could not verify authorization with the configured host.",
+    json: input2.json,
+    extra: { authScope: input2.authScope }
+  });
+}
+function buildDoctorAssessment(input2) {
+  const skillsStatePath = skillsStatePathForScope(
+    input2.baseUrl,
+    input2.scope,
+    input2.root
+  );
+  const skillsState = parseCapturedJson(safeRead(skillsStatePath));
+  const apiKey = input2.scope === "local" ? resolveProjectApiKeyForBaseUrl(input2.baseUrl) : resolveGlobalApiKeyForBaseUrl(input2.baseUrl);
+  const projectAuth = input2.scope === "local" && apiKey ? getResolvedProjectAuthSource(input2.baseUrl, apiKey) : null;
+  const connected = input2.authStatus.payload?.connected === true;
+  const authScopeOk = input2.scope === "local" ? Boolean(projectAuth) : Boolean(apiKey && !projectAuth);
+  const skillsOk = skillsState?.scope === input2.scope && typeof skillsState.skillsVersion === "string" && Array.isArray(skillsState.agents) && skillsState.agents.length > 0;
+  const runningCliPath = process.argv[1] ? resolve14(process.argv[1]) : null;
+  const globalCli = input2.scope === "global" ? inspectGlobalCliAvailability() : null;
+  const pathGlobalCli = globalCli?.path ?? null;
+  const cliPath = input2.scope === "global" ? pathGlobalCli : runningCliPath;
+  const cliScopeOk = input2.scope === "global" ? Boolean(pathGlobalCli) : Boolean(
+    input2.root && runningCliPath?.includes(join16(input2.root, ".deepline", "runtime"))
+  );
+  const checks = {
+    cli: {
+      ok: Boolean(cliPath) && cliScopeOk,
+      version: SDK_VERSION,
+      path: cliPath,
+      scope: input2.scope
+    },
+    skills: {
+      ok: skillsOk,
+      statePath: skillsStatePath,
+      version: skillsState?.skillsVersion ?? null,
+      agents: skillsState?.agents ?? []
+    },
+    auth: {
+      ok: connected && authScopeOk,
+      scope: projectAuth ? "local" : apiKey ? "global" : null,
+      status: input2.authStatus.payload?.status ?? "not_connected"
+    },
+    api: {
+      ok: connected && input2.authStatus.exitCode === 0,
+      host: input2.baseUrl,
+      workspace: input2.authStatus.payload?.workspace ?? null,
+      providerSpend: false
+    }
+  };
+  return {
+    ok: Object.values(checks).every((check) => check.ok),
+    checks
+  };
+}
+async function runDoctorCommand(options) {
+  let scope;
+  let root;
+  try {
+    scope = normalizeScope2(options.scope);
+    root = resolveScopeRoot(scope);
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "INVALID_SETUP_SCOPE",
+        exitCode: 2,
+        message: error instanceof Error ? error.message : String(error)
+      },
+      { json: options.json }
+    );
+    return 2;
+  }
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  const authScope = authScopeForSetup(scope);
+  const authStatus = await readAuthStatus(authScope);
+  const { ok, checks } = buildDoctorAssessment({
+    baseUrl,
+    scope,
+    root,
+    authStatus
+  });
+  const quickstart = setupQuickstartCommand(baseUrl);
+  printCommandEnvelope(
+    {
+      ok,
+      status: ok ? "complete" : "failed",
+      code: ok ? "DOCTOR_OK" : "DOCTOR_FAILED",
+      exitCode: ok ? 0 : 7,
+      checks,
+      next: ok ? quickstart : "Review failed checks, then rerun: deepline doctor --json",
+      render: {
+        sections: [
+          {
+            title: "doctor",
+            lines: Object.entries(checks).map(
+              ([name, check]) => `${check.ok ? "pass" : "fail"} ${name}`
+            )
+          }
+        ]
+      }
+    },
+    { json: options.json }
+  );
+  return ok ? 0 : 7;
+}
+function pendingResult(input2) {
+  input2.phases.auth = {
+    status: "waiting",
+    outcome: "authorization_pending"
+  };
+  const statePath = writeSetupState({
+    baseUrl: input2.baseUrl,
+    scope: input2.scope,
+    root: input2.root,
+    status: "authorization_pending",
+    phases: input2.phases
+  });
+  if (input2.authorizationUrl) {
+    process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
+`);
+  }
+  printCommandEnvelope(
+    {
+      ok: true,
+      status: "authorization_pending",
+      complete: false,
+      scope: input2.scope,
+      authorizationUrl: input2.authorizationUrl || null,
+      statePath,
+      phases: input2.phases,
+      currentPhase: "auth",
+      resumed: input2.resumed,
+      retry: setupRetry({
+        baseUrl: input2.baseUrl,
+        scope: input2.scope,
+        phase: "auth"
+      }),
+      next: `Approve the link, then run: ${setupResumeCommand(input2.baseUrl, input2.scope)}`,
+      render: {
+        sections: [
+          {
+            title: "setup",
+            lines: [
+              "Authorization is waiting for browser approval.",
+              ...input2.authorizationUrl ? [input2.authorizationUrl] : []
+            ]
+          }
+        ]
+      }
+    },
+    { json: input2.json }
+  );
+  return 0;
+}
+async function runSetupCommand(options) {
+  let scope;
+  let root;
+  try {
+    scope = normalizeScope2(options.scope);
+    root = resolveScopeRoot(scope);
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "INVALID_SETUP_SCOPE",
+        exitCode: 2,
+        message: error instanceof Error ? error.message : String(error),
+        phases: {
+          ...initialSetupPhases(),
+          cli: { status: "failed", code: "INVALID_SETUP_SCOPE" }
+        },
+        failedPhase: "cli"
+      },
+      { json: options.json }
+    );
+    return 2;
+  }
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  const previousState = readSetupState({ baseUrl, scope, root });
+  const { resumed, phases } = selectSetupProgress(previousState);
+  if (phases.cli.status !== "complete") {
+    beginSetupPhase(phases, "cli");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    if (scope === "global") {
+      const globalCli = inspectGlobalCliAvailability();
+      if (!globalCli.ok) {
+        const installedButUnreachable = Boolean(globalCli.persistentPath);
+        const code = installedButUnreachable ? "GLOBAL_CLI_NOT_ON_PATH" : "GLOBAL_CLI_NOT_INSTALLED";
+        return reportSetupPhaseFailure({
+          baseUrl,
+          scope,
+          root,
+          phases,
+          phase: "cli",
+          code,
+          exitCode: 7,
+          message: installedButUnreachable ? `The global Deepline executable is not reachable on PATH: ${globalCli.persistentPath}` : "No persistent global Deepline executable was found.",
+          json: options.json,
+          extra: {
+            persistentPath: globalCli.persistentPath,
+            fallback: "https://code.deepline.com/INSTALL.md"
+          }
+        });
+      }
+    }
+    const conflict = inspectPathConflict();
+    if (conflict) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "cli",
+        code: "PATH_CONFLICT",
+        exitCode: 7,
+        message: `An unknown executable named deepline is first on PATH: ${conflict}`,
+        json: options.json,
+        extra: { path: conflict }
+      });
+    }
+    completeSetupPhase(phases, "cli", "available");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+  }
+  if (phases.cleanup.status !== "complete") {
+    beginSetupPhase(phases, "cleanup");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    try {
+      const removedLegacyPaths = removeKnownLegacyPaths(baseUrl);
+      if (removedLegacyPaths.length > 0) {
+        process.stderr.write(
+          `Removed ${removedLegacyPaths.length} known legacy Deepline path(s).
+`
+        );
+      }
+      completeSetupPhase(
+        phases,
+        "cleanup",
+        removedLegacyPaths.length > 0 ? "removed_legacy_paths" : "clean"
+      );
+      persistSetupProgress({ baseUrl, scope, root, phases });
+    } catch (error) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "cleanup",
+        code: "LEGACY_CLEANUP_FAILED",
+        exitCode: 5,
+        message: error instanceof Error ? error.message : String(error),
+        json: options.json
+      });
+    }
+  }
+  let skillsPayload = null;
+  if (phases.skills.status !== "complete") {
+    beginSetupPhase(phases, "skills");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    process.stderr.write(`Installing Deepline skills (${scope})...
+`);
+    const skills = await captureStdout2(
+      () => runSkillsCommand({ scope, json: true })
+    );
+    skillsPayload = parseCapturedJson(skills.stdout);
+    if (skills.exitCode !== 0) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "skills",
+        code: "SKILLS_INSTALL_FAILED",
+        exitCode: skills.exitCode,
+        message: typeof skillsPayload?.message === "string" ? skillsPayload.message : "Deepline skills could not be installed.",
+        json: options.json,
+        extra: { detail: skillsPayload }
+      });
+    }
+    completeSetupPhase(
+      phases,
+      "skills",
+      skillsPayload?.status === "current" ? "current" : "installed"
+    );
+    writeSetupState({
+      baseUrl,
+      scope,
+      root,
+      status: "skills_installed",
+      phases
+    });
+  } else {
+    skillsPayload = parseCapturedJson(
+      safeRead(skillsStatePathForScope(baseUrl, scope, root))
+    );
+  }
+  const authScope = authScopeForSetup(scope);
+  beginSetupPhase(phases, "auth");
+  persistSetupProgress({ baseUrl, scope, root, phases });
+  let auth = await readAuthStatus(authScope);
+  const initialAuthFailure = reportSetupAuthStatusFailure({
+    auth,
+    baseUrl,
+    authScope,
+    scope,
+    root,
+    phases,
+    json: options.json
+  });
+  if (initialAuthFailure !== null) return initialAuthFailure;
+  if (auth.payload?.connected !== true) {
+    const pending = readPendingAuthClaim(baseUrl, authScope);
+    if (pending) {
+      process.stderr.write("Checking pending Deepline authorization...\n");
+      const waited = await captureStdout2(
+        () => handleWait(["--timeout", "1", "--auth-scope", authScope])
+      );
+      printCapturedAuthorizationUrl(waited.stdout);
+      auth = await readAuthStatus(authScope);
+      const resumedAuthFailure = reportSetupAuthStatusFailure({
+        auth,
+        baseUrl,
+        authScope,
+        scope,
+        root,
+        phases,
+        json: options.json
+      });
+      if (resumedAuthFailure !== null) return resumedAuthFailure;
+      if (auth.payload?.connected !== true) {
+        const stillPending = readPendingAuthClaim(baseUrl, authScope);
+        if (stillPending) {
+          return pendingResult({
+            baseUrl,
+            scope,
+            root,
+            phases,
+            authorizationUrl: stillPending.claimUrl,
+            resumed,
+            json: options.json
+          });
+        }
+      }
+    }
+  }
+  if (auth.payload?.connected !== true) {
+    process.stderr.write("Starting Deepline browser authorization...\n");
+    const agentRuntime = detectAgentRuntime();
+    const agentLed = agentRuntime !== "unknown";
+    const waitMode = options.json || agentLed || !process.stdin.isTTY ? "no" : "auto";
+    const registered = await captureStdout2(
+      () => handleRegister(["--wait", waitMode, "--auth-scope", authScope])
+    );
+    printCapturedAuthorizationUrl(registered.stdout);
+    if (registered.exitCode !== 0) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "auth",
+        code: "AUTH_REGISTER_FAILED",
+        exitCode: registered.exitCode,
+        message: "Deepline browser authorization could not be started.",
+        json: options.json,
+        extra: {
+          detail: parseCapturedJson(registered.stdout),
+          authScope
+        }
+      });
+    }
+    auth = await readAuthStatus(authScope);
+    const registeredAuthFailure = reportSetupAuthStatusFailure({
+      auth,
+      baseUrl,
+      authScope,
+      scope,
+      root,
+      phases,
+      json: options.json
+    });
+    if (registeredAuthFailure !== null) return registeredAuthFailure;
+    if (auth.payload?.connected !== true) {
+      const pending = readPendingAuthClaim(baseUrl, authScope);
+      return pendingResult({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        authorizationUrl: pending?.claimUrl ?? "",
+        resumed,
+        json: options.json
+      });
+    }
+  }
+  completeSetupPhase(phases, "auth", "connected");
+  beginSetupPhase(phases, "verify");
+  persistSetupProgress({ baseUrl, scope, root, phases });
+  const assessment = buildDoctorAssessment({
+    baseUrl,
+    scope,
+    root,
+    authStatus: auth
+  });
+  const quickstart = setupQuickstartCommand(baseUrl);
+  const doctorPayload = {
+    ok: assessment.ok,
+    status: assessment.ok ? "complete" : "failed",
+    code: assessment.ok ? "DOCTOR_OK" : "DOCTOR_FAILED",
+    exitCode: assessment.ok ? 0 : 7,
+    checks: assessment.checks,
+    next: assessment.ok ? quickstart : `deepline doctor --scope ${scope} --json`
+  };
+  if (!assessment.ok) {
+    return reportSetupPhaseFailure({
+      baseUrl,
+      scope,
+      root,
+      phases,
+      phase: "verify",
+      code: "DOCTOR_FAILED",
+      exitCode: 7,
+      message: "Deepline setup verification found one or more failed checks.",
+      json: options.json,
+      extra: {
+        doctor: doctorPayload,
+        diagnostic: {
+          command: `deepline doctor --scope ${scope} --json`
+        }
+      }
+    });
+  }
+  completeSetupPhase(phases, "verify", "verified");
+  const statePath = writeSetupState({
+    baseUrl,
+    scope,
+    root,
+    status: "complete",
+    phases
+  });
+  const doctorChecks = asRecord2(doctorPayload?.checks);
+  const apiCheck = asRecord2(doctorChecks?.api);
+  printCommandEnvelope(
+    {
+      ok: true,
+      status: "complete",
+      complete: true,
+      scope,
+      cliVersion: SDK_VERSION,
+      agents: skillsPayload?.agents ?? [],
+      workspace: apiCheck?.workspace ?? null,
+      rollbackCommand: rollbackCommand(scope, root),
+      statePath,
+      doctor: doctorPayload,
+      phases,
+      currentPhase: null,
+      failedPhase: null,
+      resumed,
+      next: quickstart,
+      render: {
+        sections: [
+          {
+            title: "setup",
+            lines: [
+              "Deepline is installed and connected.",
+              `Next: ${quickstart}`
+            ]
+          }
+        ]
+      }
+    },
+    { json: options.json }
+  );
+  return 0;
+}
+function registerSetupCommands(program) {
+  program.command("setup").description("Install skills, authenticate, and verify Deepline.").option("--scope <scope>", "Setup scope: global or local", "global").option("--json", "Emit one final JSON result envelope").addHelpText(
+    "after",
+    `
+Notes:
+  Setup is idempotent. Bare setup resumes the first incomplete or failed phase.
+  It installs skills before auth and does not run quickstart.
+  JSON output includes phase status and an exact retry command.
+
+Examples:
+  deepline setup --json
+  deepline setup --scope local --json
+`
+  ).action(async (options) => {
+    process.exitCode = await runSetupCommand(options);
+  });
+  program.command("doctor").description("Verify CLI, skills, auth, workspace, and API connectivity.").option(
+    "--scope <scope>",
+    "Expected setup scope: global or local",
+    "global"
+  ).option("--json", "Emit one JSON result envelope").addHelpText(
+    "after",
+    `
+Notes:
+  Doctor is read-only and makes no paid provider calls. It reports repairs but
+  does not apply them automatically.
+
+Examples:
+  deepline doctor --json
+  deepline doctor --scope local --json
+`
+  ).action(async (options) => {
+    process.exitCode = await runDoctorCommand(options);
+  });
+}
+
+// ../shared_libs/cli/command-compatibility.json
+var command_compatibility_default = {
+  enrich: {
+    family: "python",
+    label: "a legacy Python CLI enrichment command",
+    sdk_alternative: "Use `deepline plays ...` for durable workflows or `deepline tools execute ...` for one tool call."
+  },
+  session: {
+    family: "python",
+    label: "a legacy Python CLI session/playground command",
+    sdk_alternative: "Use `deepline sessions send ...` or `deepline sessions render ...` for transcript workflows."
+  },
+  workflows: {
+    family: "python",
+    label: "a legacy Python CLI workflow command",
+    sdk_alternative: "Use `deepline plays ...` in the SDK CLI."
+  },
+  events: {
+    family: "python",
+    label: "a legacy Python CLI event command"
+  },
+  plays: {
+    family: "sdk",
+    label: "an SDK CLI play command",
+    python_alternative: "Use `deepline workflows ...` only for legacy workflows."
+  },
+  runs: {
+    family: "sdk",
+    label: "an SDK CLI run inspection command"
+  },
+  sessions: {
+    family: "sdk",
+    label: "an SDK CLI session transcript command"
+  },
+  health: {
+    family: "sdk",
+    label: "an SDK CLI health command"
+  }
+};
+
+// src/cli/command-compatibility.ts
+var COMMAND_COMPATIBILITY = command_compatibility_default;
+function cliFamilyLabel(family) {
+  return family === "sdk" ? "SDK CLI" : "legacy Python CLI";
+}
+function commandCompatibilityHint(currentFamily, commandName, baseUrl) {
+  const compatibility = COMMAND_COMPATIBILITY[commandName];
+  if (!compatibility || compatibility.family === currentFamily) {
+    return null;
+  }
+  const expectedFamily = compatibility.family;
+  const currentLabel = cliFamilyLabel(currentFamily);
+  const expectedLabel = cliFamilyLabel(expectedFamily);
+  const lines = [
+    "",
+    "Command compatibility:",
+    `  \`deepline ${commandName}\` is ${compatibility.label}.`,
+    `  Current binary: ${currentLabel}. Required binary: ${expectedLabel}.`,
+    "  If this came from an agent skill, the installed skill likely targets the other Deepline CLI."
+  ];
+  if (currentFamily === "sdk") {
+    lines.push(
+      "",
+      "  To stay on the SDK CLI, refresh the Deepline agent skills:",
+      `    ${skillsInstallCommand(baseUrl, DEFAULT_SDK_SKILL_NAMES)}`,
+      "  To use the legacy Python CLI instead:",
+      `    ${legacyPythonInstallCommand(baseUrl)}`,
+      "  `deepline update` updates this SDK CLI, but it will not switch CLI families."
+    );
+    if (compatibility.sdk_alternative) {
+      lines.push(`  SDK alternative: ${compatibility.sdk_alternative}`);
+    }
+  } else {
+    lines.push(
+      "",
+      "  To use SDK commands, install the SDK CLI and refresh Deepline agent skills:",
+      `    ${sdkNpmGlobalInstallCommand()}`,
+      `    ${skillsInstallCommand(baseUrl, DEFAULT_SDK_SKILL_NAMES)}`,
+      "  `deepline update` updates this Python CLI and its skills, but it will not switch CLI families."
+    );
+    if (compatibility.python_alternative) {
+      lines.push(`  Python alternative: ${compatibility.python_alternative}`);
+    }
+  }
+  return lines.join("\n");
+}
+function unknownCommandNameFromMessage(message) {
+  const match = message.match(/unknown command ['"]([^'"]+)['"]/i);
+  const command = match?.[1]?.trim();
+  return command ? command : null;
+}
+
+// src/cli/self-update.ts
+import { spawn as spawn5 } 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 parseSemver(version) {
+  const trimmed = version?.trim();
+  if (!trimmed) return null;
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(
+    trimmed
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? ""
+  };
+}
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) {
+    return left.localeCompare(right);
+  }
+  for (const key of ["major", "minor", "patch"]) {
+    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  return a.prerelease.localeCompare(b.prerelease);
+}
+function isDowngradeAutoUpdateResponse(response) {
+  const target = response?.latest?.trim();
+  const current = response?.current?.trim() || SDK_VERSION;
+  if (!target) return false;
+  return compareSemver(target, current) < 0;
+}
+function relaunchCurrentCommand(plan) {
+  return new Promise((resolve15) => {
+    const command = plan.kind === "python-sidecar" ? plan.sidecarPath : process.execPath;
+    const args = plan.kind === "python-sidecar" ? process.argv.slice(2) : process.argv.slice(1);
+    const child = spawn5(command, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: {
+        ...process.env,
+        DEEPLINE_NO_AUTO_UPDATE: "1"
+      }
+    });
+    child.on("error", (error) => {
+      process.stderr.write(
+        `Deepline SDK/CLI updated, but relaunch failed: ${error.message}
+`
+      );
+      resolve15(1);
+    });
+    child.on("close", (code) => resolve15(code ?? 1));
+  });
+}
+async function maybeAutoUpdateAndRelaunch(response) {
+  const autoUpdate = response?.auto_update;
+  if (!response || !autoUpdate?.should_auto_update || shouldSkipSelfUpdate()) {
+    return false;
+  }
+  if (isDowngradeAutoUpdateResponse(response)) {
+    const target = response.latest;
+    const current = response.current?.trim() || SDK_VERSION;
+    process.stderr.write(
+      `Deepline SDK/CLI auto-update refused: server advertised older ${target} than current ${current}. Continuing without mutating the CLI.
+`
+    );
+    return false;
+  }
+  const packageSpec = response.latest ? `deepline@${response.latest}` : void 0;
+  const plan = resolveUpdatePlan({ packageSpec });
+  if (plan.kind === "source") {
+    return false;
+  }
+  const label = autoUpdate.reason === "rollback_forced" ? "has a server rollback pending and needs the latest rollback-aware CLI" : autoUpdate.reason === "deprecated" ? "is deprecated and will update automatically" : 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 updateResult = await runAutomaticUpdatePlan(plan);
+  if (updateResult.status === "skipped_previous_failure") {
+    return false;
+  }
+  if (updateResult.exitCode !== 0) {
+    if (autoUpdate.required) {
+      throw new Error(
+        `Automatic Deepline SDK/CLI update failed with exit code ${updateResult.exitCode}. ${response.message}`
+      );
+    }
+    process.stderr.write(
+      `Deepline SDK/CLI auto-update failed with exit code ${updateResult.exitCode}; continuing with ${response.current ?? "current version"}.
+`
+    );
+    return false;
+  }
+  process.stderr.write("Deepline SDK/CLI updated; rerunning command.\n");
+  const exitCode = await relaunchCurrentCommand(plan);
+  process.exit(exitCode);
+  return true;
+}
+
+// src/cli/skills-sync.ts
+import { spawn as spawn6, spawnSync as spawnSync3 } from "child_process";
+import {
+  existsSync as existsSync14,
+  mkdirSync as mkdirSync12,
+  readFileSync as readFileSync15,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync17
+} from "fs";
+import { dirname as dirname15, join as join17 } from "path";
+var CHECK_TIMEOUT_MS2 = 3e3;
+var attemptedSync = false;
+function shouldSkipSkillsSync() {
+  if (detectAgentRuntime() === "claude_cowork") {
+    return true;
+  }
+  const value = process.env.DEEPLINE_SKIP_SKILLS_SYNC?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function activePluginSkillsDir() {
+  const pluginMode = process.env.DEEPLINE_PLUGIN_MODE?.trim().toLowerCase();
+  if (pluginMode !== "true" && pluginMode !== "1" && pluginMode !== "yes" && pluginMode !== "on") {
+    return "";
+  }
+  const dir = process.env.DEEPLINE_PLUGIN_SKILLS_DIR?.trim() ?? "";
+  return dir && existsSync14(dir) ? dir : "";
+}
+function readPluginSkillsVersion() {
+  const dir = activePluginSkillsDir();
+  if (!dir) return "";
+  try {
+    return readFileSync15(join17(dir, ".version"), "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function sdkSkillsVersionPath(baseUrl) {
+  return join17(sdkCliStateDirPath(baseUrl), "skills-version");
+}
+function legacySdkSkillsVersionPath(baseUrl) {
+  return join17(dirname15(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
+}
+function unavailableSkillsNoticePath(baseUrl) {
+  return join17(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+}
+function readSdkSkillsLocalVersion(baseUrl) {
+  const pluginVersion = readPluginSkillsVersion();
+  if (pluginVersion) return pluginVersion;
+  const path = existsSync14(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
+  if (!existsSync14(path)) return "";
+  try {
+    return readFileSync15(path, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function writeLocalSkillsVersion(baseUrl, version) {
+  const path = sdkSkillsVersionPath(baseUrl);
+  mkdirSync12(dirname15(path), { recursive: true });
+  writeFileSync17(path, `${version}
+`, "utf-8");
+}
+function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
+  const path = unavailableSkillsNoticePath(baseUrl);
+  try {
+    if (existsSync14(path) && readFileSync15(path, "utf-8").trim() === remoteVersion) {
+      return;
+    }
+    mkdirSync12(dirname15(path), { recursive: true });
+    writeFileSync17(path, `${remoteVersion}
+`, "utf-8");
+  } catch {
+  }
+  const manualCommand = `npx ${buildSkillsInstallArgs(baseUrl, skillNames).join(" ")}`;
+  writeSdkSkillsStatusLine(
+    `Deepline agent skills are out of date, but neither \`bunx\` nor \`npx\` is available. Install Node.js/npm or Bun, then run:
+${manualCommand}`
+  );
+}
+function clearUnavailableSkillsNotice(baseUrl) {
+  try {
+    unlinkSync2(unavailableSkillsNoticePath(baseUrl));
+  } catch {
+  }
+}
+function sortedUniqueSkillNames(names) {
+  return [...new Set(names.map((name) => name.trim()).filter(Boolean))].sort(
+    (a, b) => a.localeCompare(b)
+  );
+}
+async function fetchV1SkillNames(baseUrl) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS2);
+  try {
+    const response = await fetch(
+      new URL("/.well-known/skills/index.json", baseUrl),
+      { signal: controller.signal }
+    );
+    if (!response.ok) return [];
+    const data = await response.json().catch(() => null);
+    const names = (data?.skills ?? []).filter((skill) => skill.install_surface === "v1").map((skill) => skill.name).filter(
+      (name) => typeof name === "string" && name.length > 0
+    );
+    return sortedUniqueSkillNames(names);
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function buildSdkSkillNames(v1SkillNames) {
+  return sortedUniqueSkillNames(v1SkillNames);
+}
+async function fetchSkillsUpdate(baseUrl, localVersion) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS2);
+  try {
+    const response = await fetch(new URL("/api/v2/cli/update-check", baseUrl), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        skills: {
+          version: localVersion
+        }
+      }),
+      signal: controller.signal
+    });
+    if (!response.ok) return null;
+    const data = await response.json().catch(() => null);
+    const skills = data?.skills;
+    if (!skills) return null;
+    return {
+      needsUpdate: skills.needs_update === true,
+      remoteVersion: typeof skills.remote?.version === "string" ? skills.remote.version.trim() : ""
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function buildSkillsInstallArgs(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
+  return buildSkillsAddArgs(baseUrl, sortedUniqueSkillNames(skillNames));
+}
+function buildBunxSkillsInstallArgs(baseUrl, skillNames) {
+  return buildSkillsAddArgs(baseUrl, sortedUniqueSkillNames(skillNames), {
+    firstArg: "--bun"
+  });
+}
+function hasCommand(command) {
+  const result = spawnSync3(command, ["--version"], {
+    stdio: "ignore",
+    shell: process.platform === "win32"
+  });
+  return result.status === 0;
+}
+function shellQuote6(arg) {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function resolveSkillsInstallCommands(baseUrl, skillNames = DEFAULT_SDK_SKILL_NAMES) {
+  const commands = [];
+  if (hasCommand("bunx")) {
+    const bunxArgs = buildBunxSkillsInstallArgs(baseUrl, skillNames);
+    commands.push({
+      command: "bunx",
+      args: bunxArgs,
+      manualCommand: `bunx ${bunxArgs.map(shellQuote6).join(" ")}`
+    });
+  }
+  if (hasCommand("npx")) {
+    const npxArgs = buildSkillsInstallArgs(baseUrl, skillNames);
+    commands.push({
+      command: "npx",
+      args: npxArgs,
+      manualCommand: `npx ${npxArgs.map(shellQuote6).join(" ")}`
+    });
+  }
+  return commands;
+}
+function runOneSkillsInstall(install) {
+  return new Promise((resolve15) => {
+    const child = spawn6(install.command, install.args, {
+      stdio: ["ignore", "ignore", "pipe"],
+      env: process.env
+    });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    child.on("error", (error) => {
+      resolve15({
+        ok: false,
+        detail: `failed to start ${install.command}: ${error.message}`,
+        manualCommand: install.manualCommand
+      });
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve15({ ok: true, detail: "", manualCommand: install.manualCommand });
+        return;
+      }
+      const detail = stderr.trim();
+      resolve15({
+        ok: false,
+        detail: detail ? `${install.command}: ${detail}` : `${install.command} exited ${code}`,
+        manualCommand: install.manualCommand
+      });
+    });
+  });
+}
+async function runSkillsInstall(installs) {
+  const failures = [];
+  for (const install of installs) {
+    const result = await runOneSkillsInstall(install);
+    if (result.ok) return true;
+    failures.push(result);
+  }
+  const details = failures.map((failure) => failure.detail).filter(Boolean).join("\n");
+  const manualCommand = failures.at(-1)?.manualCommand;
+  process.stderr.write(
+    `SDK skills sync failed${details ? `:
+${details}` : ""}
+` + (manualCommand ? `Run manually: ${manualCommand}
+` : "")
+  );
+  return false;
+}
+function runLegacySkillsCleanup() {
+  const candidates = hasCommand("bunx") ? [
+    {
+      command: "bunx",
+      args: [
+        "--bun",
+        "skills",
+        "remove",
+        "--global",
+        "-y",
+        ...LEGACY_SKILL_NAMES_TO_REMOVE
+      ]
+    },
+    {
+      command: "npx",
+      args: [
+        "--yes",
+        "skills",
+        "remove",
+        "--global",
+        "-y",
+        ...LEGACY_SKILL_NAMES_TO_REMOVE
+      ]
+    }
+  ] : [
+    {
+      command: "npx",
+      args: [
+        "--yes",
+        "skills",
+        "remove",
+        "--global",
+        "-y",
+        ...LEGACY_SKILL_NAMES_TO_REMOVE
+      ]
+    }
+  ];
+  for (const candidate of candidates) {
+    const result = spawnSync3(candidate.command, candidate.args, {
+      stdio: "ignore",
+      env: process.env,
+      shell: process.platform === "win32"
+    });
+    if (result.status === 0) return;
+  }
+}
+function writeSdkSkillsStatusLine(line) {
+  const progress = getActiveCliProgress();
+  if (progress) {
+    progress.writeLine(line);
+    return;
+  }
+  process.stderr.write(`${line}
+`);
+}
+async function syncSdkSkillsIfNeeded(baseUrl, options = {}) {
+  if (attemptedSync || shouldSkipSkillsSync()) return;
+  attemptedSync = true;
+  const usingPluginSkills = Boolean(activePluginSkillsDir());
+  if (usingPluginSkills) {
+    return;
+  }
+  const localVersion = readSdkSkillsLocalVersion(baseUrl);
+  const update = options.update === void 0 ? await fetchSkillsUpdate(baseUrl, localVersion) : options.update ? {
+    needsUpdate: options.update.needs_update,
+    remoteVersion: options.update.remote.version
+  } : null;
+  if (!update?.needsUpdate || !update.remoteVersion) {
+    return;
+  }
+  const remoteSkillNames = await fetchV1SkillNames(baseUrl);
+  const skillNames = buildSdkSkillNames(
+    remoteSkillNames.length > 0 ? remoteSkillNames : DEFAULT_SDK_SKILL_NAMES
+  );
+  if (skillNames.length === 0) return;
+  const installs = resolveSkillsInstallCommands(baseUrl, skillNames);
+  if (installs.length === 0) {
+    writeUnavailableSkillsNotice(baseUrl, update.remoteVersion, skillNames);
+    return;
+  }
+  writeSdkSkillsStatusLine("Deepline skills changed; syncing agent skills...");
+  const installed = await runSkillsInstall(installs);
+  if (!installed) return;
+  runLegacySkillsCleanup();
+  writeLocalSkillsVersion(baseUrl, update.remoteVersion);
+  clearUnavailableSkillsNotice(baseUrl);
+  writeSdkSkillsStatusLine("Deepline agent skills are up to date.");
 }
 
 // src/cli/failure-reporting.ts
@@ -30283,8 +31754,8 @@ function topLevelCommandKnown(program, commandName) {
   );
 }
 async function runPlayRunnerHealthCheck() {
-  const dir = await mkdtemp2(join15(tmpdir4(), "deepline-health-play-"));
-  const file = join15(dir, "health-check.play.ts");
+  const dir = await mkdtemp2(join18(tmpdir4(), "deepline-health-play-"));
+  const file = join18(dir, "health-check.play.ts");
   try {
     await writeFile5(
       file,
@@ -30502,7 +31973,7 @@ Exit codes:
 `
   );
   program.hook("preAction", async (_thisCommand, actionCommand) => {
-    if (actionCommand.name() === "version" || actionCommand.name() === "update" || actionCommand.name() === "switch" || isLegacyNoopInvocation()) {
+    if (actionCommand.name() === "version" || actionCommand.name() === "update" || actionCommand.name() === "switch" || actionCommand.name() === "setup" || actionCommand.name() === "skills" || actionCommand.name() === "doctor" || isLegacyNoopInvocation()) {
       return;
     }
     if (printStartupPhase) {
@@ -30574,6 +32045,8 @@ Exit codes:
   registerFeedbackCommands(program);
   registerLegacyNoopCommands(program);
   registerUpdateCommand(program);
+  registerSkillsCommand(program);
+  registerSetupCommands(program);
   registerQuickstartCommands(program);
   registerSwitchCommands(program);
   program.command("preflight").description("Run compact health, auth, and Deepline billing checks.").option("--json", "Force JSON output.").addHelpText(