deepline 0.1.259 → 0.1.261

package/dist/cli/index.js

@@ -182,8 +182,8 @@ configureProxyFromEnv();
 
 // src/cli/index.ts
 var import_promises6 = require("fs/promises");
-var import_node_path20 = require("path");
-var import_node_os15 = require("os");
+var import_node_path22 = require("path");
+var import_node_os17 = require("os");
 var import_commander4 = require("commander");
 
 // src/config.ts
@@ -499,6 +499,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();
@@ -542,14 +557,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 = (0, import_node_path.join)(gitDir, "info", "exclude");
+    const existing2 = (0, import_node_fs.existsSync)(excludePath) ? (0, import_node_fs.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;
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(excludePath), { recursive: true });
+    const prefix2 = existing2 && !existing2.endsWith("\n") ? "\n" : "";
+    (0, import_node_fs.writeFileSync)(
+      excludePath,
+      `${existing2}${prefix2}${missing2.join("\n")}
+`,
+      "utf-8"
+    );
+    return;
+  }
   const gitignorePath = (0, import_node_path.join)(dir, ".gitignore");
-  const entry = PROJECT_DEEPLINE_ENV_FILE;
   const existing = (0, import_node_fs.existsSync)(gitignorePath) ? (0, import_node_fs.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" : "";
-  (0, import_node_fs.writeFileSync)(gitignorePath, `${existing}${prefix}${entry}
-`, "utf-8");
+  (0, import_node_fs.writeFileSync)(
+    gitignorePath,
+    `${existing}${prefix}${missing.join("\n")}
+`,
+    "utf-8"
+  );
+}
+function findNearestGitCommonDir(startDir) {
+  let current = (0, import_node_path.resolve)(startDir);
+  while (true) {
+    const candidate = (0, import_node_path.join)(current, ".git");
+    if ((0, import_node_fs.existsSync)(candidate)) {
+      try {
+        const stat2 = (0, import_node_fs.statSync)(candidate);
+        if (stat2.isDirectory()) return candidate;
+        if (stat2.isFile()) {
+          const match = (0, import_node_fs.readFileSync)(candidate, "utf8").match(
+            /^gitdir:\s*(.+)$/m
+          );
+          const rawGitDir = match?.[1]?.trim();
+          if (rawGitDir) {
+            const gitDir = (0, import_node_path.isAbsolute)(rawGitDir) ? rawGitDir : (0, import_node_path.resolve)((0, import_node_path.dirname)(candidate), rawGitDir);
+            const commonDirPath = (0, import_node_path.join)(gitDir, "commondir");
+            if (!(0, import_node_fs.existsSync)(commonDirPath)) return gitDir;
+            const rawCommonDir = (0, import_node_fs.readFileSync)(commonDirPath, "utf8").trim();
+            return rawCommonDir ? (0, import_node_path.isAbsolute)(rawCommonDir) ? rawCommonDir : (0, import_node_path.resolve)(gitDir, rawCommonDir) : gitDir;
+          }
+        }
+      } catch {
+        return null;
+      }
+    }
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) return null;
+    current = parent;
+  }
 }
 function saveProjectDeeplineEnvValues(values, startDir = process.cwd()) {
   const target = resolveProjectPinTarget(startDir);
@@ -636,7 +716,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",
@@ -1321,7 +1401,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)) {
@@ -2293,14 +2373,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) {
@@ -2518,7 +2598,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") {
@@ -5679,30 +5759,86 @@ 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 (0, import_node_path5.join)(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 = (0, import_node_path5.dirname)(filePath);
   if (!(0, import_node_fs5.existsSync)(dir)) {
     (0, import_node_fs5.mkdirSync)(dir, { recursive: true });
   }
-  (0, import_node_fs5.writeFileSync)(filePath, `${claimToken}
-`, "utf-8");
+  (0, import_node_fs5.writeFileSync)(filePath, `${JSON.stringify(claim, null, 2)}
+`, {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
-function readPendingClaimToken(baseUrl) {
-  const filePath = pendingClaimTokenPath(baseUrl);
-  if (!(0, import_node_fs5.existsSync)(filePath)) return "";
+function readPendingAuthClaim(baseUrl, scope) {
+  let filePath;
   try {
-    return (0, import_node_fs5.readFileSync)(filePath, "utf-8").trim();
+    filePath = pendingClaimPath(baseUrl, scope);
   } catch {
-    return "";
+    return null;
+  }
+  if (!(0, import_node_fs5.existsSync)(filePath)) {
+    if (scope !== "global") return null;
+    try {
+      const claimToken = (0, import_node_fs5.readFileSync)(
+        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((0, import_node_fs5.readFileSync)(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 {
-    (0, import_node_fs5.rmSync)(pendingClaimTokenPath(baseUrl), { force: true });
+    (0, import_node_fs5.rmSync)(pendingClaimPath(baseUrl, scope), { force: true });
+    if (scope === "global") {
+      (0, import_node_fs5.rmSync)(legacyPendingClaimTokenPath(baseUrl), { force: true });
+    }
   } catch {
   }
 }
@@ -5727,12 +5863,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 = {
@@ -5795,7 +5935,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) {
@@ -5856,8 +5996,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;
@@ -5890,18 +6035,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));
@@ -5919,7 +6068,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;
     }
@@ -5940,15 +6089,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"
       );
@@ -5960,6 +6110,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);
@@ -5968,9 +6125,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;
     }
@@ -5986,7 +6145,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;
     }
@@ -6007,15 +6166,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;
     }
@@ -6030,6 +6190,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 {
@@ -6056,14 +6226,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: [
@@ -6145,7 +6317,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)",
@@ -6170,9 +6343,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 ? (0, import_node_path5.join)(target.dir, ".env.deepline") : null;
+      } else {
+        savedApiKeyPath = envFilePath(baseUrl);
+      }
     }
   }
   printCommandEnvelope(
@@ -6237,12 +6416,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(
@@ -6255,10 +6441,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(
@@ -6271,14 +6464,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"] : []
     ]);
   });
@@ -11302,7 +11497,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();
@@ -19617,7 +19812,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();
@@ -25044,7 +25239,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;
@@ -25247,7 +25442,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);
@@ -25624,17 +25819,17 @@ function hasClaudeBinary() {
   }
 }
 function launchClaude(prompt) {
-  return new Promise((resolve14) => {
+  return new Promise((resolve15) => {
     const child = (0, import_node_child_process2.spawn)("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) => {
@@ -25644,7 +25839,7 @@ function readBody(req) {
         req.destroy();
       }
     });
-    req.on("end", () => resolve14(raw));
+    req.on("end", () => resolve15(raw));
     req.on("error", reject);
   });
 }
@@ -25699,7 +25894,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();
@@ -25707,7 +25902,7 @@ function startCallbackServer(input2) {
         reject(new Error("Failed to bind quickstart callback server."));
         return;
       }
-      resolve14({ server, port: address.port });
+      resolve15({ server, port: address.port });
     });
   });
 }
@@ -25733,8 +25928,8 @@ async function handleQuickstart(options) {
   }
   const state = (0, import_node_crypto6.randomBytes)(32).toString("hex");
   let resolveSelection;
-  const selectionPromise = new Promise((resolve14) => {
-    resolveSelection = resolve14;
+  const selectionPromise = new Promise((resolve15) => {
+    resolveSelection = resolve15;
   });
   let callback;
   try {
@@ -25873,7 +26068,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);
@@ -25891,7 +26086,7 @@ async function readHiddenLine(prompt, streams = {}) {
       settled = true;
       outputStream.write("\n");
       cleanup();
-      resolve14(line);
+      resolve15(line);
     };
     const fail = (error) => {
       if (settled) return;
@@ -28694,12 +28889,13 @@ Notes:
 // src/cli/commands/update.ts
 var import_node_child_process4 = require("child_process");
 var import_node_fs17 = require("fs");
-var import_node_os13 = require("os");
+var import_node_os14 = require("os");
 var import_node_path19 = require("path");
 
-// src/cli/skills-sync.ts
+// src/cli/commands/skills.ts
 var import_node_child_process3 = require("child_process");
 var import_node_fs16 = require("fs");
+var import_node_os13 = require("os");
 var import_node_path18 = require("path");
 
 // ../shared_libs/cli/install-commands.json
@@ -28716,7 +28912,7 @@ var install_commands_default = {
     npx_binary: "npx",
     npx_add_args_template: [
       "--yes",
-      "skills",
+      "skills@latest",
       "add",
       "{skills_index_url}",
       "--agent",
@@ -28806,311 +29002,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 && (0, import_node_fs16.existsSync)(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 (0, import_node_fs16.readFileSync)((0, import_node_path18.join)(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 (0, import_node_path18.join)(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 ?? (0, import_node_os13.homedir)()
+  ];
+  const detected = AGENT_MARKERS.filter(
+    (marker) => roots.some(
+      (root) => marker.paths.some((path) => (0, import_node_fs16.existsSync)((0, import_node_path18.join)(root, path)))
+    )
+  ).map((marker) => marker.agent);
+  return detected.length > 0 ? detected : ["*"];
 }
-function legacySdkSkillsVersionPath(baseUrl) {
-  return (0, import_node_path18.join)((0, import_node_path18.dirname)(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 (0, import_node_path18.join)(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+function skillsStatePathForScope(baseUrl, scope, root) {
+  return scope === "local" && root ? (0, import_node_path18.join)(root, ".deepline", "setup", "skills.json") : (0, import_node_path18.join)(sdkCliStateDirPath(baseUrl), "skills-install.json");
 }
-function readSdkSkillsLocalVersion(baseUrl) {
-  const pluginVersion = readPluginSkillsVersion();
-  if (pluginVersion) return pluginVersion;
-  const path = (0, import_node_fs16.existsSync)(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
-  if (!(0, import_node_fs16.existsSync)(path)) return "";
-  try {
-    return (0, import_node_fs16.readFileSync)(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);
-  (0, import_node_fs16.mkdirSync)((0, import_node_path18.dirname)(path), { recursive: true });
-  (0, import_node_fs16.writeFileSync)(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 ((0, import_node_fs16.existsSync)(path) && (0, import_node_fs16.readFileSync)(path, "utf-8").trim() === remoteVersion) {
-      return;
-    }
-    (0, import_node_fs16.mkdirSync)((0, import_node_path18.dirname)(path), { recursive: true });
-    (0, import_node_fs16.writeFileSync)(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 {
-    (0, import_node_fs16.unlinkSync)(unavailableSkillsNoticePath(baseUrl));
+    const parsed = JSON.parse((0, import_node_fs16.readFileSync)(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 = (0, import_node_child_process3.spawn)(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 = (0, import_node_child_process3.spawnSync)(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 = (0, import_node_child_process3.spawn)(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 = (0, import_node_child_process3.spawnSync)(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
+  (0, import_node_fs16.mkdirSync)((0, import_node_path18.dirname)(plan.statePath), { recursive: true });
+  (0, import_node_fs16.writeFileSync)(
+    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
@@ -29142,14 +29407,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`;
 }
@@ -29161,7 +29426,7 @@ 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();
@@ -29224,7 +29489,7 @@ function resolvePythonSidecarUpdatePlan(options) {
   const npmCommand = "npm";
   const registryUrl = sidecarRegistryUrl(hostUrl);
   const versionDir = (0, import_node_path19.join)(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 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,
@@ -29272,7 +29537,7 @@ function inferNpmGlobalPrefixFromEntrypoint(entrypoint) {
 }
 function resolveUpdatePlan(options = {}) {
   const env = options.env ?? process.env;
-  const homeDir2 = options.homeDir ?? (0, import_node_os13.homedir)();
+  const homeDir2 = options.homeDir ?? (0, import_node_os14.homedir)();
   const entrypoint = options.entrypoint ?? (process.argv[1] ? (0, import_node_path19.resolve)(process.argv[1]) : "");
   const sourceRoot = entrypoint ? findRepoBackedSdkRoot((0, import_node_path19.dirname)(entrypoint)) : null;
   if (sourceRoot) {
@@ -29308,7 +29573,7 @@ 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";
@@ -29318,7 +29583,7 @@ function autoUpdateFailurePath(plan) {
     return (0, import_node_path19.join)(plan.stateDir, AUTO_UPDATE_FAILURE_FILE);
   }
   return (0, import_node_path19.join)(
-    (0, import_node_os13.homedir)(),
+    (0, import_node_os14.homedir)(),
     ".local",
     "deepline",
     "sdk-cli",
@@ -29513,9 +29778,9 @@ 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 }
@@ -29645,7 +29910,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 = {
@@ -29713,214 +29991,1399 @@ 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
+var import_node_child_process5 = require("child_process");
+var import_node_fs18 = require("fs");
+var import_node_os15 = require("os");
+var import_node_path20 = require("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(
+      (0, import_node_fs18.readFileSync)(
+        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
-var import_node_child_process5 = require("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 ? (0, import_node_path20.join)(root, ".deepline", "setup", "state.json") : (0, import_node_path20.join)(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 = (0, import_node_child_process5.spawn)(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 (0, import_node_fs18.readFileSync)(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 (0, import_node_fs18.realpathSync)(path).includes(`${(0, import_node_path20.join)("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 = (0, import_node_os15.homedir)();
+  const hostDir = (0, import_node_path20.join)(home, ".local", "deepline", baseUrlSlug(baseUrl));
+  const installerCommandPath = safeRead(
+    (0, import_node_path20.join)(hostDir, "sdk", ".command-path")
+  ).trim();
+  const candidates = [
+    (0, import_node_path20.join)(home, ".local", "bin", "deepline-real"),
+    (0, import_node_path20.join)(hostDir, "bin", "deepline"),
+    (0, import_node_path20.join)(hostDir, "bin", "deepline-real"),
+    (0, import_node_path20.join)(hostDir, "cli", ".install-method"),
+    (0, import_node_path20.join)(hostDir, "cli", ".version"),
+    (0, import_node_path20.join)(hostDir, "sdk", ".install-method"),
+    (0, import_node_path20.join)(hostDir, "sdk", ".command-path"),
+    ...installerCommandPath ? [
+      installerCommandPath,
+      (0, import_node_path20.join)((0, import_node_path20.dirname)(installerCommandPath), "deepline-sdk")
+    ] : []
+  ];
+  const removed = [];
+  for (const path of candidates) {
+    if (!(0, import_node_fs18.existsSync)(path)) continue;
+    if (path === installerCommandPath && isNpmManagedDeeplinePath(path)) {
+      continue;
+    }
+    (0, import_node_fs18.rmSync)(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 = (0, import_node_child_process5.spawnSync)(
+    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) => (0, import_node_path20.resolve)(path))
+    )
+  ];
+}
+function resolvePathCommand(command) {
+  return resolvePathCommands(command)[0] ?? null;
+}
+function resolvePersistentGlobalCommand() {
+  const prefix = (0, import_node_child_process5.spawnSync)("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" ? [(0, import_node_path20.join)(root, "deepline.cmd"), (0, import_node_path20.join)(root, "deepline")] : [(0, import_node_path20.join)(root, "bin", "deepline")];
+  return candidates.find((candidate) => (0, import_node_fs18.existsSync)(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 (0, import_node_fs18.realpathSync)(left) === (0, import_node_fs18.realpathSync)(right);
+  } catch {
+    return (0, import_node_path20.resolve)(left) === (0, import_node_path20.resolve)(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] ? (0, import_node_path20.resolve)(process.argv[1]) : "";
+  let resolvedPath = path;
+  try {
+    resolvedPath = (0, import_node_fs18.realpathSync)(path);
+  } catch {
+  }
+  if (entrypoint && resolvedPath === entrypoint) return true;
+  if (resolvedPath.includes(`${(0, import_node_path20.join)("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 ((0, import_node_fs18.lstatSync)(commandPath).isSymbolicLink()) {
+      const target = (0, import_node_fs18.realpathSync)(commandPath);
+      if (target.includes(`${(0, import_node_path20.join)("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;
 }
-
-// src/cli/failure-reporting.ts
-var import_node_os14 = require("os");
+function writeSetupState(input2) {
+  const path = setupStatePath(input2.baseUrl, input2.scope, input2.root);
+  (0, import_node_fs18.mkdirSync)((0, import_node_path20.dirname)(path), { recursive: true });
+  (0, import_node_fs18.writeFileSync)(
+    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((0, import_node_path20.join)(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] ? (0, import_node_path20.resolve)(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((0, import_node_path20.join)(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
+var import_node_child_process6 = require("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 = (0, import_node_child_process6.spawn)(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
+var import_node_child_process7 = require("child_process");
+var import_node_fs19 = require("fs");
+var import_node_path21 = require("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 && (0, import_node_fs19.existsSync)(dir) ? dir : "";
+}
+function readPluginSkillsVersion() {
+  const dir = activePluginSkillsDir();
+  if (!dir) return "";
+  try {
+    return (0, import_node_fs19.readFileSync)((0, import_node_path21.join)(dir, ".version"), "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function sdkSkillsVersionPath(baseUrl) {
+  return (0, import_node_path21.join)(sdkCliStateDirPath(baseUrl), "skills-version");
+}
+function legacySdkSkillsVersionPath(baseUrl) {
+  return (0, import_node_path21.join)((0, import_node_path21.dirname)(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
+}
+function unavailableSkillsNoticePath(baseUrl) {
+  return (0, import_node_path21.join)(sdkCliStateDirPath(baseUrl), "skills-sync-unavailable-version");
+}
+function readSdkSkillsLocalVersion(baseUrl) {
+  const pluginVersion = readPluginSkillsVersion();
+  if (pluginVersion) return pluginVersion;
+  const path = (0, import_node_fs19.existsSync)(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
+  if (!(0, import_node_fs19.existsSync)(path)) return "";
+  try {
+    return (0, import_node_fs19.readFileSync)(path, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function writeLocalSkillsVersion(baseUrl, version) {
+  const path = sdkSkillsVersionPath(baseUrl);
+  (0, import_node_fs19.mkdirSync)((0, import_node_path21.dirname)(path), { recursive: true });
+  (0, import_node_fs19.writeFileSync)(path, `${version}
+`, "utf-8");
+}
+function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
+  const path = unavailableSkillsNoticePath(baseUrl);
+  try {
+    if ((0, import_node_fs19.existsSync)(path) && (0, import_node_fs19.readFileSync)(path, "utf-8").trim() === remoteVersion) {
+      return;
+    }
+    (0, import_node_fs19.mkdirSync)((0, import_node_path21.dirname)(path), { recursive: true });
+    (0, import_node_fs19.writeFileSync)(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 {
+    (0, import_node_fs19.unlinkSync)(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 = (0, import_node_child_process7.spawnSync)(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 = (0, import_node_child_process7.spawn)(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 = (0, import_node_child_process7.spawnSync)(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
+var import_node_os16 = require("os");
 var FAILURE_REPORT_DISABLE_ENV = "DEEPLINE_DISABLE_FAILURE_REPORTING";
 var REPORT_FAILURE_TIMEOUT_MS = 1e4;
 var MAX_FAILURE_TEXT_CHARS = 4e3;
@@ -30022,12 +31485,12 @@ function isNetworkFailure(error) {
 }
 function buildEnvironmentContext() {
   const context = {
-    os: (0, import_node_os14.platform)(),
-    os_release: (0, import_node_os14.release)(),
-    platform: `${(0, import_node_os14.platform)()}-${(0, import_node_os14.release)()}-${process.arch}`,
+    os: (0, import_node_os16.platform)(),
+    os_release: (0, import_node_os16.release)(),
+    platform: `${(0, import_node_os16.platform)()}-${(0, import_node_os16.release)()}-${process.arch}`,
     node_version: process.version,
     runtime: "Node.js",
-    hostname: (0, import_node_os14.hostname)(),
+    hostname: (0, import_node_os16.hostname)(),
     agent_runtime: detectAgentRuntime()
   };
   for (const key of ["CLAUDE_CODE_REMOTE", "DEEPLINE_PLUGIN_MODE"]) {
@@ -30220,8 +31683,8 @@ function topLevelCommandKnown(program, commandName) {
   );
 }
 async function runPlayRunnerHealthCheck() {
-  const dir = await (0, import_promises6.mkdtemp)((0, import_node_path20.join)((0, import_node_os15.tmpdir)(), "deepline-health-play-"));
-  const file = (0, import_node_path20.join)(dir, "health-check.play.ts");
+  const dir = await (0, import_promises6.mkdtemp)((0, import_node_path22.join)((0, import_node_os17.tmpdir)(), "deepline-health-play-"));
+  const file = (0, import_node_path22.join)(dir, "health-check.play.ts");
   try {
     await (0, import_promises6.writeFile)(
       file,
@@ -30439,7 +31902,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) {
@@ -30511,6 +31974,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(