deepline 0.1.260 → 0.1.262

package/dist/cli/index.mjs

@@ -701,7 +701,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.260",
+  version: "0.1.262",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",
@@ -26664,6 +26664,33 @@ function extractSummaryFields(payload) {
   return {};
 }
 
+// ../shared_libs/plays/tool-category-descriptions.ts
+var TOOL_CATEGORY_DESCRIPTIONS = {
+  company_search: "Find companies matching firmographic, ad, or web criteria.",
+  people_search: "Find people matching role, company, or persona criteria.",
+  people_enrich: "Enrich a known person with contact, social, and profile data.",
+  company_enrich: "Enrich a known company with firmographic and account data.",
+  email_finder: "Find work or personal email addresses for a person.",
+  email_verify: "Validate email deliverability and catch-all status.",
+  phone_finder: "Find mobile or direct phone numbers for a person.",
+  phone_verify: "Validate phone-number reachability and line type.",
+  research: "Research accounts, people, news, and signals for context and scoring.",
+  autocomplete: "Resolve names and entities to canonical catalog records.",
+  automation: "Kick off provider-side jobs, exports, and asynchronous workflows.",
+  outbound_tools: "Run outbound sequencing, deliverability, and campaign operations.",
+  admin: "Provider-side status, metadata, and account operations behind other tools.",
+  smb: "Look up small-business listings, local records, and public filings.",
+  identity_resolution: "Match a partial identity to a single resolved person or company.",
+  reverse_lookup: "Resolve an email, phone, or profile back to a person.",
+  enrichment: "General-purpose record enrichment across people and companies.",
+  batch: "Run an enrichment or search operation over many rows at once.",
+  premium: "Higher-cost tools with premium provider coverage.",
+  free: "Free tools that do not spend Deepline credits."
+};
+function describeToolCategory(category) {
+  return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
+}
+
 // src/cli/commands/model-description.ts
 function formatModelDescription(description) {
   const lines = [];
@@ -26830,21 +26857,181 @@ function zeroMatchRender(emptyResult) {
     ]
   };
 }
-async function listTools(args) {
+function firstSentence(text) {
+  const clean = (text ?? "").replace(/\s+/g, " ").trim();
+  if (!clean) return "";
+  const match = clean.match(/^.*?[.!?](?=\s|$)/);
+  return (match ? match[0] : clean).trim();
+}
+function requiredInputIds(tool) {
+  const inputSchema = recordField2(
+    tool,
+    "inputSchema",
+    "input_schema"
+  );
+  return toolInputFieldsForDisplay(inputSchema).filter((field) => field.required === true).map((field) => String(field.name ?? "")).filter(Boolean);
+}
+function shortPricingHint(tool) {
+  const pricing = recordField2(
+    tool,
+    "pricing"
+  );
+  const credits = numberField2(pricing, "creditsPerUnit", "credits_per_unit");
+  const unit = stringField2(pricing, "unit");
+  if (credits !== null) {
+    return `${formatDecimal(credits)} cr/${unit || "unit"}`;
+  }
+  const summary = stringField2(pricing, "summary");
+  if (summary) return summary;
+  const displayText = stringField2(pricing, "displayText", "display_text");
+  return displayText || null;
+}
+function aggregateCategorySummaries(tools) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    for (const category of tool.categories ?? []) {
+      counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].map(([name, count]) => ({
+    name,
+    count,
+    description: describeToolCategory(name)
+  })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+function categoryEnumerationRender(summaries) {
+  const nameWidth = summaries.reduce(
+    (max, item) => Math.max(max, item.name.length),
+    0
+  );
+  const countWidth = summaries.reduce(
+    (max, item) => Math.max(max, String(item.count).length),
+    0
+  );
+  return {
+    sections: [
+      {
+        title: `${summaries.length} tool categories:`,
+        lines: summaries.map((item) => {
+          const name = item.name.padEnd(nameWidth);
+          const count = String(item.count).padStart(countWidth);
+          const definition = item.description ? ` - ${item.description}` : "";
+          return `${name}  ${count}${definition}`;
+        })
+      },
+      {
+        title: "next",
+        lines: ["Pass a category: deepline tools list email_finder"]
+      }
+    ]
+  };
+}
+async function listToolCategories(emitJson, compact) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({ compact });
+  const items = rawTools.map(toListedTool);
+  const summaries = aggregateCategorySummaries(rawTools);
+  const outputItems = compact ? items.map(compactTool) : items;
+  printCommandEnvelope(
+    {
+      tools: outputItems,
+      count: outputItems.length,
+      categories: summaries,
+      filters: {
+        categories: []
+      },
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render: categoryEnumerationRender(summaries)
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+function unknownCategoryError(category, summaries, emitJson) {
+  const known = summaries.map((item) => item.name);
+  const message = `Unknown tool category "${category}". Run \`deepline tools list\` to browse categories.`;
+  if (emitJson) {
+    printJson({
+      ok: false,
+      exitCode: 4,
+      code: "TOOL_CATEGORY_NOT_FOUND",
+      message,
+      category,
+      categories: summaries,
+      next: "deepline tools list"
+    });
+    return 4;
+  }
+  const render = categoryEnumerationRender(summaries);
+  console.error(message);
+  console.error("");
+  console.error(renderCommandEnvelopeText({ render }).trimEnd());
+  console.error("");
+  console.error(`Valid categories: ${known.join(", ")}`);
+  return 4;
+}
+async function listToolsInCategory(category, emitJson) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({
+    categories: category,
+    compact: false
+  });
+  const allTools = await client2.listTools({ compact: true });
+  const summaries = aggregateCategorySummaries(allTools);
+  if (!summaries.some((item) => item.name === category)) {
+    return unknownCategoryError(category, summaries, emitJson);
+  }
+  const rows = rawTools.filter((tool) => tool.categories?.includes(category)).map((tool) => ({
+    id: tool.toolId,
+    provider: tool.provider,
+    required: requiredInputIds(tool),
+    pricing: shortPricingHint(tool),
+    description: firstSentence(tool.description)
+  })).sort((a, b) => a.id.localeCompare(b.id));
+  const idWidth = rows.reduce((max, row) => Math.max(max, row.id.length), 0);
+  const render = {
+    sections: [
+      {
+        title: `${rows.length} tools in ${category}:`,
+        lines: rows.map((row) => {
+          const id = row.id.padEnd(idWidth);
+          const required = row.required.length ? `(${row.required.join(", ")})` : "(no required inputs)";
+          const pricing = row.pricing ? ` [${row.pricing}]` : "";
+          const description = row.description ? ` - ${row.description}` : "";
+          return `${id}  ${required}${pricing}${description}`;
+        })
+      },
+      {
+        title: "next",
+        lines: [
+          "Run `deepline tools describe <toolId>` for the full contract."
+        ]
+      }
+    ]
+  };
+  printCommandEnvelope(
+    {
+      category,
+      total: rows.length,
+      tools: rows,
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+async function listToolsForCategoryFilter(requestedCategories, emitJson, compact) {
   const client2 = new DeeplineClient();
-  const categoryArgIndex = args.findIndex((arg) => arg === "--categories");
-  const categoryFilter = categoryArgIndex >= 0 ? args[categoryArgIndex + 1] : "";
-  const compact = !args.includes("--full");
-  const requestedCategories = categoryFilter ? categoryFilter.split(",").map((item) => item.trim()).filter(Boolean) : [];
   const items = (await client2.listTools({
-    ...categoryFilter ? { categories: categoryFilter } : {},
+    categories: requestedCategories.join(","),
     compact
   })).map(toListedTool).filter(
-    (item) => requestedCategories.length === 0 || requestedCategories.some(
+    (item) => requestedCategories.some(
       (category) => item.categories.includes(category)
     )
   );
-  const emptyResult = items.length === 0 && requestedCategories.length > 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
+  const emptyResult = items.length === 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
   const render = {
     sections: emptyResult ? zeroMatchRender(emptyResult).sections : [
       {
@@ -26875,10 +27062,41 @@ async function listTools(args) {
       commandTemplates: TOOL_COMMAND_TEMPLATES,
       render
     },
-    { json: argsWantJson(args) }
+    { json: emitJson }
   );
   return 0;
 }
+async function listTools(category, options = {}) {
+  const positional = category?.trim() ?? "";
+  const flagCategories = (options.categories ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  const compact = options.compact !== false;
+  const emitJson = options.json === true || shouldEmitJson();
+  if (positional && flagCategories.length > 0) {
+    const flagIsSameSingle = flagCategories.length === 1 && flagCategories[0] === positional;
+    if (!flagIsSameSingle) {
+      const message = `Category "${positional}" and --categories ${flagCategories.join(",")} disagree. Pass one: deepline tools list ${positional}`;
+      if (emitJson) {
+        printJson({
+          ok: false,
+          exitCode: 2,
+          code: "TOOL_LIST_CATEGORY_CONFLICT",
+          message,
+          next: `deepline tools list ${positional}`
+        });
+      } else {
+        console.error(message);
+      }
+      return 2;
+    }
+  }
+  if (positional) {
+    return listToolsInCategory(positional, emitJson);
+  }
+  if (flagCategories.length > 0) {
+    return listToolsForCategoryFilter(flagCategories, emitJson, compact);
+  }
+  return listToolCategories(emitJson, compact);
+}
 async function searchTools(queryInput, options = {}) {
   const query = queryInput?.trim() ?? "";
   const hasStructuredSearch = Boolean(
@@ -27077,27 +27295,37 @@ Output:
   Use execute to run a tool.
 `
   );
-  tools.command("list").description("List available tools.").addHelpText(
+  tools.command("list [category]").description("Browse tool categories, or list every tool in a category.").addHelpText(
     "after",
     `
 Notes:
-  Inventory command for known tool ids. Use search for ranked discovery by
-  intent, aliases, descriptions, and schema fields.
+  Bare \`tools list\` prints the category enumeration: one line per category with
+  its tool count and definition. Pass a category to list every tool in it, one
+  succinct row each (required inputs, Deepline pricing hint, first sentence).
+  The listing is exhaustive and never truncated. Use search for ranked discovery
+  by intent, aliases, descriptions, and schema fields.
+
+  --categories is a back-compat inventory filter. Passing it alone returns the
+  legacy flat inventory envelope (one row per tool). The positional category is
+  the newer exhaustive per-category view. If both are given they must name the
+  same category (the positional view wins); otherwise it is a usage error.
 
 Examples:
   deepline tools list
+  deepline tools list email_finder
+  deepline tools list email_finder --json
   deepline tools list --categories email_finder --json
   deepline tools search email --json
 `
   ).option(
     "--categories <categories>",
-    "Comma-separated categories to filter inventory"
-  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
-    process.exitCode = await listTools([
-      ...options.categories ? ["--categories", options.categories] : [],
-      ...options.compact ? ["--compact"] : [],
-      ...options.json ? ["--json"] : []
-    ]);
+    "Comma-separated categories filter (back-compat alias for the positional)"
+  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (category, options) => {
+    process.exitCode = await listTools(category, {
+      categories: typeof options.categories === "string" ? options.categories : void 0,
+      compact: options.compact !== false,
+      json: Boolean(options.json)
+    });
   });
   const addToolSearchCommand = (command) => command.description(
     "Search available tools by intent query or structured filters."
@@ -28940,7 +29168,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   realpathSync as realpathSync3,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
   unlinkSync,
@@ -28951,7 +29179,7 @@ import { dirname as dirname13, isAbsolute as isAbsolute3, join as join15, relati
 
 // src/cli/commands/skills.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync9, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
 import { homedir as homedir11 } from "os";
 import { dirname as dirname12, join as join14 } from "path";
 
@@ -29163,10 +29391,13 @@ function buildSkillsPlan(input2) {
     skillNames: input2.skillNames,
     version: input2.version,
     remove: {
-      command: "npx",
+      command: "npm",
       args: [
+        "exec",
         "--yes",
-        "skills@latest",
+        "--package=skills@latest",
+        "--",
+        "skills",
         "remove",
         ...scopeArgs,
         "--agent",
@@ -29176,10 +29407,13 @@ function buildSkillsPlan(input2) {
       ]
     },
     install: {
-      command: "npx",
+      command: "npm",
       args: [
+        "exec",
         "--yes",
-        "skills@latest",
+        "--package=skills@latest",
+        "--",
+        "skills",
         "add",
         skillsIndexUrl(input2.baseUrl),
         "--agent",
@@ -29193,6 +29427,29 @@ function buildSkillsPlan(input2) {
     statePath: skillsStatePathForScope(input2.baseUrl, input2.scope, input2.root)
   };
 }
+function sortedStrings(value) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    return null;
+  }
+  return [...value].sort((a, b) => a.localeCompare(b));
+}
+function isSkillsPlanCurrent(plan, state) {
+  if (!state || state.scope !== plan.scope || state.skillsVersion !== plan.version) {
+    return false;
+  }
+  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 readSkillsInstallState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync12(path, "utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
 function runProcess(command, args, cwd) {
   return new Promise((resolve15, reject) => {
     const child = spawn3(command, args, {
@@ -29216,7 +29473,7 @@ function runProcess(command, args, cwd) {
     });
   });
 }
-async function runSkillsCommand(options) {
+async function runSkillsCommand(options, dependencies = {}) {
   let scope;
   let root;
   try {
@@ -29238,7 +29495,7 @@ async function runSkillsCommand(options) {
   const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
   let catalog;
   try {
-    catalog = options.dryRun ? { skillNames: [...DEFAULT_SDK_SKILL_NAMES], version: "latest" } : await fetchSkillCatalog(baseUrl);
+    catalog = options.dryRun ? { skillNames: [...DEFAULT_SDK_SKILL_NAMES], version: "latest" } : await (dependencies.fetchCatalog ?? fetchSkillCatalog)(baseUrl);
   } catch (error) {
     printCommandEnvelope(
       {
@@ -29262,6 +29519,37 @@ async function runSkillsCommand(options) {
     );
     return 0;
   }
+  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;
+  }
   if (scope === "local" && root) {
     const managedNames = [
       .../* @__PURE__ */ new Set([...plan.skillNames, ...LEGACY_SKILL_NAMES_TO_REMOVE])
@@ -29279,7 +29567,8 @@ async function runSkillsCommand(options) {
 `
   );
   try {
-    const removeCode = await runProcess(
+    const execute = dependencies.runProcess ?? runProcess;
+    const removeCode = await execute(
       plan.remove.command,
       plan.remove.args,
       root ?? void 0
@@ -29287,7 +29576,7 @@ async function runSkillsCommand(options) {
     if (removeCode !== 0) {
       throw new Error("Could not remove the existing Deepline skills.");
     }
-    const installCode = await runProcess(
+    const installCode = await execute(
       plan.install.command,
       plan.install.args,
       root ?? void 0
@@ -29456,7 +29745,7 @@ function publicNpmFallbackRegistryUrl(hostUrl) {
 }
 function readOptionalText(path) {
   try {
-    return readFileSync12(path, "utf8").trim();
+    return readFileSync13(path, "utf8").trim();
   } catch {
     return "";
   }
@@ -29596,7 +29885,7 @@ function readAutoUpdateFailure(plan) {
   if (!path) return null;
   try {
     const parsed = JSON.parse(
-      readFileSync12(path, "utf8")
+      readFileSync13(path, "utf8")
     );
     if ((parsed.kind === "npm-global" || parsed.kind === "python-sidecar") && typeof parsed.packageSpec === "string" && typeof parsed.failedAt === "string" && typeof parsed.exitCode === "number" && typeof parsed.manualCommand === "string") {
       return parsed;
@@ -29680,7 +29969,7 @@ function installedPackageVersion(versionDir) {
     "package.json"
   );
   try {
-    const parsed = JSON.parse(readFileSync12(packageJsonPath, "utf8"));
+    const parsed = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
     return typeof parsed.version === "string" ? safeVersionSegment(parsed.version) : "";
   } catch {
     return "";
@@ -29993,13 +30282,92 @@ import {
   existsSync as existsSync13,
   lstatSync,
   mkdirSync as mkdirSync11,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   realpathSync as realpathSync4,
   rmSync as rmSync5,
   writeFileSync as writeFileSync16
 } from "fs";
 import { homedir as homedir13 } from "os";
 import { dirname as dirname14, join as join16, resolve as resolve14 } from "path";
+var SETUP_PHASE_NAMES = [
+  "cli",
+  "cleanup",
+  "skills",
+  "auth",
+  "verify"
+];
+function initialSetupPhases() {
+  return {
+    cli: { status: "pending" },
+    cleanup: { status: "pending" },
+    skills: { status: "pending" },
+    auth: { status: "pending" },
+    verify: { status: "pending" }
+  };
+}
+function isSetupPhaseStatus(value) {
+  return value === "pending" || value === "in_progress" || value === "complete" || value === "waiting" || value === "failed";
+}
+function parseSetupPhases(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const source = value;
+  const phases = initialSetupPhases();
+  for (const name of SETUP_PHASE_NAMES) {
+    const phase = source[name];
+    if (!phase || typeof phase !== "object" || Array.isArray(phase)) {
+      return null;
+    }
+    const record = phase;
+    if (!isSetupPhaseStatus(record.status)) return null;
+    phases[name] = {
+      status: record.status,
+      ...typeof record.outcome === "string" ? { outcome: record.outcome } : {},
+      ...typeof record.code === "string" ? { code: record.code } : {}
+    };
+  }
+  return phases;
+}
+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" };
+  }
+  if (status === "authorization_pending") {
+    phases.auth = { status: "waiting", outcome: "authorization_pending" };
+  } else if (status === "complete") {
+    phases.auth = { status: "complete" };
+    phases.verify = { status: "complete" };
+  }
+  return phases;
+}
+function readSetupState(input2) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync14(
+        setupStatePath(input2.baseUrl, input2.scope, input2.root),
+        "utf8"
+      )
+    );
+    if (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;
+  }
+}
+function selectSetupProgress(previousState) {
+  const resumed = Boolean(previousState && previousState.status !== "complete");
+  return {
+    resumed,
+    phases: resumed ? previousState.phases : initialSetupPhases()
+  };
+}
 function normalizeScope2(value) {
   if (!value || value === "global") return "global";
   if (value === "local") return "local";
@@ -30059,7 +30427,7 @@ function printCapturedAuthorizationUrl(stdout) {
 }
 function safeRead(path) {
   try {
-    return readFileSync13(path, "utf8");
+    return readFileSync14(path, "utf8");
   } catch {
     return "";
   }
@@ -30170,13 +30538,14 @@ function writeSetupState(input2) {
     path,
     `${JSON.stringify(
       {
-        schemaVersion: 1,
+        schemaVersion: 2,
         updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         cliVersion: SDK_VERSION,
         host: input2.baseUrl,
         scope: input2.scope,
         root: input2.root,
-        status: input2.status
+        status: input2.status,
+        phases: input2.phases
       },
       null,
       2
@@ -30186,6 +30555,24 @@ function writeSetupState(input2) {
   );
   return path;
 }
+function persistSetupProgress(input2) {
+  return writeSetupState({
+    ...input2,
+    status: input2.status ?? "in_progress"
+  });
+}
+function completeSetupPhase(phases, phase, outcome) {
+  phases[phase] = {
+    status: "complete",
+    ...outcome ? { outcome } : {}
+  };
+}
+function beginSetupPhase(phases, phase) {
+  phases[phase] = { status: "in_progress" };
+}
+function failSetupPhase(phases, phase, code) {
+  phases[phase] = { status: "failed", code };
+}
 function rollbackCommand(scope, root) {
   const prefix = scope === "local" && root ? ` --prefix ${JSON.stringify(join16(root, ".deepline", "runtime"))}` : "";
   return `npm install -g${prefix} --no-audit --no-fund --include=optional --allow-scripts=esbuild deepline@${SDK_VERSION}`;
@@ -30197,6 +30584,42 @@ 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(
@@ -30216,63 +30639,44 @@ async function readAuthStatus(authScope) {
 }
 function reportSetupAuthStatusFailure(input2) {
   if (!input2.auth.error) return null;
-  printCommandEnvelope(
-    {
-      ok: false,
-      status: "failed",
-      code: "AUTH_STATUS_FAILED",
-      exitCode: 4,
-      scope: input2.scope,
-      message: "Deepline could not verify authorization with the configured host.",
-      next: `Check network access, then rerun: deepline setup --scope ${input2.scope} --json`,
-      authScope: input2.authScope
-    },
-    { json: input2.json }
-  );
-  return 4;
+  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 }
+  });
 }
-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 skillsStatePath = skillsStatePathForScope(baseUrl, scope, root);
+function buildDoctorAssessment(input2) {
+  const skillsStatePath = skillsStatePathForScope(
+    input2.baseUrl,
+    input2.scope,
+    input2.root
+  );
   const skillsState = parseCapturedJson(safeRead(skillsStatePath));
-  const authScope = authScopeForSetup(scope);
-  const apiKey = scope === "local" ? resolveProjectApiKeyForBaseUrl(baseUrl) : resolveGlobalApiKeyForBaseUrl(baseUrl);
-  const projectAuth = scope === "local" && apiKey ? getResolvedProjectAuthSource(baseUrl, apiKey) : null;
-  const authStatus = await readAuthStatus(authScope);
-  const connected = authStatus.payload?.connected === true;
-  const authScopeOk = scope === "local" ? Boolean(projectAuth) : Boolean(apiKey && !projectAuth);
-  const skillsOk = skillsState?.scope === scope && Array.isArray(skillsState.agents) && skillsState.agents.length > 0;
+  const apiKey = input2.scope === "local" ? resolveProjectApiKeyForBaseUrl(input2.baseUrl) : resolveGlobalApiKeyForBaseUrl(input2.baseUrl);
+  const projectAuth = input2.scope === "local" && apiKey ? getResolvedProjectAuthSource(input2.baseUrl, apiKey) : null;
+  const connected = input2.authStatus.payload?.connected === true;
+  const authScopeOk = input2.scope === "local" ? Boolean(projectAuth) : Boolean(apiKey && !projectAuth);
+  const skillsOk = skillsState?.scope === input2.scope && typeof skillsState.skillsVersion === "string" && Array.isArray(skillsState.agents) && skillsState.agents.length > 0;
   const runningCliPath = process.argv[1] ? resolve14(process.argv[1]) : null;
-  const globalCli = scope === "global" ? inspectGlobalCliAvailability() : null;
+  const globalCli = input2.scope === "global" ? inspectGlobalCliAvailability() : null;
   const pathGlobalCli = globalCli?.path ?? null;
-  const cliPath = scope === "global" ? pathGlobalCli : runningCliPath;
-  const cliScopeOk = scope === "global" ? Boolean(pathGlobalCli) : Boolean(
-    root && runningCliPath?.includes(join16(root, ".deepline", "runtime"))
+  const cliPath = input2.scope === "global" ? pathGlobalCli : runningCliPath;
+  const cliScopeOk = input2.scope === "global" ? Boolean(pathGlobalCli) : Boolean(
+    input2.root && runningCliPath?.includes(join16(input2.root, ".deepline", "runtime"))
   );
   const checks = {
     cli: {
       ok: Boolean(cliPath) && cliScopeOk,
       version: SDK_VERSION,
       path: cliPath,
-      scope
+      scope: input2.scope
     },
     skills: {
       ok: skillsOk,
@@ -30283,16 +30687,48 @@ async function runDoctorCommand(options) {
     auth: {
       ok: connected && authScopeOk,
       scope: projectAuth ? "local" : apiKey ? "global" : null,
-      status: authStatus.payload?.status ?? "not_connected"
+      status: input2.authStatus.payload?.status ?? "not_connected"
     },
     api: {
-      ok: connected && authStatus.exitCode === 0,
-      host: baseUrl,
-      workspace: authStatus.payload?.workspace ?? null,
+      ok: connected && input2.authStatus.exitCode === 0,
+      host: input2.baseUrl,
+      workspace: input2.authStatus.payload?.workspace ?? null,
       providerSpend: false
     }
   };
-  const ok = Object.values(checks).every((check) => check.ok);
+  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(
     {
@@ -30318,11 +30754,16 @@ async function runDoctorCommand(options) {
   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"
+    status: "authorization_pending",
+    phases: input2.phases
   });
   if (input2.authorizationUrl) {
     process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
@@ -30336,6 +30777,14 @@ function pendingResult(input2) {
       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: [
@@ -30366,84 +30815,146 @@ async function runSetupCommand(options) {
         status: "failed",
         code: "INVALID_SETUP_SCOPE",
         exitCode: 2,
-        message: error instanceof Error ? error.message : String(error)
+        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(/\/$/, "");
-  if (scope === "global") {
-    const globalCli = inspectGlobalCliAvailability();
-    if (!globalCli.ok) {
-      const installedButUnreachable = Boolean(globalCli.persistentPath);
-      printCommandEnvelope(
-        {
-          ok: false,
-          status: "failed",
-          code: installedButUnreachable ? "GLOBAL_CLI_NOT_ON_PATH" : "GLOBAL_CLI_NOT_INSTALLED",
-          exitCode: 7,
+  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,
-          persistentPath: globalCli.persistentPath,
+          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.",
-          next: "Use the automatic project-local fallback in https://code.deepline.com/SKILL.md"
-        },
-        { json: options.json }
-      );
-      return 7;
+          json: options.json,
+          extra: {
+            persistentPath: globalCli.persistentPath,
+            fallback: "https://code.deepline.com/INSTALL.md"
+          }
+        });
+      }
     }
-  }
-  const conflict = inspectPathConflict();
-  if (conflict) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
+    const conflict = inspectPathConflict();
+    if (conflict) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "cli",
         code: "PATH_CONFLICT",
         exitCode: 7,
-        path: conflict,
         message: `An unknown executable named deepline is first on PATH: ${conflict}`,
-        next: "Move or rename that executable, then rerun: deepline setup --json"
-      },
-      { json: options.json }
-    );
-    return 7;
+        json: options.json,
+        extra: { path: conflict }
+      });
+    }
+    completeSetupPhase(phases, "cli", "available");
+    persistSetupProgress({ baseUrl, scope, root, phases });
   }
-  const removedLegacyPaths = removeKnownLegacyPaths(baseUrl);
-  if (removedLegacyPaths.length > 0) {
-    process.stderr.write(
-      `Removed ${removedLegacyPaths.length} known legacy Deepline path(s).
+  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
+      });
+    }
   }
-  process.stderr.write(`Installing Deepline skills (${scope})...
+  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 })
-  );
-  const skillsPayload = parseCapturedJson(skills.stdout);
-  if (skills.exitCode !== 0) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
+    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,
-        scope,
-        detail: skillsPayload,
-        next: `deepline skills --scope ${scope} --json`
-      },
-      { json: options.json }
+        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))
     );
-    return skills.exitCode;
   }
-  writeSetupState({ baseUrl, scope, root, status: "skills_installed" });
   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;
@@ -30458,8 +30969,11 @@ async function runSetupCommand(options) {
       auth = await readAuthStatus(authScope);
       const resumedAuthFailure = reportSetupAuthStatusFailure({
         auth,
+        baseUrl,
         authScope,
         scope,
+        root,
+        phases,
         json: options.json
       });
       if (resumedAuthFailure !== null) return resumedAuthFailure;
@@ -30470,7 +30984,9 @@ async function runSetupCommand(options) {
             baseUrl,
             scope,
             root,
+            phases,
             authorizationUrl: stillPending.claimUrl,
+            resumed,
             json: options.json
           });
         }
@@ -30487,24 +31003,30 @@ async function runSetupCommand(options) {
     );
     printCapturedAuthorizationUrl(registered.stdout);
     if (registered.exitCode !== 0) {
-      printCommandEnvelope(
-        {
-          ok: false,
-          status: "failed",
-          code: "AUTH_REGISTER_FAILED",
-          exitCode: registered.exitCode,
-          scope,
-          next: `deepline auth register --auth-scope ${authScope}`
-        },
-        { json: options.json }
-      );
-      return registered.exitCode;
+      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;
@@ -30514,40 +31036,60 @@ async function runSetupCommand(options) {
         baseUrl,
         scope,
         root,
+        phases,
         authorizationUrl: pending?.claimUrl ?? "",
+        resumed,
         json: options.json
       });
     }
   }
-  process.stderr.write("Verifying Deepline setup...\n");
-  const doctor = await captureStdout2(
-    () => runDoctorCommand({ scope, json: true })
-  );
-  const doctorPayload = parseCapturedJson(doctor.stdout);
-  if (doctor.exitCode !== 0) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
-        code: "DOCTOR_FAILED",
-        exitCode: doctor.exitCode,
-        scope,
+  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,
-        next: "Review the doctor result and choose a repair, then rerun: deepline setup --json"
-      },
-      { json: options.json }
-    );
-    return doctor.exitCode;
+        diagnostic: {
+          command: `deepline doctor --scope ${scope} --json`
+        }
+      }
+    });
   }
+  completeSetupPhase(phases, "verify", "verified");
   const statePath = writeSetupState({
     baseUrl,
     scope,
     root,
-    status: "complete"
+    status: "complete",
+    phases
   });
   const doctorChecks = asRecord2(doctorPayload?.checks);
   const apiCheck = asRecord2(doctorChecks?.api);
-  const quickstart = setupQuickstartCommand(baseUrl);
   printCommandEnvelope(
     {
       ok: true,
@@ -30560,6 +31102,10 @@ async function runSetupCommand(options) {
       rollbackCommand: rollbackCommand(scope, root),
       statePath,
       doctor: doctorPayload,
+      phases,
+      currentPhase: null,
+      failedPhase: null,
+      resumed,
       next: quickstart,
       render: {
         sections: [
@@ -30582,8 +31128,9 @@ function registerSetupCommands(program) {
     "after",
     `
 Notes:
-  Setup is idempotent. Bare setup resumes pending browser authorization.
+  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
@@ -30823,7 +31370,7 @@ import { spawn as spawn6, spawnSync as spawnSync3 } from "child_process";
 import {
   existsSync as existsSync14,
   mkdirSync as mkdirSync12,
-  readFileSync as readFileSync14,
+  readFileSync as readFileSync15,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync17
 } from "fs";
@@ -30849,7 +31396,7 @@ function readPluginSkillsVersion() {
   const dir = activePluginSkillsDir();
   if (!dir) return "";
   try {
-    return readFileSync14(join17(dir, ".version"), "utf-8").trim();
+    return readFileSync15(join17(dir, ".version"), "utf-8").trim();
   } catch {
     return "";
   }
@@ -30869,7 +31416,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
   const path = existsSync14(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
   if (!existsSync14(path)) return "";
   try {
-    return readFileSync14(path, "utf-8").trim();
+    return readFileSync15(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -30883,7 +31430,7 @@ function writeLocalSkillsVersion(baseUrl, version) {
 function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
   const path = unavailableSkillsNoticePath(baseUrl);
   try {
-    if (existsSync14(path) && readFileSync14(path, "utf-8").trim() === remoteVersion) {
+    if (existsSync14(path) && readFileSync15(path, "utf-8").trim() === remoteVersion) {
       return;
     }
     mkdirSync12(dirname15(path), { recursive: true });