@apicircle/cli 1.0.9 → 1.1.0

package/dist/bin/cli.cjs

@@ -37,7 +37,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@apicircle/cli",
-      version: "1.0.9",
+      version: "1.1.0",
       private: false,
       type: "module",
       description: "Command-line interface for API Circle Studio. Run mock servers, drive the MCP server, and import OpenAPI / Postman / Insomnia collections from any terminal.",
@@ -115,6 +115,7 @@ var init_package = __esm({
         kleur: "^4.1.5"
       },
       devDependencies: {
+        "@apicircle/git": "workspace:*",
         "@types/node": "^20.0.0",
         tsup: "^8.3.0",
         typescript: "^5.4.0",
@@ -292,24 +293,7 @@ var init_loadWorkspace = __esm({
 function defaultWorkspacesRoot() {
   const override = process.env.APICIRCLE_WORKSPACES_ROOT;
   if (override && override.length > 0) return path3.resolve(override);
-  return path3.join(electronUserDataDir(), WORKSPACES_DIRNAME);
-}
-function electronUserDataDir() {
-  const home = os.homedir();
-  switch (process.platform) {
-    case "win32": {
-      const appdata = process.env.APPDATA ?? path3.join(home, "AppData", "Roaming");
-      return path3.join(appdata, APP_NAME, APP_SUBDIR);
-    }
-    case "darwin":
-      return path3.join(home, "Library", "Application Support", APP_NAME, APP_SUBDIR);
-    default:
-      return path3.join(
-        process.env.XDG_CONFIG_HOME ?? path3.join(home, ".config"),
-        APP_NAME,
-        APP_SUBDIR
-      );
-  }
+  return (0, import_registry.defaultApicircleRoot)();
 }
 async function resolveWorkspace(opts = {}) {
   const root = opts.workspacesRoot ?? defaultWorkspacesRoot();
@@ -490,7 +474,7 @@ function buildEmptyState(workspaceId, now, withSample) {
     }
   };
 }
-var os, path3, import_node_fs3, import_registry, import_file_backed2, import_shared3, APP_NAME, APP_SUBDIR, WORKSPACES_DIRNAME, WorkspaceResolutionError;
+var os, path3, import_node_fs3, import_registry, import_file_backed2, import_shared3, WorkspaceResolutionError;
 var init_resolveWorkspace = __esm({
   "src/util/resolveWorkspace.ts"() {
     "use strict";
@@ -500,9 +484,6 @@ var init_resolveWorkspace = __esm({
     import_registry = require("@apicircle/core/workspace/registry");
     import_file_backed2 = require("@apicircle/core/workspace/file-backed");
     import_shared3 = require("@apicircle/shared");
-    APP_NAME = "@apicircle";
-    APP_SUBDIR = "desktop";
-    WORKSPACES_DIRNAME = "workspaces";
     WorkspaceResolutionError = class extends Error {
       code;
       constructor(message, code) {
@@ -514,6 +495,152 @@ var init_resolveWorkspace = __esm({
   }
 });
 
+// src/commands/mocks.ts
+function registerMocksCommand(program) {
+  const mocks = program.command("mocks").description("Manage mock-server definitions in the active workspace");
+  mocks.command("list").description("List every mock server in the workspace + its default port").option(
+    "--workspace-name <name-or-id>",
+    "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+  ).option(
+    "-w, --workspace-path <dir>",
+    "Filesystem directory containing workspace.json (skips the registry)."
+  ).option("--json", "Emit JSON instead of a formatted table").action(async (opts) => {
+    const dir = await resolveDir(opts);
+    const state = await ensureWorkspace(dir);
+    const mockList = Object.values(state.synced.mockServers);
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify(
+          mockList.map((m) => ({
+            id: m.id,
+            name: m.name,
+            defaultPort: m.defaultPort,
+            endpoints: m.endpoints.length
+          })),
+          null,
+          2
+        ) + "\n"
+      );
+      return;
+    }
+    if (mockList.length === 0) {
+      process.stdout.write(`${import_kleur2.default.dim("No mock servers in this workspace.")}
+`);
+      return;
+    }
+    const nameWidth = Math.max(4, ...mockList.map((m) => m.name.length));
+    const idWidth = Math.max(2, ...mockList.map((m) => m.id.length));
+    process.stdout.write(
+      import_kleur2.default.bold(
+        `  ${"NAME".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  ${"PORT".padStart(6)}  ENDPOINTS
+`
+      )
+    );
+    for (const m of mockList) {
+      const portLabel = m.defaultPort === null ? import_kleur2.default.dim("auto") : String(m.defaultPort);
+      process.stdout.write(
+        `  ${m.name.padEnd(nameWidth)}  ${import_kleur2.default.dim(m.id.padEnd(idWidth))}  ${portLabel.padStart(6)}  ${m.endpoints.length}
+`
+      );
+    }
+  });
+  mocks.command("set-port").description("Set (or clear) the default port for a mock server in the active workspace").argument("<selector>", "Mock server id or case-insensitive name").argument(
+    "[port]",
+    'Port 1024-65535, or omit / "auto" / "null" to clear back to free-port mode'
+  ).option(
+    "--workspace-name <name-or-id>",
+    "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+  ).option(
+    "-w, --workspace-path <dir>",
+    "Filesystem directory containing workspace.json (skips the registry)."
+  ).action(async (selector, portArg, opts) => {
+    const dir = await resolveDir(opts);
+    const state = await ensureWorkspace(dir);
+    const target = findMock(state.synced, selector);
+    if (!target) {
+      process.stderr.write(
+        `${import_kleur2.default.red("error")}: no mock named "${selector}" in this workspace. Run ${import_kleur2.default.cyan("apicircle mocks list")} to see what's available.
+`
+      );
+      process.exit(2);
+      return;
+    }
+    const nextPort = parsePortArg(portArg);
+    if (nextPort === "invalid") {
+      process.stderr.write(
+        `${import_kleur2.default.red("error")}: port must be an integer in 1024-65535, or "auto" / "null" / omitted to clear.
+`
+      );
+      process.exit(2);
+      return;
+    }
+    if (target.defaultPort === nextPort) {
+      process.stdout.write(
+        `${import_kleur2.default.dim("unchanged")}: "${target.name}" already has defaultPort ${nextPort === null ? "auto" : String(nextPort)}.
+`
+      );
+      return;
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const updated = { ...target, defaultPort: nextPort, updatedAt: now };
+    const nextSynced = {
+      ...state.synced,
+      mockServers: { ...state.synced.mockServers, [target.id]: updated },
+      meta: { ...state.synced.meta, updatedAt: now }
+    };
+    await (0, import_file_backed3.saveToFile)(dir, { synced: nextSynced, local: state.local });
+    process.stdout.write(
+      `${import_kleur2.default.green("updated")} "${target.name}" defaultPort = ${nextPort === null ? import_kleur2.default.dim("auto (free port)") : import_kleur2.default.cyan(String(nextPort))}
+`
+    );
+  });
+}
+async function resolveDir(opts) {
+  try {
+    const resolved = await resolveWorkspace({
+      name: opts.workspaceName,
+      path: opts.workspacePath,
+      expectExists: false
+    });
+    return resolved.dir;
+  } catch (err) {
+    if (err instanceof WorkspaceResolutionError) {
+      process.stderr.write(`${import_kleur2.default.red("error")}: ${err.message}
+`);
+      process.exit(2);
+    }
+    throw err;
+  }
+}
+function findMock(synced, selector) {
+  const all = Object.values(synced.mockServers);
+  const byId = all.find((m) => m.id === selector);
+  if (byId) return byId;
+  const lower = selector.toLowerCase();
+  return all.find((m) => m.name.toLowerCase() === lower);
+}
+function parsePortArg(raw) {
+  if (raw === void 0) return null;
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed.toLowerCase() === "auto" || trimmed.toLowerCase() === "null") {
+    return null;
+  }
+  const n = Number(trimmed);
+  if (!Number.isInteger(n)) return "invalid";
+  if (n < 1024 || n > 65535) return "invalid";
+  return n;
+}
+var import_kleur2, import_file_backed3;
+var init_mocks = __esm({
+  "src/commands/mocks.ts"() {
+    "use strict";
+    import_kleur2 = __toESM(require("kleur"), 1);
+    import_file_backed3 = require("@apicircle/core/workspace/file-backed");
+    init_loadWorkspace();
+    init_resolveWorkspace();
+  }
+});
+
 // src/commands/mcp.ts
 function registerMcpCommand(program) {
   program.command("mcp").description("Run the API Circle MCP server (stdio transport)").option(
@@ -521,7 +648,7 @@ function registerMcpCommand(program) {
     "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
   ).option(
     "-w, --workspace-path <dir>",
-    "Filesystem directory containing workspace.synced.json (skips the registry)."
+    "Filesystem directory containing workspace.json (skips the registry)."
   ).action(async (opts) => {
     let dir;
     let label;
@@ -535,7 +662,7 @@ function registerMcpCommand(program) {
       label = resolved.fromRegistry ? `${resolved.name ?? resolved.id} (${dir})` : dir;
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${import_kleur2.default.red("error")}: ${err.message}
+        process.stderr.write(`${import_kleur3.default.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -545,7 +672,7 @@ function registerMcpCommand(program) {
       await ensureWorkspace(dir);
     } catch (err) {
       process.stderr.write(
-        `${import_kleur2.default.red("failed to initialise workspace")} at ${dir}: ${err instanceof Error ? err.message : String(err)}
+        `${import_kleur3.default.red("failed to initialise workspace")} at ${dir}: ${err instanceof Error ? err.message : String(err)}
 `
       );
       process.exit(1);
@@ -553,16 +680,16 @@ function registerMcpCommand(program) {
     const workspace = new import_mcp_server.FileBackedWorkspaceProvider(dir);
     const mock = new import_mcp_server.InProcessMockController();
     const host = (0, import_mcp_server.createMcpServer)({ workspace, mock });
-    process.stderr.write(`${import_kleur2.default.green("apicircle-mcp")} ready \xB7 workspace=${label}
+    process.stderr.write(`${import_kleur3.default.green("apicircle-mcp")} ready \xB7 workspace=${label}
 `);
     await host.connect();
   });
 }
-var import_kleur2, import_mcp_server;
+var import_kleur3, import_mcp_server;
 var init_mcp = __esm({
   "src/commands/mcp.ts"() {
     "use strict";
-    import_kleur2 = __toESM(require("kleur"), 1);
+    import_kleur3 = __toESM(require("kleur"), 1);
     import_mcp_server = require("@apicircle/mcp-server");
     init_loadWorkspace();
     init_resolveWorkspace();
@@ -579,7 +706,7 @@ function registerImportCommand(program) {
     "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
   ).option(
     "-w, --workspace-path <dir>",
-    "Filesystem directory containing workspace.synced.json (skips the registry)."
+    "Filesystem directory containing workspace.json (skips the registry)."
   ).option("-f, --format <format>", "OpenAPI format: json | yaml", "json").action(async (type, input, opts) => {
     let dir;
     try {
@@ -591,13 +718,13 @@ function registerImportCommand(program) {
       dir = resolved.dir;
       if (resolved.fromRegistry) {
         process.stderr.write(
-          `${import_kleur3.default.dim("workspace")}: ${import_kleur3.default.cyan(resolved.name ?? resolved.id ?? "")} ${import_kleur3.default.dim(`(${dir})`)}
+          `${import_kleur4.default.dim("workspace")}: ${import_kleur4.default.cyan(resolved.name ?? resolved.id ?? "")} ${import_kleur4.default.dim(`(${dir})`)}
 `
         );
       }
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${import_kleur3.default.red("error")}: ${err.message}
+        process.stderr.write(`${import_kleur4.default.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -670,7 +797,7 @@ function registerImportCommand(program) {
         parsedEnvelope = (0, import_core.parseApicircleFolderExport)(raw);
       } catch (err) {
         process.stderr.write(
-          `${import_kleur3.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
+          `${import_kleur4.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
 `
         );
         process.exit(2);
@@ -683,29 +810,29 @@ function registerImportCommand(program) {
       nextLocal = out.next.local;
       for (const r of parsedEnvelope.requests) created.push(r.id);
       for (const w of parsedEnvelope.warnings) {
-        process.stderr.write(`${import_kleur3.default.yellow("warning")}: ${w}
+        process.stderr.write(`${import_kleur4.default.yellow("warning")}: ${w}
 `);
       }
-      await (0, import_file_backed3.saveToFile)(dir, { synced: nextSynced, local: nextLocal });
+      await (0, import_file_backed4.saveToFile)(dir, { synced: nextSynced, local: nextLocal });
       process.stdout.write(
-        `${import_kleur3.default.green("imported")} folder "${parsedEnvelope.rootFolder.name}" (${parsedEnvelope.subfolders.length + 1} folders, ${parsedEnvelope.requests.length} requests) into ${dir}
+        `${import_kleur4.default.green("imported")} folder "${parsedEnvelope.rootFolder.name}" (${parsedEnvelope.subfolders.length + 1} folders, ${parsedEnvelope.requests.length} requests) into ${dir}
 `
       );
       if (parsedEnvelope.dependencies.files.length > 0) {
         process.stderr.write(
-          `${import_kleur3.default.yellow("note")}: ${parsedEnvelope.dependencies.files.length} file asset${parsedEnvelope.dependencies.files.length === 1 ? "" : "s"} landed without bytes \u2014 re-attach them inside Global Assets \u2192 Global Files.
+          `${import_kleur4.default.yellow("note")}: ${parsedEnvelope.dependencies.files.length} file asset${parsedEnvelope.dependencies.files.length === 1 ? "" : "s"} landed without bytes \u2014 re-attach them inside Global Assets \u2192 Global Files.
 `
         );
       }
       return;
     } else {
-      process.stderr.write(`${import_kleur3.default.red("error")}: unknown type '${String(type)}'
+      process.stderr.write(`${import_kleur4.default.red("error")}: unknown type '${String(type)}'
 `);
       process.exit(2);
     }
-    await (0, import_file_backed3.saveToFile)(dir, { synced: nextSynced, local: nextLocal });
+    await (0, import_file_backed4.saveToFile)(dir, { synced: nextSynced, local: nextLocal });
     process.stdout.write(
-      `${import_kleur3.default.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
+      `${import_kleur4.default.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
 `
     );
   });
@@ -741,15 +868,15 @@ function blankRequest(partial) {
     ...partial
   };
 }
-var import_node_fs4, path4, import_kleur3, import_core, import_file_backed3, import_mock_server_core2, import_shared4;
+var import_node_fs4, path4, import_kleur4, import_core, import_file_backed4, import_mock_server_core2, import_shared4;
 var init_import = __esm({
   "src/commands/import.ts"() {
     "use strict";
     import_node_fs4 = require("fs");
     path4 = __toESM(require("path"), 1);
-    import_kleur3 = __toESM(require("kleur"), 1);
+    import_kleur4 = __toESM(require("kleur"), 1);
     import_core = require("@apicircle/core");
-    import_file_backed3 = require("@apicircle/core/workspace/file-backed");
+    import_file_backed4 = require("@apicircle/core/workspace/file-backed");
     import_mock_server_core2 = require("@apicircle/mock-server-core");
     import_shared4 = require("@apicircle/shared");
     init_loadWorkspace();
@@ -776,7 +903,7 @@ function registerExportCommand(program) {
     "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
   ).option(
     "-w, --workspace-path <dir>",
-    "Filesystem directory containing workspace.synced.json (skips the registry)."
+    "Filesystem directory containing workspace.json (skips the registry)."
   ).action(async (folder, opts) => {
     let dir;
     try {
@@ -787,7 +914,7 @@ function registerExportCommand(program) {
       dir = resolved.dir;
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${import_kleur4.default.red("error")}: ${err.message}
+        process.stderr.write(`${import_kleur5.default.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -796,13 +923,13 @@ function registerExportCommand(program) {
     const state = await ensureWorkspace(dir);
     const folderId = resolveFolderId(state.synced.collections.folders, folder);
     if (!folderId) {
-      process.stderr.write(`${import_kleur4.default.red("error")}: no folder matches "${folder}" in ${dir}
+      process.stderr.write(`${import_kleur5.default.red("error")}: no folder matches "${folder}" in ${dir}
 `);
       process.exit(2);
     }
     const collected = (0, import_core2.collectFolderExport)({ synced: state.synced, folderId });
     if (!collected) {
-      process.stderr.write(`${import_kleur4.default.red("error")}: folder "${folder}" no longer exists
+      process.stderr.write(`${import_kleur5.default.red("error")}: folder "${folder}" no longer exists
 `);
       process.exit(2);
     }
@@ -824,20 +951,20 @@ function registerExportCommand(program) {
       const outPath = path5.resolve(opts.out);
       await import_node_fs5.promises.writeFile(outPath, json, "utf-8");
       process.stderr.write(
-        `${import_kleur4.default.green("exported")} folder "${collected.report.folderName}" \u2192 ${outPath}
+        `${import_kleur5.default.green("exported")} folder "${collected.report.folderName}" \u2192 ${outPath}
 `
       );
     } else {
       process.stdout.write(json);
       process.stdout.write("\n");
       process.stderr.write(
-        `${import_kleur4.default.green("exported")} folder "${collected.report.folderName}" (${collected.report.totalFolderCount} folders, ${collected.report.requestCount} requests, ${collected.report.credentials.length - includeIds.size} credentials redacted)
+        `${import_kleur5.default.green("exported")} folder "${collected.report.folderName}" (${collected.report.totalFolderCount} folders, ${collected.report.requestCount} requests, ${collected.report.credentials.length - includeIds.size} credentials redacted)
 `
       );
     }
     if (!opts.out) {
       process.stderr.write(
-        `${import_kleur4.default.dim("hint")}: save with .apicircle.json, e.g. ${(0, import_core2.suggestFolderExportFilename)(envelope)}
+        `${import_kleur5.default.dim("hint")}: save with .apicircle.json, e.g. ${(0, import_core2.suggestFolderExportFilename)(envelope)}
 `
       );
     }
@@ -850,13 +977,13 @@ function resolveFolderId(folders, query) {
   if (matches.length === 1) return matches[0].id;
   return null;
 }
-var import_node_fs5, path5, import_kleur4, import_core2;
+var import_node_fs5, path5, import_kleur5, import_core2;
 var init_export = __esm({
   "src/commands/export.ts"() {
     "use strict";
     import_node_fs5 = require("fs");
     path5 = __toESM(require("path"), 1);
-    import_kleur4 = __toESM(require("kleur"), 1);
+    import_kleur5 = __toESM(require("kleur"), 1);
     import_core2 = require("@apicircle/core");
     init_loadWorkspace();
     init_resolveWorkspace();
@@ -915,6 +1042,10 @@ async function prepareExecutionAttachments(workspaceDir, state, plan) {
   const entries = [];
   for (const requirement of requirements) {
     const localPath = path7.join(cacheDir, encodeURIComponent(requirement.slotId));
+    const resolvedLocal = path7.resolve(localPath);
+    if (!resolvedLocal.startsWith(path7.resolve(cacheDir) + path7.sep)) {
+      throw new Error(`Attachment path escapes cache directory: ${requirement.slotId}`);
+    }
     const present = await hasExpectedFile(localPath, requirement.sha256);
     if (present) {
       alreadyPresent++;
@@ -1015,6 +1146,7 @@ function collectExecutionAttachmentRequirements(state, plan) {
     addRequirement(seen, {
       ...slot,
       source: "workspace",
+      sourceWorkspaceId: state.synced.workspaceId,
       repoFullName: state.local.connectedRepo?.fullName ?? void 0,
       branch: state.local.workingBranch?.name ?? void 0,
       publicRepo: state.local.connectedRepo ? !state.local.connectedRepo.isPrivate : false,
@@ -1046,6 +1178,7 @@ function collectExecutionAttachmentRequirements(state, plan) {
       addRequirement(seen, {
         ...slot,
         source: "linked-workspace",
+        sourceWorkspaceId: link.sourceWorkspaceId,
         linkedWorkspaceId,
         repoFullName: link.source.repoFullName,
         branch: link.source.branch,
@@ -1117,7 +1250,12 @@ async function downloadAttachment(requirement) {
       "private linked attachments need a GitHub token (set APICIRCLE_GITHUB_TOKEN or GITHUB_TOKEN)"
     );
   }
-  const apiPath = [".apicircle", "attachments", requirement.slotId].map(encodeURIComponent).join("/");
+  const apiPath = [
+    ".apicircle",
+    `workspace-${requirement.sourceWorkspaceId}`,
+    "attachments",
+    requirement.slotId
+  ].map(encodeURIComponent).join("/");
   const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(
     repo
   )}/contents/${apiPath}?ref=${encodeURIComponent(requirement.branch)}`;
@@ -1169,7 +1307,7 @@ var init_executionAttachments = __esm({
     import_node_fs7 = require("fs");
     path7 = __toESM(require("path"), 1);
     import_core3 = require("@apicircle/core");
-    ATTACHMENTS_DIR = path7.join(".apicircle", "attachments");
+    ATTACHMENTS_DIR = "attachments";
   }
 });
 
@@ -1180,7 +1318,7 @@ function registerRunCommand(program) {
     "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
   ).option(
     "-w, --workspace-path <dir>",
-    "Filesystem directory containing workspace.synced.json (skips the registry)."
+    "Filesystem directory containing workspace.json (skips the registry)."
   ).option("--no-assertions", "Run requests without evaluating their assertions").option("-s, --secrets <file>", "JSON file mapping secretKeyId \u2192 plaintext value").option("--no-save", "Do not write the plan run to workspace history").option("--reporter <format>", "Report format: text | json | junit", "text").option("--bail", "Stop the run at the first failed step").option("-e, --env <name>", "Layer a local environment on top of the run").option("--as <actor>", "Override the recorded runner identity").action(async (planRef, opts) => {
     let dir;
     try {
@@ -1192,7 +1330,7 @@ function registerRunCommand(program) {
       dir = resolved.dir;
       if (resolved.fromRegistry) {
         process.stderr.write(
-          `${import_kleur5.default.dim("workspace")}: ${import_kleur5.default.cyan(resolved.name ?? resolved.id ?? "")} ${import_kleur5.default.dim(`(${dir})`)}
+          `${import_kleur6.default.dim("workspace")}: ${import_kleur6.default.cyan(resolved.name ?? resolved.id ?? "")} ${import_kleur6.default.dim(`(${dir})`)}
 `
         );
       }
@@ -1208,9 +1346,9 @@ function registerRunCommand(program) {
       fail(`unknown --reporter "${reporter}" (expected: ${REPORTERS.join(", ")})`);
       return;
     }
-    const state = await (0, import_file_backed4.loadFromFile)(dir, { allowMissing: true });
+    const state = await (0, import_file_backed5.loadFromFile)(dir, { allowMissing: true });
     if (!state) {
-      fail(`no workspace found at ${dir} (expected workspace.synced.json)`);
+      fail(`no workspace found at ${dir} (expected workspace.json)`);
       return;
     }
     const ref = (0, import_core4.resolvePlanRef)(state.synced, planRef);
@@ -1280,7 +1418,7 @@ function registerRunCommand(program) {
     process.off("SIGINT", onSigint);
     const aborted = controller.signal.aborted;
     const saved = opts.save !== false;
-    if (saved) await (0, import_file_backed4.saveToFile)(dir, result.nextState);
+    if (saved) await (0, import_file_backed5.saveToFile)(dir, result.nextState);
     if (reporter === "json") {
       process.stdout.write(
         JSON.stringify(
@@ -1321,17 +1459,17 @@ function formatHeader(plan, actor, withAssertions, opts) {
     opts.bail ? "bail" : null,
     opts.env ? `env=${opts.env}` : null
   ].filter((f) => f !== null);
-  return `${import_kleur5.default.bold("Plan")} ${plan.name}  ${import_kleur5.default.dim(
+  return `${import_kleur6.default.bold("Plan")} ${plan.name}  ${import_kleur6.default.dim(
     `(${enabled}/${plan.steps.length} steps \xB7 ${flags.join(" \xB7 ")})`
   )}
-${import_kleur5.default.dim("Run by")} ${actor.name} ${import_kleur5.default.dim(`(${actor.kind})`)}
+${import_kleur6.default.dim("Run by")} ${actor.name} ${import_kleur6.default.dim(`(${actor.kind})`)}
 
 `;
 }
 function formatAttachmentPreparation(summary) {
   const status = `${summary.downloaded} downloaded, ${summary.alreadyPresent} already local`;
   const lines = [
-    `${import_kleur5.default.bold("Attachments")} ${summary.total} required ${import_kleur5.default.dim(
+    `${import_kleur6.default.bold("Attachments")} ${summary.total} required ${import_kleur6.default.dim(
       `(${status} - ${summary.cacheDir})`
     )}`
   ];
@@ -1339,7 +1477,7 @@ function formatAttachmentPreparation(summary) {
     const source = entry3.source === "linked-workspace" ? `linked:${entry3.linkedWorkspaceId ?? "unknown"}` : "workspace";
     const requiredBy = entry3.requiredBy.map((item) => item.requestName).join(", ");
     lines.push(
-      `  ${import_kleur5.default.dim("file")} ${entry3.filename} ${import_kleur5.default.dim(
+      `  ${import_kleur6.default.dim("file")} ${entry3.filename} ${import_kleur6.default.dim(
         `${source} - ${requiredBy} - ${entry3.localPath}`
       )}`
     );
@@ -1352,31 +1490,31 @@ function formatStepLine(step) {
   const n = `${step.stepIndex + 1}.`.padEnd(3);
   const method = (step.requestMethod || "\u2014").padEnd(7);
   if (step.skipped) {
-    return `  ${import_kleur5.default.dim("\u2013")} ${import_kleur5.default.dim(n)} ${import_kleur5.default.dim(method)} ${import_kleur5.default.dim(
+    return `  ${import_kleur6.default.dim("\u2013")} ${import_kleur6.default.dim(n)} ${import_kleur6.default.dim(method)} ${import_kleur6.default.dim(
       `${step.requestName}  skipped`
     )}
 `;
   }
-  const mark = step.passed ? import_kleur5.default.green("\u2713") : import_kleur5.default.red("\u2717");
+  const mark = step.passed ? import_kleur6.default.green("\u2713") : import_kleur6.default.red("\u2717");
   const status = step.result?.status != null ? String(step.result.status) : "\u2014";
   const duration = step.result ? `${step.result.durationMs}ms` : "";
   const name = step.requestName.padEnd(28);
-  let line = `  ${mark} ${n} ${method} ${name} ${status.padEnd(4)} ${import_kleur5.default.dim(duration)}`;
+  let line = `  ${mark} ${n} ${method} ${name} ${status.padEnd(4)} ${import_kleur6.default.dim(duration)}`;
   if (step.assertionResults.length > 0) {
     const passed = step.assertionResults.filter((a) => a.passed).length;
-    line += `  ${import_kleur5.default.dim(`${passed}/${step.assertionResults.length} assertions`)}`;
+    line += `  ${import_kleur6.default.dim(`${passed}/${step.assertionResults.length} assertions`)}`;
   }
   line += "\n";
   if (step.error) {
-    line += `      ${import_kleur5.default.red(step.error)}
+    line += `      ${import_kleur6.default.red(step.error)}
 `;
   }
   for (const a of step.assertionResults) {
-    if (!a.passed) line += `      ${import_kleur5.default.red("\u2717")} ${a.detail ?? `${a.kind} ${a.op}`}
+    if (!a.passed) line += `      ${import_kleur6.default.red("\u2717")} ${a.detail ?? `${a.kind} ${a.op}`}
 `;
   }
   if (step.missingVariables.length > 0) {
-    line += `      ${import_kleur5.default.yellow("\u26A0")} unresolved: ${step.missingVariables.map((v) => `{{${v}}}`).join(", ")}
+    line += `      ${import_kleur6.default.yellow("\u26A0")} unresolved: ${step.missingVariables.map((v) => `{{${v}}}`).join(", ")}
 `;
   }
   return line;
@@ -1395,24 +1533,24 @@ function tally(result) {
 function formatSummary(result, saved, aborted) {
   if (result.steps.length === 0) {
     return `
-${import_kleur5.default.yellow("Plan has no steps.")}
+${import_kleur6.default.yellow("Plan has no steps.")}
 `;
   }
   const { passed, failed, skipped } = tally(result);
   const parts = [
-    import_kleur5.default.green(`${passed} passed`),
-    failed > 0 ? import_kleur5.default.red(`${failed} failed`) : import_kleur5.default.dim(`${failed} failed`),
-    import_kleur5.default.dim(`${skipped} skipped`)
+    import_kleur6.default.green(`${passed} passed`),
+    failed > 0 ? import_kleur6.default.red(`${failed} failed`) : import_kleur6.default.dim(`${failed} failed`),
+    import_kleur6.default.dim(`${skipped} skipped`)
   ];
-  const verdict = result.passed && !aborted ? import_kleur5.default.green("PASS") : import_kleur5.default.red("FAIL");
+  const verdict = result.passed && !aborted ? import_kleur6.default.green("PASS") : import_kleur6.default.red("FAIL");
   let out = `
-${verdict}  ${parts.join(import_kleur5.default.dim(" \xB7 "))}  ${import_kleur5.default.dim(
+${verdict}  ${parts.join(import_kleur6.default.dim(" \xB7 "))}  ${import_kleur6.default.dim(
     `\xB7 ${result.planRun.durationMs}ms`
   )}
 `;
-  if (aborted) out += `${import_kleur5.default.yellow("Run aborted before every step finished.")}
+  if (aborted) out += `${import_kleur6.default.yellow("Run aborted before every step finished.")}
 `;
-  out += saved ? import_kleur5.default.dim("Plan run saved to workspace history.\n") : import_kleur5.default.dim("Plan run not saved (--no-save).\n");
+  out += saved ? import_kleur6.default.dim("Plan run saved to workspace history.\n") : import_kleur6.default.dim("Plan run not saved (--no-save).\n");
   return out;
 }
 function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted, attachments) {
@@ -1488,18 +1626,18 @@ ${cases.join("\n")}
 `;
 }
 function fail(message, code = 2, kind = "error") {
-  process.stderr.write(`${import_kleur5.default.red(kind)}: ${message}
+  process.stderr.write(`${import_kleur6.default.red(kind)}: ${message}
 `);
   process.exitCode = code;
 }
-var os2, import_kleur5, import_core4, import_file_backed4, REPORTERS;
+var os2, import_kleur6, import_core4, import_file_backed5, REPORTERS;
 var init_run = __esm({
   "src/commands/run.ts"() {
     "use strict";
     os2 = __toESM(require("os"), 1);
-    import_kleur5 = __toESM(require("kleur"), 1);
+    import_kleur6 = __toESM(require("kleur"), 1);
     import_core4 = require("@apicircle/core");
-    import_file_backed4 = require("@apicircle/core/workspace/file-backed");
+    import_file_backed5 = require("@apicircle/core/workspace/file-backed");
     init_secrets();
     init_resolveWorkspace();
     init_executionAttachments();
@@ -1518,15 +1656,15 @@ function registerWorkspacesCommand(program) {
     }
     if (registry.workspaces.length === 0) {
       process.stdout.write(
-        `${import_kleur6.default.dim("No workspaces registered yet at")} ${root}
-${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle workspaces create <name>")} ${import_kleur6.default.dim(
+        `${import_kleur7.default.dim("No workspaces registered yet at")} ${root}
+${import_kleur7.default.dim("Run")} ${import_kleur7.default.cyan("apicircle workspaces create <name>")} ${import_kleur7.default.dim(
           "or open the desktop app to seed one."
         )}
 `
       );
       return;
     }
-    process.stdout.write(`${import_kleur6.default.dim("registry")}: ${root}
+    process.stdout.write(`${import_kleur7.default.dim("registry")}: ${root}
 
 `);
     const rows = [...registry.workspaces].sort(
@@ -1535,22 +1673,22 @@ ${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle work
     const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
     const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
     process.stdout.write(
-      import_kleur6.default.bold(
+      import_kleur7.default.bold(
         `  ${"".padEnd(1)} ${"NAME".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  LAST OPENED
 `
       )
     );
     for (const w of rows) {
-      const mark = w.id === registry.activeWorkspaceId ? import_kleur6.default.green("\u25CF") : " ";
+      const mark = w.id === registry.activeWorkspaceId ? import_kleur7.default.green("\u25CF") : " ";
       process.stdout.write(
-        `  ${mark} ${w.name.padEnd(nameWidth)}  ${import_kleur6.default.dim(
+        `  ${mark} ${w.name.padEnd(nameWidth)}  ${import_kleur7.default.dim(
           w.id.padEnd(idWidth)
-        )}  ${import_kleur6.default.dim(w.lastOpenedAt)}
+        )}  ${import_kleur7.default.dim(w.lastOpenedAt)}
 `
       );
     }
     process.stdout.write(`
-${import_kleur6.default.dim("\u25CF = active")}
+${import_kleur7.default.dim("\u25CF = active")}
 `);
   });
   ws.command("create").description("Create a new workspace and add it to the registry").argument("<name>", "Human-readable label for the workspace").option("--sample", "Seed the workspace with one sample request", false).action(async (name, opts) => {
@@ -1560,17 +1698,17 @@ ${import_kleur6.default.dim("\u25CF = active")}
         sampleRequest: opts.sample ?? false
       });
       process.stdout.write(
-        `${import_kleur6.default.green("created")} workspace ${import_kleur6.default.cyan(entry3.name)} ${import_kleur6.default.dim(`(${entry3.id})`)}
+        `${import_kleur7.default.green("created")} workspace ${import_kleur7.default.cyan(entry3.name)} ${import_kleur7.default.dim(`(${entry3.id})`)}
   at ${dir}
 `
       );
       if (registry.activeWorkspaceId === entry3.id) {
-        process.stdout.write(`${import_kleur6.default.dim("marked as active")}
+        process.stdout.write(`${import_kleur7.default.dim("marked as active")}
 `);
       }
     } catch (err) {
       process.stderr.write(
-        `${import_kleur6.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
+        `${import_kleur7.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
 `
       );
       process.exit(2);
@@ -1581,8 +1719,8 @@ ${import_kleur6.default.dim("\u25CF = active")}
     const entry3 = (0, import_registry2.findWorkspaceEntry)(registry, selector);
     if (!entry3) {
       process.stderr.write(
-        `${import_kleur6.default.red("error")}: no workspace named "${selector}" in the registry at ${root}.
-${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle workspaces list")} ${import_kleur6.default.dim("to see what is available.")}
+        `${import_kleur7.default.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+${import_kleur7.default.dim("Run")} ${import_kleur7.default.cyan("apicircle workspaces list")} ${import_kleur7.default.dim("to see what is available.")}
 `
       );
       process.exit(2);
@@ -1591,7 +1729,7 @@ ${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle work
     const next = await (0, import_registry2.setActiveWorkspace)(root, entry3.id);
     void next;
     process.stdout.write(
-      `${import_kleur6.default.green("active")} workspace is now ${import_kleur6.default.cyan(entry3.name)} ${import_kleur6.default.dim(`(${entry3.id})`)}
+      `${import_kleur7.default.green("active")} workspace is now ${import_kleur7.default.cyan(entry3.name)} ${import_kleur7.default.dim(`(${entry3.id})`)}
 `
     );
   });
@@ -1604,7 +1742,7 @@ ${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle work
     const entry3 = (0, import_registry2.findWorkspaceEntry)(registry, selector);
     if (!entry3) {
       process.stderr.write(
-        `${import_kleur6.default.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+        `${import_kleur7.default.red("error")}: no workspace named "${selector}" in the registry at ${root}.
 `
       );
       process.exit(2);
@@ -1615,16 +1753,1433 @@ ${import_kleur6.default.dim("Run")} ${import_kleur6.default.cyan("apicircle work
     process.stdout.write(workspaceDirFor2(root, entry3.id) + "\n");
   });
 }
-var import_kleur6, import_registry2;
+var import_kleur7, import_registry2;
 var init_workspaces = __esm({
   "src/commands/workspaces.ts"() {
     "use strict";
-    import_kleur6 = __toESM(require("kleur"), 1);
+    import_kleur7 = __toESM(require("kleur"), 1);
     init_resolveWorkspace();
     import_registry2 = require("@apicircle/core/workspace/registry");
   }
 });
 
+// ../git/src/github/errors.ts
+var GitHubError, MissingScopeError, RateLimitedError, UnauthorizedError, TimeoutError;
+var init_errors = __esm({
+  "../git/src/github/errors.ts"() {
+    "use strict";
+    GitHubError = class extends Error {
+      constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "GitHubError";
+      }
+      status;
+      body;
+    };
+    MissingScopeError = class extends GitHubError {
+      /** Scope strings the API said are missing, e.g. ['pull_request']. */
+      missingScopes;
+      /** Scope strings the token currently grants, parsed from x-oauth-scopes. */
+      grantedScopes;
+      constructor(message, status, missingScopes, grantedScopes) {
+        super(message, status);
+        this.name = "MissingScopeError";
+        this.missingScopes = missingScopes;
+        this.grantedScopes = grantedScopes;
+      }
+    };
+    RateLimitedError = class extends GitHubError {
+      /** Unix timestamp (ms) when the rate-limit window resets. */
+      resetAtMs;
+      constructor(message, status, resetAtMs) {
+        super(message, status);
+        this.name = "RateLimitedError";
+        this.resetAtMs = resetAtMs;
+      }
+    };
+    UnauthorizedError = class extends GitHubError {
+      constructor(message, status) {
+        super(message, status);
+        this.name = "UnauthorizedError";
+      }
+    };
+    TimeoutError = class extends GitHubError {
+      /** Timeout that fired, in ms. Useful for the UI message. */
+      timeoutMs;
+      constructor(message, timeoutMs) {
+        super(message, 0);
+        this.name = "TimeoutError";
+        this.timeoutMs = timeoutMs;
+      }
+    };
+  }
+});
+
+// ../git/src/github/api.ts
+function normalizeMarketplaceRepo(raw) {
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    description: raw.description ?? "",
+    topics: raw.topics ?? [],
+    stargazers: raw.stargazers_count ?? 0,
+    defaultBranch: raw.default_branch ?? "main"
+  };
+}
+function decodeBase64Utf8(b64) {
+  return new TextDecoder("utf-8").decode(decodeBase64Bytes(b64));
+}
+function decodeBase64Bytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function normalizeRepo(raw) {
+  const visibility = raw.visibility ?? (raw.private === true ? "private" : "public");
+  const isPrivate = raw.private ?? visibility !== "public";
+  const pushable = raw.permissions?.push === true || raw.permissions?.admin === true;
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    defaultBranch: raw.default_branch,
+    visibility,
+    isPrivate,
+    pushable
+  };
+}
+function parseScopes(headers) {
+  const raw = headers.get("x-oauth-scopes") ?? "";
+  const granted = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  const acceptedHeader = headers.get("x-accepted-oauth-scopes") ?? "";
+  const acceptedRequired = acceptedHeader.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return acceptedRequired.length > 0 ? { granted, acceptedRequired } : { granted };
+}
+function classifyError(response, body, callerRequiredScopes) {
+  const message = extractMessage(body) ?? response.statusText;
+  const status = response.status;
+  if (status === 401) {
+    return new UnauthorizedError(message || "Unauthorized \u2014 token rejected", status);
+  }
+  if (status === 403) {
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const reset = response.headers.get("x-ratelimit-reset");
+    if (remaining === "0" && reset) {
+      const resetAtMs = Number(reset) * 1e3;
+      const deltaMs = Math.max(0, resetAtMs - Date.now());
+      const totalSeconds = Math.ceil(deltaMs / 1e3);
+      const human = totalSeconds < 60 ? `${totalSeconds}s` : totalSeconds < 3600 ? `${Math.ceil(totalSeconds / 60)} min` : `${Math.ceil(totalSeconds / 3600)} h`;
+      return new RateLimitedError(
+        `GitHub rate limit reached. Resets in ${human} (at ${new Date(resetAtMs).toISOString()}).`,
+        status,
+        resetAtMs
+      );
+    }
+    const accepted = (response.headers.get("x-accepted-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const granted = (response.headers.get("x-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const missing = accepted.length > 0 ? accepted.filter((s) => !granted.includes(s)) : callerRequiredScopes.filter((s) => !granted.includes(s));
+    if (missing.length > 0) {
+      return new MissingScopeError(
+        `GitHub denied this action: missing scopes ${missing.join(", ")}.`,
+        status,
+        missing,
+        granted
+      );
+    }
+  }
+  return new GitHubError(message || "GitHub API call failed", status, body);
+}
+function extractMessage(body) {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string") return m;
+  }
+  return null;
+}
+async function safeReadJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+var API_BASE, LOGIN_BASE, DEFAULT_TIMEOUT_MS, GitHubClient;
+var init_api = __esm({
+  "../git/src/github/api.ts"() {
+    "use strict";
+    init_errors();
+    API_BASE = "https://api.github.com";
+    LOGIN_BASE = "https://github.com";
+    DEFAULT_TIMEOUT_MS = 15e3;
+    GitHubClient = class {
+      baseUrl;
+      loginBaseUrl;
+      fetchImpl;
+      timeoutMs;
+      constructor(opts = {}) {
+        this.baseUrl = opts.baseUrl ?? API_BASE;
+        this.loginBaseUrl = (opts.loginBaseUrl ?? LOGIN_BASE).replace(/\/$/, "");
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      }
+      /**
+       * Fetch the authenticated user. Doubles as a "verify token" probe — used
+       * by the Secret Vault Sessions tab to refresh the granted-scopes list.
+       */
+      async getViewer(token, opts = {}) {
+        const { json, response } = await this.call(token, "/user", opts);
+        return {
+          viewer: {
+            login: json.login,
+            id: json.id,
+            name: json.name ?? null,
+            avatarUrl: json.avatar_url ?? null
+          },
+          scopes: parseScopes(response.headers)
+        };
+      }
+      /**
+       * List repositories the authenticated user can access. Used by the repo
+       * picker. Capped at 100 sorted by recent push; users with thousands of
+       * repos can paginate later.
+       */
+      async listAccessibleRepos(token, opts = {}) {
+        const { json } = await this.call(
+          token,
+          "/user/repos?per_page=100&sort=pushed&affiliation=owner,collaborator,organization_member",
+          opts
+        );
+        return json.map(normalizeRepo);
+      }
+      /**
+       * Fetch a specific repo. Validates the user-supplied owner/name pair
+       * exists + is accessible, and exposes the default branch.
+       */
+      async getRepo(token, owner, name, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+          opts
+        );
+        return normalizeRepo(json);
+      }
+      /**
+       * Read the head SHA of a branch. Used to seed a new working branch from
+       * main before any edits land.
+       */
+      async getBranchHead(token, owner, name, branch, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches/${encodeURIComponent(branch)}`,
+          opts
+        );
+        return { name: json.name, commitSha: json.commit.sha };
+      }
+      /**
+       * List branches on a repo. Used by the Link Workspace repo-browser to
+       * populate the branch dropdown after the user picks a repo. Capped at
+       * 100 (GitHub's max page size); repos with more branches paginate.
+       */
+      async listBranches(token, owner, name, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches?per_page=100`,
+          opts
+        );
+        return json.map((b) => ({ name: b.name, commitSha: b.commit.sha }));
+      }
+      /**
+       * Create a new branch ref pointing at `sha`. The auto-branch flow calls
+       * this with the head SHA from `getBranchHead(main)`.
+       *
+       * GitHub returns 422 with "Reference already exists" when the branch
+       * already exists; that surfaces as a GitHubError(422) so the UI can
+       * prompt for a different name.
+       */
+      async createBranch(token, owner, name, branchName, sha, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs`,
+          {
+            ...opts,
+            method: "POST",
+            body: { ref: `refs/heads/${branchName}`, sha },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { name: branchName, commitSha: json.object.sha };
+      }
+      /**
+       * Read a branch ref's current commit SHA. Used at the start of push-to-
+       * save to find the parent commit before building the new tree.
+       */
+      async getRef(token, owner, name, branch, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(branch)}`,
+          opts
+        );
+        return { ref: json.ref, sha: json.object.sha };
+      }
+      /**
+       * Read a commit's tree SHA. Used so the new tree can be built `base_tree`
+       * — every path we don't override is inherited from the parent.
+       */
+      async getCommit(token, owner, name, sha, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits/${encodeURIComponent(sha)}`,
+          opts
+        );
+        return {
+          sha: json.sha,
+          treeSha: json.tree.sha,
+          message: json.message
+        };
+      }
+      /**
+       * Upload a blob to the repo and return its SHA. Used by push-to-save
+       * (P4.3b) for binary attachments — text files go straight into a tree
+       * entry's `content`, but binary bytes have to go through a blob first.
+       *
+       * `content` is base64 when `encoding === 'base64'`. GitHub stores blobs
+       * deduplicated by their git-sha1 (not our sha256), so re-uploading the
+       * same bytes is cheap on their side; we save a roundtrip locally by
+       * tracking lastPushedBlobSha per slot in a future revision.
+       */
+      async createBlob(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/blobs`,
+          {
+            ...opts,
+            method: "POST",
+            body: { content: args.content, encoding: args.encoding },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha, size: json.size ?? 0 };
+      }
+      /**
+       * Build a new tree from `entries`, layered over `baseTreeSha`. Entries
+       * with `content` are inlined (text path); entries with a pre-uploaded
+       * `sha` reference an existing blob (binary path — used by attachments).
+       */
+      async createTree(token, owner, name, args, opts = {}) {
+        const tree = args.entries.map((e) => ({
+          path: e.path,
+          mode: e.mode ?? "100644",
+          type: e.type ?? "blob",
+          ...e.content !== void 0 ? { content: e.content } : {},
+          ...e.sha !== void 0 ? { sha: e.sha } : {}
+        }));
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/trees`,
+          {
+            ...opts,
+            method: "POST",
+            body: { base_tree: args.baseTreeSha, tree },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha };
+      }
+      /**
+       * Create a new commit object pointing at the given tree, with the given
+       * parents. Returns the new commit's SHA + the tree it points at.
+       */
+      async createCommit(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits`,
+          {
+            ...opts,
+            method: "POST",
+            body: {
+              message: args.message,
+              tree: args.treeSha,
+              parents: args.parents
+            },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha, treeSha: json.tree.sha };
+      }
+      /**
+       * Fast-forward a branch ref to a new commit SHA. Pass `force: true` to
+       * skip the FF check (we don't — push-to-save is always FF over the ref
+       * we just read with getRef()).
+       */
+      async updateRef(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(args.branch)}`,
+          {
+            ...opts,
+            method: "PATCH",
+            body: { sha: args.sha, force: args.force ?? false },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { ref: json.ref, sha: json.object.sha };
+      }
+      /**
+       * Search GitHub for public API Circle workspaces. Appends
+       * `topic:apicircle` to the user-supplied query so only repos carrying
+       * the `apicircle` topic — the topic the Releases & Topics dialog
+       * locks onto every workspace repo — surface in results. GitHub
+       * matches the bare query against repository name, description, and
+       * topics, so category words like `payments` narrow the marketplace by
+       * topic. An empty query lists every public API Circle workspace. Top
+       * 30 results. Token is optional — anonymous browsing is supported
+       * (lower GitHub rate limits apply); pass a PAT when one is available
+       * to lift them. `sort` controls ordering: omit for GitHub's
+       * best-match relevance, or pass `'stars'` / `'updated'`.
+       */
+      async searchMarketplaceRepos(token, query, opts = {}) {
+        const { sort, ...callOpts } = opts;
+        const fullQuery = `${query.trim()} topic:apicircle`.trim();
+        const sortParam = sort ? `&sort=${sort}&order=desc` : "";
+        const path8 = `/search/repositories?q=${encodeURIComponent(fullQuery)}&per_page=30${sortParam}`;
+        const { json } = await this.call(token, path8, callOpts);
+        const items = json.items ?? [];
+        return items.map(normalizeMarketplaceRepo);
+      }
+      /**
+       * Start GitHub's OAuth Device Flow. Returns a user-facing code the
+       * user types into github.com/login/device + a device_code the app
+       * polls with. Pure browser-safe: no client_secret involved (device
+       * flow is the only OAuth path GitHub supports for public clients).
+       *
+       * Requires the OAuth App to have "Enable Device Flow" turned on in
+       * its GitHub settings — surface 400 with `not_supported` to the user
+       * if the App owner hasn't done that yet.
+       */
+      async startDeviceFlow(clientId, scope, opts = {}) {
+        const url = `${this.loginBaseUrl}/login/device/code`;
+        const response = await this.fetchImpl(url, {
+          method: "POST",
+          headers: { Accept: "application/json", "Content-Type": "application/json" },
+          body: JSON.stringify({ client_id: clientId, scope }),
+          signal: opts.signal
+        });
+        if (!response.ok) {
+          throw new GitHubError(
+            `Device-flow start failed: HTTP ${response.status}`,
+            response.status,
+            {}
+          );
+        }
+        const json = await response.json();
+        if (json.error) {
+          throw new GitHubError(json.error_description ?? json.error, 400, json);
+        }
+        return {
+          deviceCode: json.device_code,
+          userCode: json.user_code,
+          verificationUri: json.verification_uri,
+          expiresIn: json.expires_in,
+          interval: json.interval
+        };
+      }
+      /**
+       * Poll for the access token after the user has authorized the device
+       * code. GitHub returns `authorization_pending` until the user
+       * completes the flow, `slow_down` if we polled too fast, then a real
+       * token. Caller wraps this in a polling loop bounded by `expiresIn`.
+       */
+      async pollDeviceToken(clientId, deviceCode, opts = {}) {
+        const url = `${this.loginBaseUrl}/login/oauth/access_token`;
+        const response = await this.fetchImpl(url, {
+          method: "POST",
+          headers: { Accept: "application/json", "Content-Type": "application/json" },
+          body: JSON.stringify({
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+          }),
+          signal: opts.signal
+        });
+        const json = await response.json();
+        if (json.access_token) {
+          return {
+            kind: "granted",
+            accessToken: json.access_token,
+            tokenType: json.token_type ?? "bearer",
+            scope: json.scope ?? ""
+          };
+        }
+        if (json.error === "authorization_pending") return { kind: "pending", slowDown: false };
+        if (json.error === "slow_down") return { kind: "pending", slowDown: true };
+        if (json.error === "expired_token") return { kind: "expired" };
+        if (json.error === "access_denied")
+          return { kind: "denied", reason: json.error_description ?? "User denied authorization" };
+        throw new GitHubError(
+          json.error_description ?? json.error ?? "Device-token poll failed",
+          response.status,
+          json
+        );
+      }
+      /**
+       * Create a lightweight Git tag (a ref under `refs/tags/<name>`) on the
+       * given commit SHA. Used by the publish-release flow when the user
+       * opts in to "Create Git tag v<x.y.z>". Returns the resolved ref.
+       *
+       * GitHub returns 422 with "Reference already exists" when the tag is
+       * a duplicate; that surfaces as a GitHubError(422) so the UI can warn
+       * the user without ever overwriting an existing tag.
+       */
+      async createTag(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs`,
+          {
+            ...opts,
+            method: "POST",
+            body: { ref: `refs/tags/${args.tagName}`, sha: args.sha },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { ref: json.ref, sha: json.object.sha };
+      }
+      /**
+       * Compare two commits. Returns the relationship classification GitHub
+       * gives us: `ahead` (head is descendant of base), `behind` (base is
+       * descendant of head), `identical`, or `diverged` (the two histories
+       * share a base but neither contains the other — typical of a force-push
+       * that rewrote history under us).
+       *
+       * Used by the refresh path so we never silently 3-way-merge across a
+       * history rewrite — divergence steers the user through an explicit
+       * "history rewritten" modal instead of corrupting local state.
+       */
+      async compareCommits(token, owner, name, base, head, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/compare/${encodeURIComponent(
+            base
+          )}...${encodeURIComponent(head)}`,
+          { ...opts, requiredScopes: ["repo"] }
+        );
+        return {
+          status: json.status,
+          aheadBy: json.ahead_by,
+          behindBy: json.behind_by
+        };
+      }
+      /**
+       * Is `ancestor` reachable from `descendant`? Thin wrapper around
+       * `compareCommits` — "ahead" or "identical" means yes; "behind" or
+       * "diverged" means the histories don't fit, so the answer is no.
+       */
+      async isAncestor(token, owner, name, ancestor, descendant, opts = {}) {
+        if (ancestor === descendant) return true;
+        const cmp = await this.compareCommits(token, owner, name, ancestor, descendant, opts);
+        return cmp.status === "ahead" || cmp.status === "identical";
+      }
+      /**
+       * Create a GitHub Release pointing at an existing tag. Used by the
+       * publish-release flow when the user opts in to "Create GitHub
+       * Release". Returns the release's HTML URL so the UI can show a
+       * "Released — view on GitHub" link.
+       *
+       * Pass `prerelease: true` for semver pre-release identifiers (e.g.
+       * `1.0.0-rc.1`); GitHub's Releases UI flags those distinctly.
+       */
+      async createRelease(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(token, `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/releases`, {
+          ...opts,
+          method: "POST",
+          body: {
+            tag_name: args.tagName,
+            name: args.releaseName ?? args.tagName,
+            body: args.body ?? "",
+            draft: args.draft ?? false,
+            prerelease: args.prerelease ?? false
+          },
+          requiredScopes: ["repo"]
+        });
+        return { id: json.id, htmlUrl: json.html_url, tagName: json.tag_name };
+      }
+      /**
+       * Read a tag ref's current commit SHA. Used by the Release & topics
+       * modal to detect whether a tag with the chosen name already exists
+       * (so the UI can surface an "Override existing tag" toggle instead of
+       * silently 422'ing through createTag).
+       *
+       * Returns `null` when the tag doesn't exist (404). Other failures
+       * surface as typed errors.
+       */
+      async getTagSha(token, owner, name, tagName, opts = {}) {
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/tags/${encodeURIComponent(tagName)}`,
+            opts
+          );
+          return json.object.sha;
+        } catch (err) {
+          if (err instanceof GitHubError && err.status === 404) return null;
+          throw err;
+        }
+      }
+      /**
+       * Delete a ref. Used to support the "Override existing tag" path on
+       * the Release & topics modal — we delete the existing tag ref, then
+       * createTag against the new SHA. (GitHub doesn't have a single
+       * "force-update tag" endpoint via the simple refs API.)
+       *
+       * `ref` is the bare suffix, e.g. `tags/v1.0.0` or `heads/feature-x`.
+       */
+      async deleteRef(token, owner, name, ref, opts = {}) {
+        await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/${ref.split("/").map(encodeURIComponent).join("/")}`,
+          {
+            ...opts,
+            method: "DELETE",
+            requiredScopes: ["repo"]
+          }
+        );
+      }
+      /**
+       * Read the repo's current topic list. Topics drive marketplace
+       * discoverability — public API Circle workspaces include `apicircle`
+       * plus user-chosen category topics.
+       *
+       * Note: GitHub's topics API uses a custom Accept header, but we treat
+       * that as transport detail; the `application/vnd.github.mercy-preview+json`
+       * preview is now stable so the default Accept works.
+       */
+      async listRepoTopics(token, owner, name, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/topics`,
+          opts
+        );
+        return Array.isArray(json.names) ? json.names : [];
+      }
+      /**
+       * Replace the repo's full topic list. GitHub's `PUT /topics` endpoint
+       * is a full replace (not a merge), so the caller must pass the
+       * complete desired list. Caps at 20 topics; each must match
+       * `^[a-z0-9][a-z0-9-]*$` and be ≤ 50 chars (GitHub enforces this with
+       * a 422). Returns the persisted list.
+       */
+      async setRepoTopics(token, owner, name, topics, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/topics`,
+          {
+            ...opts,
+            method: "PUT",
+            body: { names: topics },
+            requiredScopes: ["repo"]
+          }
+        );
+        return Array.isArray(json.names) ? json.names : [];
+      }
+      /**
+       * Fetch a single file's contents from a branch / commit. Returns
+       * `null` when GitHub answers 404 (file simply doesn't exist on that
+       * ref — the common case for the very first pull). Other failures
+       * surface as the usual typed errors.
+       *
+       * Used by the refresh flow to read remote `workspace.json` so the
+       * 3-way diff can compare it against the local doc.
+       */
+      async getContents(token, owner, name, path8, ref, opts = {}) {
+        const query = `?ref=${encodeURIComponent(ref)}`;
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path8.split("/").map(encodeURIComponent).join("/")}${query}`,
+            opts
+          );
+          if (Array.isArray(json) || json.type !== "file") {
+            throw new GitHubError(`Path ${path8} is not a file`, 422, json);
+          }
+          const cleaned = json.content.replace(/\n/g, "");
+          const decoded = decodeBase64Utf8(cleaned);
+          return { content: decoded, sha: json.sha, path: json.path, size: json.size };
+        } catch (err) {
+          if (err instanceof GitHubError && err.status === 404) return null;
+          throw err;
+        }
+      }
+      /**
+       * Create or update a file via the Contents API. The killer feature here
+       * vs. the git-data flow (createBlob → createTree → createCommit →
+       * updateRef) is that this works on **truly empty repos**: GitHub's git
+       * database isn't initialized until the first commit lands, so all the
+       * `/git/*` endpoints reject with 409 "Git Repository is empty" — but
+       * `PUT /contents/{path}` atomically initializes the database with a
+       * single-file commit on the supplied branch (defaulting to the repo's
+       * default branch).
+       *
+       * Used by the seed-initial-commit flow to bootstrap a freshly-created
+       * empty repo with a scaffold `workspace.json`.
+       *
+       * `contentBase64` must already be base64-encoded — caller chooses the
+       * encoder (TextEncoder for UTF-8 strings, raw bytes for binaries).
+       */
+      async putContents(token, owner, name, path8, args, opts = {}) {
+        const body = {
+          message: args.message,
+          content: args.contentBase64
+        };
+        if (args.branch) body.branch = args.branch;
+        if (args.sha) body.sha = args.sha;
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path8.split("/").map(encodeURIComponent).join("/")}`,
+          {
+            ...opts,
+            method: "PUT",
+            body,
+            requiredScopes: ["repo"]
+          }
+        );
+        return { commitSha: json.commit.sha, contentSha: json.content.sha };
+      }
+      /**
+       * Same as `getContents` but returns the raw bytes instead of UTF-8
+       * decoding the file. Used by the refresh flow to pull
+       * `.apicircle/workspace-<id>/attachments/<slotId>` blobs into local IDB without
+       * mangling binary data through TextDecoder.
+       */
+      async getBinaryContents(token, owner, name, path8, ref, opts = {}) {
+        const query = `?ref=${encodeURIComponent(ref)}`;
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path8.split("/").map(encodeURIComponent).join("/")}${query}`,
+            opts
+          );
+          if (Array.isArray(json) || json.type !== "file") {
+            throw new GitHubError(`Path ${path8} is not a file`, 422, json);
+          }
+          const cleaned = json.content.replace(/\n/g, "");
+          const bytes = decodeBase64Bytes(cleaned);
+          return { bytes, sha: json.sha, path: json.path, size: json.size };
+        } catch (err) {
+          if (err instanceof GitHubError && err.status === 404) return null;
+          throw err;
+        }
+      }
+      /**
+       * Open a pull request from `head` (the working branch) into `base` (the
+       * repo's default branch). PR creation needs the `pull_request` scope on
+       * top of `repo`; missing-scope errors flow through MissingScopeError so
+       * the UI can prompt the user to update the token without losing branch
+       * state (Plan §3.7).
+       *
+       * GitHub returns 422 when:
+       *   - head/base are equal (nothing to merge)
+       *   - a PR already exists between this head and base
+       *   - the head branch doesn't exist
+       * All three surface as a plain GitHubError(422); the UI message is
+       * picked up from response.body.message.
+       */
+      /**
+       * Fetch a single pull request by number. Used by the refresh flow to
+       * detect whether a previously-opened PR has been merged on GitHub —
+       * `merged: true` is what triggers the working-branch retirement path.
+       *
+       * Returns `null` on 404 (PR was deleted or never existed at this number);
+       * other failures surface as the usual typed errors.
+       */
+      async getPullRequest(token, owner, name, number, opts = {}) {
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls/${number}`,
+            opts
+          );
+          return {
+            number: json.number,
+            htmlUrl: json.html_url,
+            state: json.state,
+            merged: json.merged === true
+          };
+        } catch (err) {
+          if (err instanceof GitHubError && err.status === 404) return null;
+          throw err;
+        }
+      }
+      /**
+       * List pull requests on a repo. The capability-probe path uses this with
+       * `perPage: 1` to determine whether the token can read PRs (and, by
+       * extension on classic PATs, whether it can also create them).
+       *
+       * Caller declares `requiredScopes` to surface a `MissingScopeError` on
+       * 403, so the capability probe can recognise the missing-scope case
+       * cleanly vs. transient 5xx/network failures.
+       */
+      async listPullRequests(token, owner, name, args = {}, opts = {}) {
+        const params = new URLSearchParams();
+        params.set("per_page", String(args.perPage ?? 30));
+        if (args.state) params.set("state", args.state);
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls?${params.toString()}`,
+          {
+            ...opts,
+            requiredScopes: ["repo", "pull_request"]
+          }
+        );
+        return json.map((pr) => ({
+          number: pr.number,
+          htmlUrl: pr.html_url,
+          state: pr.state,
+          title: pr.title
+        }));
+      }
+      async createPullRequest(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`,
+          {
+            ...opts,
+            method: "POST",
+            body: {
+              title: args.title,
+              body: args.body,
+              head: args.head,
+              base: args.base,
+              draft: args.draft ?? false
+            },
+            requiredScopes: ["repo", "pull_request"]
+          }
+        );
+        return {
+          number: json.number,
+          htmlUrl: json.html_url,
+          state: json.state,
+          title: json.title
+        };
+      }
+      // --- low-level call ----------------------------------------------------
+      async call(token, path8, opts = {}) {
+        const url = path8.startsWith("http") ? path8 : `${this.baseUrl}${path8}`;
+        const controller = new AbortController();
+        const onExternalAbort = () => controller.abort(opts.signal.reason);
+        if (opts.signal) {
+          if (opts.signal.aborted) controller.abort(opts.signal.reason);
+          else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        const timeoutHandle = setTimeout(
+          () => controller.abort(new Error(`GitHub request timed out after ${this.timeoutMs}ms`)),
+          this.timeoutMs
+        );
+        let response;
+        let timedOut = false;
+        try {
+          response = await this.fetchImpl(url, {
+            method: opts.method ?? "GET",
+            headers: {
+              Accept: "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+              ...token ? { Authorization: `Bearer ${token}` } : {},
+              ...opts.body !== void 0 ? { "Content-Type": "application/json" } : {}
+            },
+            cache: "no-store",
+            body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+            signal: controller.signal
+          });
+        } catch (err) {
+          const isAbort = err instanceof DOMException && err.name === "AbortError";
+          const callerAborted = opts.signal?.aborted ?? false;
+          if (isAbort && !callerAborted) {
+            timedOut = true;
+            throw new TimeoutError(
+              `GitHub request timed out after ${this.timeoutMs}ms. The write may have partially landed \u2014 refresh before retrying.`,
+              this.timeoutMs
+            );
+          }
+          throw err;
+        } finally {
+          clearTimeout(timeoutHandle);
+          if (opts.signal) opts.signal.removeEventListener("abort", onExternalAbort);
+          void timedOut;
+        }
+        if (response.ok) {
+          if (response.status === 204 || response.status === 205) {
+            return { json: {}, response };
+          }
+          const json = await response.json();
+          return { json, response };
+        }
+        const errBody = await safeReadJson(response);
+        throw classifyError(response, errBody, opts.requiredScopes ?? []);
+      }
+    };
+  }
+});
+
+// ../git/src/index.ts
+var init_src = __esm({
+  "../git/src/index.ts"() {
+    "use strict";
+    init_api();
+    init_errors();
+  }
+});
+
+// src/commands/linked.ts
+function resolveToken(opts) {
+  return (opts.token ?? process.env.GITHUB_TOKEN ?? "").trim();
+}
+async function resolveDir2(opts) {
+  try {
+    const resolved = await resolveWorkspace({
+      name: opts.workspaceName,
+      path: opts.workspacePath,
+      expectExists: false
+    });
+    if (resolved.fromRegistry) {
+      process.stderr.write(
+        `${import_kleur8.default.dim("workspace")}: ${import_kleur8.default.cyan(resolved.name ?? resolved.id ?? "")} ${import_kleur8.default.dim(`(${resolved.dir})`)}
+`
+      );
+    }
+    return resolved.dir;
+  } catch (err) {
+    if (err instanceof WorkspaceResolutionError) {
+      process.stderr.write(`${import_kleur8.default.red("error")}: ${err.message}
+`);
+      process.exit(2);
+    }
+    throw err;
+  }
+}
+function registerLinkedCommand(program) {
+  const linked = program.command("linked").description("Manage linked workspaces (the workspaces this one consumes).");
+  linked.command("list").description("List linked workspaces in the active workspace.").option("--workspace-name <name-or-id>", "Workspace name or id.").option("-w, --workspace-path <dir>", "Workspace folder path.").action(async (opts) => {
+    const dir = await resolveDir2(opts);
+    const state = await ensureWorkspace(dir);
+    const links = Object.values(state.synced.linkedWorkspaces);
+    if (links.length === 0) {
+      process.stdout.write(`${import_kleur8.default.dim("No linked workspaces.")}
+`);
+      return;
+    }
+    for (const l of links) {
+      const pin = l.pinnedVersion ? `v${l.pinnedVersion}` : "unpinned";
+      const ledger = state.synced.releases.perLink[l.id];
+      const cur = ledger?.currentVersion ? ` \xB7 cached current v${ledger.currentVersion}` : "";
+      process.stdout.write(
+        `${import_kleur8.default.cyan(l.id)}  ${import_kleur8.default.bold(l.name)}  ${import_kleur8.default.dim(`${l.kind} \xB7 ${l.source.repoFullName}@${l.source.branch} \xB7 ${pin}${cur}`)}
+`
+      );
+    }
+  });
+  linked.command("link <repo>").description("Link a source workspace repo (owner/name).").option("-b, --branch <branch>", "Source branch.", "main").option("--pinned-version <version>", "Pin a specific version (defaults to source current).").option("--kind <kind>", "private | public", "private").option("--workspace-name <name-or-id>", "Workspace name or id.").option("-w, --workspace-path <dir>", "Workspace folder path.").option("--token <token>", "GitHub token (or set GITHUB_TOKEN).").action(
+    async (repo, opts) => {
+      if (!repo.includes("/")) {
+        process.stderr.write(`${import_kleur8.default.red("error")}: repo must be owner/name
+`);
+        process.exit(2);
+      }
+      if (opts.kind !== "public" && opts.kind !== "private") {
+        process.stderr.write(`${import_kleur8.default.red("error")}: --kind must be private or public
+`);
+        process.exit(2);
+      }
+      const token = resolveToken(opts);
+      if (opts.kind === "private" && !token) {
+        process.stderr.write(
+          `${import_kleur8.default.red("error")}: a token is required for private repos (--token or GITHUB_TOKEN)
+`
+        );
+        process.exit(2);
+      }
+      const dir = await resolveDir2(opts);
+      const state = await ensureWorkspace(dir);
+      const dup = Object.values(state.synced.linkedWorkspaces).find(
+        (l) => l.source.repoFullName === repo && l.source.branch === opts.branch
+      );
+      if (dup) {
+        process.stderr.write(
+          `${import_kleur8.default.red("error")}: already linked to ${repo}@${opts.branch} (${dup.id})
+`
+        );
+        process.exit(2);
+      }
+      const [owner, name] = repo.split("/", 2);
+      const client = new GitHubClient();
+      const result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+        const f = await client.getContents(token, owner, name, p, opts.branch);
+        return f?.content ?? null;
+      });
+      if ("error" in result) {
+        process.stderr.write(`${import_kleur8.default.red("error")}: ${repo}@${opts.branch}: ${result.error}
+`);
+        process.exit(2);
+      }
+      const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+      const ledger = (0, import_core5.ledgerFromProbe)(probe);
+      const link = {
+        id: (0, import_shared5.generateId)(),
+        kind: opts.kind,
+        name: repo,
+        sourceWorkspaceId: result.workspaceId,
+        source: {
+          provider: "github",
+          repoFullName: repo,
+          branch: opts.branch,
+          sessionMode: "workspace"
+        },
+        scope: ["collections", "environments"],
+        pinnedVersion: opts.pinnedVersion ?? ledger.currentVersion,
+        updatePolicy: "manual",
+        linkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        requiredSecretKeyIds: probe.secretKeys ? Object.keys(probe.secretKeys) : []
+      };
+      const snapshot = (0, import_core5.buildLinkedSnapshot)(probe, link) ?? void 0;
+      const out = (0, import_core5.applyMutation)(state, {
+        kind: "linkedWorkspace.upsert",
+        link,
+        ledger,
+        ...snapshot ? { snapshot } : {}
+      });
+      await (0, import_file_backed6.saveToFile)(dir, out.next);
+      process.stdout.write(
+        `${import_kleur8.default.green("linked")} ${import_kleur8.default.bold(repo)} ${import_kleur8.default.dim(`(id ${link.id}, ${link.pinnedVersion ? `v${link.pinnedVersion}` : "unpinned"})`)}
+`
+      );
+    }
+  );
+  linked.command("refresh <id>").description("Re-pull a linked workspace's cached release ledger.").option("--workspace-name <name-or-id>", "Workspace name or id.").option("-w, --workspace-path <dir>", "Workspace folder path.").option("--token <token>", "GitHub token (or set GITHUB_TOKEN).").action(async (id, opts) => {
+    const dir = await resolveDir2(opts);
+    const state = await ensureWorkspace(dir);
+    const link = state.synced.linkedWorkspaces[id];
+    if (!link) {
+      process.stderr.write(`${import_kleur8.default.red("error")}: linked workspace ${id} not found
+`);
+      process.exit(2);
+    }
+    const token = resolveToken(opts);
+    if (link.kind === "private" && !token) {
+      process.stderr.write(
+        `${import_kleur8.default.red("error")}: a token is required for private links (--token or GITHUB_TOKEN)
+`
+      );
+      process.exit(2);
+    }
+    const [owner, name] = link.source.repoFullName.split("/", 2);
+    const client = new GitHubClient();
+    const result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+      const f = await client.getContents(token, owner, name, p, link.source.branch);
+      return f?.content ?? null;
+    });
+    if ("error" in result) {
+      process.stderr.write(
+        `${import_kleur8.default.red("error")}: ${link.source.repoFullName}@${link.source.branch}: ${result.error}
+`
+      );
+      process.exit(2);
+    }
+    const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+    const ledger = (0, import_core5.ledgerFromProbe)(probe);
+    const needsSnapshot = !state.local.linkedCollections[id];
+    const snapshot = needsSnapshot ? (0, import_core5.buildLinkedSnapshot)(probe, link) ?? void 0 : void 0;
+    const out = (0, import_core5.applyMutation)(state, {
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    await (0, import_file_backed6.saveToFile)(dir, out.next);
+    process.stdout.write(
+      `${import_kleur8.default.green("refreshed")} ${import_kleur8.default.bold(link.name)} ${import_kleur8.default.dim(`(${ledger.versions.length} version(s), current ${ledger.currentVersion ?? "none"})`)}
+`
+    );
+  });
+  linked.command("unlink <id>").description("Unlink a workspace (drops cached ledger + overrides + snapshot).").option("--workspace-name <name-or-id>", "Workspace name or id.").option("-w, --workspace-path <dir>", "Workspace folder path.").action(async (id, opts) => {
+    const dir = await resolveDir2(opts);
+    const state = await ensureWorkspace(dir);
+    if (!state.synced.linkedWorkspaces[id]) {
+      process.stderr.write(`${import_kleur8.default.red("error")}: linked workspace ${id} not found
+`);
+      process.exit(2);
+    }
+    const out = (0, import_core5.applyMutation)(state, { kind: "linkedWorkspace.remove", id });
+    await (0, import_file_backed6.saveToFile)(dir, out.next);
+    process.stdout.write(`${import_kleur8.default.green("unlinked")} ${import_kleur8.default.dim(id)}
+`);
+  });
+}
+var import_kleur8, import_core5, import_file_backed6, import_shared5;
+var init_linked = __esm({
+  "src/commands/linked.ts"() {
+    "use strict";
+    import_kleur8 = __toESM(require("kleur"), 1);
+    import_core5 = require("@apicircle/core");
+    import_file_backed6 = require("@apicircle/core/workspace/file-backed");
+    import_shared5 = require("@apicircle/shared");
+    init_src();
+    init_loadWorkspace();
+    init_resolveWorkspace();
+  }
+});
+
+// src/commands/release.ts
+function resolveToken2(opts) {
+  return (opts.token ?? process.env.GITHUB_TOKEN ?? "").trim();
+}
+function parseRepo(repo) {
+  if (!repo.includes("/")) return null;
+  const [owner, name] = repo.split("/", 2);
+  return { owner, name };
+}
+function registerReleaseCommand(program) {
+  const release = program.command("release").description("Tag releases and edit topics on the workspace's GitHub repo.");
+  release.command("tag <repo> <version>").description("Create a v<version> tag on the default branch HEAD.").option("-r, --release", "Also create a GitHub Release for the tag.").option("-n, --notes <notes>", "Release notes (used when --release is set).", "").option("--override", "Replace an existing tag of the same name.").option("--token <token>", "GitHub token (or set GITHUB_TOKEN).").action(async (repo, version, opts) => {
+    const parsed = parseRepo(repo);
+    if (!parsed) {
+      process.stderr.write(`${import_kleur9.default.red("error")}: repo must be owner/name
+`);
+      process.exit(2);
+    }
+    const token = resolveToken2(opts);
+    if (!token) {
+      process.stderr.write(
+        `${import_kleur9.default.red("error")}: a token is required (--token or GITHUB_TOKEN)
+`
+      );
+      process.exit(2);
+    }
+    const tagName = `v${version.replace(/^v/, "")}`;
+    const client = new GitHubClient();
+    try {
+      const meta = await client.getRepo(token, parsed.owner, parsed.name);
+      const ref = await client.getRef(token, parsed.owner, parsed.name, meta.defaultBranch);
+      const existing = await client.getTagSha(token, parsed.owner, parsed.name, tagName);
+      if (existing !== null) {
+        if (!opts.override) {
+          process.stderr.write(
+            `${import_kleur9.default.red("error")}: tag ${tagName} already exists at ${existing.slice(0, 7)} \u2014 pass --override to replace
+`
+          );
+          process.exit(2);
+        }
+        await client.deleteRef(token, parsed.owner, parsed.name, `tags/${tagName}`);
+      }
+      await client.createTag(token, parsed.owner, parsed.name, { tagName, sha: ref.sha });
+      process.stdout.write(
+        `${import_kleur9.default.green("tagged")} ${import_kleur9.default.bold(tagName)} ${import_kleur9.default.dim(`on ${meta.defaultBranch} (${ref.sha.slice(0, 7)})`)}
+`
+      );
+      if (opts.release) {
+        const r = await client.createRelease(token, parsed.owner, parsed.name, {
+          tagName,
+          releaseName: tagName,
+          body: opts.notes ?? ""
+        });
+        process.stdout.write(`${import_kleur9.default.green("release")} ${import_kleur9.default.dim(r.htmlUrl)}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `${import_kleur9.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(2);
+    }
+  });
+  release.command("topics <repo>").description("List or set the repo's topics ('apicircle' is always kept).").option("--set <topics>", "Comma-separated topics to set (replaces existing).").option("--token <token>", "GitHub token (or set GITHUB_TOKEN).").action(async (repo, opts) => {
+    const parsed = parseRepo(repo);
+    if (!parsed) {
+      process.stderr.write(`${import_kleur9.default.red("error")}: repo must be owner/name
+`);
+      process.exit(2);
+    }
+    const token = resolveToken2(opts);
+    if (!token) {
+      process.stderr.write(
+        `${import_kleur9.default.red("error")}: a token is required (--token or GITHUB_TOKEN)
+`
+      );
+      process.exit(2);
+    }
+    const client = new GitHubClient();
+    try {
+      if (opts.set === void 0) {
+        const list = await client.listRepoTopics(token, parsed.owner, parsed.name);
+        if (list.length === 0) {
+          process.stdout.write(`${import_kleur9.default.dim("(no topics)")}
+`);
+        } else {
+          for (const t of list) process.stdout.write(`${t}
+`);
+        }
+        return;
+      }
+      const normalized = Array.from(
+        /* @__PURE__ */ new Set([
+          "apicircle",
+          ...opts.set.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean)
+        ])
+      );
+      for (const t of normalized) {
+        if (!TOPIC_RE.test(t)) {
+          process.stderr.write(`${import_kleur9.default.red("error")}: invalid topic "${t}"
+`);
+          process.exit(2);
+        }
+        if (t.length > 50) {
+          process.stderr.write(`${import_kleur9.default.red("error")}: topic "${t}" exceeds 50 characters
+`);
+          process.exit(2);
+        }
+      }
+      if (normalized.length > 20) {
+        process.stderr.write(`${import_kleur9.default.red("error")}: GitHub allows at most 20 topics
+`);
+        process.exit(2);
+      }
+      const saved = await client.setRepoTopics(token, parsed.owner, parsed.name, normalized);
+      process.stdout.write(`${import_kleur9.default.green("topics set")} ${import_kleur9.default.dim(`(${saved.length})`)}
+`);
+      for (const t of saved) process.stdout.write(`  ${t}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `${import_kleur9.default.red("error")}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(2);
+    }
+  });
+}
+var import_kleur9, TOPIC_RE;
+var init_release = __esm({
+  "src/commands/release.ts"() {
+    "use strict";
+    import_kleur9 = __toESM(require("kleur"), 1);
+    init_src();
+    TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+  }
+});
+
+// src/commands/folder.ts
+async function openWorkspace(opts) {
+  let dir;
+  try {
+    const resolved = await resolveWorkspace({
+      name: opts.workspaceName,
+      path: opts.workspacePath,
+      expectExists: true
+    });
+    dir = resolved.dir;
+  } catch (err) {
+    if (err instanceof WorkspaceResolutionError) {
+      process.stderr.write(`${import_kleur10.default.red("error")}: ${err.message}
+`);
+      process.exit(2);
+    }
+    throw err;
+  }
+  await ensureWorkspace(dir);
+  return { provider: new import_mcp_server2.FileBackedWorkspaceProvider(dir), dir };
+}
+function registerFolderCommand(program) {
+  const folder = program.command("folder").description("List, create, rename, move, set auth, or delete folders.");
+  COMMON_OPTS(
+    folder.command("list").description("Print the folder tree (with auth markers).").option("--json", "Emit JSON instead of a formatted tree")
+  ).action(async (opts) => {
+    const { provider } = await openWorkspace(opts);
+    const state = await provider.read();
+    const folders = state.synced.collections.folders;
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(Object.values(folders), null, 2) + "\n");
+      return;
+    }
+    if (Object.keys(folders).length === 0) {
+      process.stdout.write(`${import_kleur10.default.dim("No folders in this workspace.")}
+`);
+      return;
+    }
+    const roots = Object.values(folders).filter((f) => f.parentId === null);
+    roots.sort((a, b) => a.name.localeCompare(b.name));
+    for (const root of roots) printTree(root, folders, 0);
+  });
+  COMMON_OPTS(
+    folder.command("create").description(
+      "Create a new folder. Optionally seed folder-level auth in the same call (saves a follow-up `folder set-auth` round-trip). Prints the new id."
+    ).requiredOption("--name <name>", "Folder name (must be unique among siblings)").option("--parent <id>", "Parent folder id (omit for top level)").option(
+      "--type <type>",
+      "Initial auth type: bearer | basic | api-key | custom-header | none | inherit"
+    ).option("--token <token>", "Token (bearer)").option("--username <user>", "Username (basic)").option("--password <pass>", "Password (basic)").option("--key <key>", "Key (api-key / custom-header)").option("--value <value>", "Value (api-key / custom-header)").option("--add-to <where>", "Where to inject api-key: header | query | cookie", "header")
+  ).action(async (opts) => {
+    const initialAuth = opts.type ? buildAuthFromCli({ ...opts, type: opts.type }) : void 0;
+    const { provider } = await openWorkspace(opts);
+    const f = {
+      id: (0, import_shared6.generateId)(),
+      name: opts.name.trim(),
+      parentId: opts.parent ?? null,
+      ...initialAuth ? { auth: initialAuth } : {}
+    };
+    const result = await provider.apply({ kind: "folder.create", folder: f });
+    if ((result.changedIds.length ?? 0) === 0) {
+      process.stderr.write(`${import_kleur10.default.red("error")}: folder.create no-op (duplicate id?)
+`);
+      process.exit(1);
+    }
+    const authNote = initialAuth ? `  auth=${initialAuth.type}` : "";
+    process.stdout.write(`${import_kleur10.default.green("created")} ${f.id}  ${f.name}${authNote}
+`);
+  });
+  COMMON_OPTS(
+    folder.command("rename").description("Rename a folder. Fails if a sibling already has the new name.").argument("<id>", "Folder id").requiredOption("--name <name>", "New name")
+  ).action(async (id, opts) => {
+    const { provider } = await openWorkspace(opts);
+    const result = await provider.apply({
+      kind: "folder.update",
+      id,
+      patch: { name: opts.name.trim() }
+    });
+    if (result.changedIds.length === 0) {
+      process.stderr.write(
+        `${import_kleur10.default.red("error")}: rename rejected \u2014 folder not found, or a sibling already has the name "${opts.name}".
+`
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`${import_kleur10.default.green("renamed")} ${id}  ${opts.name}
+`);
+  });
+  COMMON_OPTS(
+    folder.command("set-auth").description("Set folder-level auth. Descendants with `auth.type: inherit` will pick it up.").argument("<id>", "Folder id").requiredOption(
+      "--type <type>",
+      "Auth type: bearer | basic | api-key | custom-header | none | inherit"
+    ).option("--token <token>", "Token (bearer)").option("--username <user>", "Username (basic)").option("--password <pass>", "Password (basic)").option("--key <key>", "Key (api-key / custom-header)").option("--value <value>", "Value (api-key / custom-header)").option("--add-to <where>", "Where to inject api-key: header | query | cookie", "header")
+  ).action(async (id, opts) => {
+    const auth = buildAuthFromCli(opts);
+    const { provider } = await openWorkspace(opts);
+    const result = await provider.apply({
+      kind: "folder.update",
+      id,
+      patch: { auth }
+    });
+    if (result.changedIds.length === 0) {
+      process.stderr.write(`${import_kleur10.default.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${import_kleur10.default.green("updated")} ${id}  auth.type=${auth.type}
+`);
+  });
+  COMMON_OPTS(
+    folder.command("clear-auth").description("Clear folder-level auth. Descendants `inherit` walks further up.").argument("<id>", "Folder id")
+  ).action(async (id, opts) => {
+    const { provider } = await openWorkspace(opts);
+    const result = await provider.apply({
+      kind: "folder.update",
+      id,
+      patch: { auth: void 0 }
+    });
+    if (result.changedIds.length === 0) {
+      process.stderr.write(`${import_kleur10.default.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${import_kleur10.default.green("cleared auth")} ${id}
+`);
+  });
+  COMMON_OPTS(
+    folder.command("move").description("Reparent a folder. Cycles + self-parenting are rejected.").argument("<id>", "Folder id").option("--parent <id>", "New parent id (omit for top level)")
+  ).action(async (id, opts) => {
+    const { provider } = await openWorkspace(opts);
+    const result = await provider.apply({
+      kind: "folder.move",
+      id,
+      newParentId: opts.parent ?? null
+    });
+    if (result.changedIds.length === 0) {
+      process.stderr.write(
+        `${import_kleur10.default.red("error")}: move rejected \u2014 folder not found, same parent, self-parent, or cycle.
+`
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`${import_kleur10.default.green("moved")} ${id}  parent=${opts.parent ?? "(root)"}
+`);
+  });
+  COMMON_OPTS(
+    folder.command("delete").description("Delete a folder. Direct children reparent to its parent.").argument("<id>", "Folder id")
+  ).action(async (id, opts) => {
+    const { provider } = await openWorkspace(opts);
+    const result = await provider.apply({ kind: "folder.delete", id });
+    if (result.changedIds.length === 0) {
+      process.stderr.write(`${import_kleur10.default.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${import_kleur10.default.green("deleted")} ${id}
+`);
+  });
+}
+function buildAuthFromCli(opts) {
+  switch (opts.type) {
+    case "none":
+      return { type: "none" };
+    case "inherit":
+      return { type: "inherit" };
+    case "bearer":
+      return { type: "bearer", token: opts.token ?? "" };
+    case "basic":
+      return { type: "basic", username: opts.username ?? "", password: opts.password ?? "" };
+    case "api-key":
+      return {
+        type: "api-key",
+        key: opts.key ?? "",
+        value: opts.value ?? "",
+        addTo: opts.addTo === "query" || opts.addTo === "cookie" ? opts.addTo : "header"
+      };
+    case "custom-header":
+      return { type: "custom-header", key: opts.key ?? "", value: opts.value ?? "" };
+    default:
+      process.stderr.write(
+        `${import_kleur10.default.red("error")}: --type "${opts.type}" not supported by the CLI. Use bearer | basic | api-key | custom-header | none | inherit. For OAuth2 / AWS / Hawk / NTLM / JWT, edit the folder YAML in VS Code or the web/desktop app.
+`
+      );
+      process.exit(2);
+  }
+}
+function printTree(folder, all, depth) {
+  const indent = "  ".repeat(depth);
+  const authTag = folder.auth && folder.auth.type !== "none" && folder.auth.type !== "inherit" ? `  ${import_kleur10.default.cyan(`[auth: ${folder.auth.type}]`)}` : "";
+  process.stdout.write(`${indent}${import_kleur10.default.bold(folder.name)}  ${import_kleur10.default.dim(folder.id)}${authTag}
+`);
+  const children = Object.values(all).filter((f) => f.parentId === folder.id).sort((a, b) => a.name.localeCompare(b.name));
+  for (const c of children) printTree(c, all, depth + 1);
+}
+var import_kleur10, import_shared6, import_mcp_server2, COMMON_OPTS;
+var init_folder = __esm({
+  "src/commands/folder.ts"() {
+    "use strict";
+    import_kleur10 = __toESM(require("kleur"), 1);
+    import_shared6 = require("@apicircle/shared");
+    import_mcp_server2 = require("@apicircle/mcp-server");
+    init_loadWorkspace();
+    init_resolveWorkspace();
+    COMMON_OPTS = (cmd) => cmd.option(
+      "--workspace-name <name-or-id>",
+      "Registry workspace name (case-insensitive) or id. Defaults to the active workspace."
+    ).option(
+      "-w, --workspace-path <dir>",
+      "Filesystem directory containing the .apicircle/ workspace (skips the registry)."
+    );
+  }
+});
+
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
@@ -1635,27 +3190,35 @@ function buildProgram() {
   const program = new import_commander.Command();
   program.name("apicircle").description("Command-line companion to API Circle Studio.").version(CLI_PACKAGE_VERSION);
   registerMockCommand(program);
+  registerMocksCommand(program);
   registerMcpCommand(program);
   registerImportCommand(program);
   registerExportCommand(program);
   registerRunCommand(program);
   registerWorkspacesCommand(program);
+  registerLinkedCommand(program);
+  registerReleaseCommand(program);
+  registerFolderCommand(program);
   return program;
 }
 async function runCli(argv = process.argv) {
   await buildProgram().parseAsync(argv);
 }
 var import_commander, entry;
-var init_src = __esm({
+var init_src2 = __esm({
   "src/index.ts"() {
     "use strict";
     import_commander = require("commander");
     init_mock();
+    init_mocks();
     init_mcp();
     init_import();
     init_export();
     init_run();
     init_workspaces();
+    init_linked();
+    init_release();
+    init_folder();
     init_packageVersion();
     entry = process.argv[1] ?? "";
     if (entry.endsWith("apicircle") || entry.endsWith("index.cjs") || entry.endsWith("index.ts")) {
@@ -1694,6 +3257,8 @@ Commands:
   import <source> <workspace>       Import OpenAPI, Postman, Insomnia, or curl.
   run [options] <plan-id>           Run an execution plan.
   workspaces                        Manage local workspace registries.
+  linked <subcommand>               Manage linked workspaces (list/link/refresh/unlink).
+  release <subcommand>              Tag releases / set topics on the workspace's GitHub repo.
 
 Run "apicircle <command> --help" for command-specific help.
 `;
@@ -1711,7 +3276,7 @@ async function runBin(argv = process.argv) {
     process.stdout.write(formatRootHelp());
     return;
   }
-  const { runCli: runCli2 } = await Promise.resolve().then(() => (init_src(), src_exports));
+  const { runCli: runCli2 } = await Promise.resolve().then(() => (init_src2(), src_exports));
   await runCli2(argv);
 }
 var entry2 = process.argv[1] ?? "";