@apicircle/cli 1.0.8 → 1.1.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   CLI_PACKAGE_VERSION
-} from "./chunk-M5PWIZZF.js";
+} from "./chunk-P4CXF2MS.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -84,13 +84,9 @@ function installShutdown(handle) {
   process.on("SIGTERM", () => void shutdown());
 }
 
-// src/commands/mcp.ts
+// src/commands/mocks.ts
 import kleur2 from "kleur";
-import {
-  createMcpServer,
-  FileBackedWorkspaceProvider,
-  InProcessMockController
-} from "@apicircle/mcp-server";
+import { saveToFile as saveToFile3 } from "@apicircle/core/workspace/file-backed";
 
 // src/util/loadWorkspace.ts
 import * as path2 from "path";
@@ -157,6 +153,7 @@ import * as os from "os";
 import * as path3 from "path";
 import { promises as fs3 } from "fs";
 import {
+  defaultApicircleRoot,
   findWorkspaceEntry,
   loadRegistry,
   registerWorkspace,
@@ -165,30 +162,10 @@ import {
 } from "@apicircle/core/workspace/registry";
 import { saveToFile as saveToFile2 } from "@apicircle/core/workspace/file-backed";
 import { generateId as generateId3 } from "@apicircle/shared";
-var APP_NAME = "@apicircle";
-var APP_SUBDIR = "desktop";
-var WORKSPACES_DIRNAME = "workspaces";
 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 defaultApicircleRoot();
 }
 async function resolveWorkspace(opts = {}) {
   const root = opts.workspacesRoot ?? defaultWorkspacesRoot();
@@ -378,14 +355,156 @@ function buildEmptyState(workspaceId, now, withSample) {
   };
 }
 
+// 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(`${kleur2.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(
+      kleur2.bold(
+        `  ${"NAME".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  ${"PORT".padStart(6)}  ENDPOINTS
+`
+      )
+    );
+    for (const m of mockList) {
+      const portLabel = m.defaultPort === null ? kleur2.dim("auto") : String(m.defaultPort);
+      process.stdout.write(
+        `  ${m.name.padEnd(nameWidth)}  ${kleur2.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(
+        `${kleur2.red("error")}: no mock named "${selector}" in this workspace. Run ${kleur2.cyan("apicircle mocks list")} to see what's available.
+`
+      );
+      process.exit(2);
+      return;
+    }
+    const nextPort = parsePortArg(portArg);
+    if (nextPort === "invalid") {
+      process.stderr.write(
+        `${kleur2.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(
+        `${kleur2.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 saveToFile3(dir, { synced: nextSynced, local: state.local });
+    process.stdout.write(
+      `${kleur2.green("updated")} "${target.name}" defaultPort = ${nextPort === null ? kleur2.dim("auto (free port)") : kleur2.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(`${kleur2.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;
+}
+
 // src/commands/mcp.ts
+import kleur3 from "kleur";
+import {
+  createMcpServer,
+  FileBackedWorkspaceProvider,
+  InProcessMockController
+} from "@apicircle/mcp-server";
 function registerMcpCommand(program) {
   program.command("mcp").description("Run the API Circle MCP server (stdio transport)").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.synced.json (skips the registry)."
+    "Filesystem directory containing workspace.json (skips the registry)."
   ).action(async (opts) => {
     let dir;
     let label;
@@ -399,7 +518,7 @@ function registerMcpCommand(program) {
       label = resolved.fromRegistry ? `${resolved.name ?? resolved.id} (${dir})` : dir;
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${kleur2.red("error")}: ${err.message}
+        process.stderr.write(`${kleur3.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -409,7 +528,7 @@ function registerMcpCommand(program) {
       await ensureWorkspace(dir);
     } catch (err) {
       process.stderr.write(
-        `${kleur2.red("failed to initialise workspace")} at ${dir}: ${err instanceof Error ? err.message : String(err)}
+        `${kleur3.red("failed to initialise workspace")} at ${dir}: ${err instanceof Error ? err.message : String(err)}
 `
       );
       process.exit(1);
@@ -417,7 +536,7 @@ function registerMcpCommand(program) {
     const workspace = new FileBackedWorkspaceProvider(dir);
     const mock = new InProcessMockController();
     const host = createMcpServer({ workspace, mock });
-    process.stderr.write(`${kleur2.green("apicircle-mcp")} ready \xB7 workspace=${label}
+    process.stderr.write(`${kleur3.green("apicircle-mcp")} ready \xB7 workspace=${label}
 `);
     await host.connect();
   });
@@ -426,9 +545,9 @@ function registerMcpCommand(program) {
 // src/commands/import.ts
 import { promises as fs4 } from "fs";
 import * as path4 from "path";
-import kleur3 from "kleur";
+import kleur4 from "kleur";
 import { applyMutation, parseApicircleFolderExport } from "@apicircle/core";
-import { saveToFile as saveToFile3 } from "@apicircle/core/workspace/file-backed";
+import { saveToFile as saveToFile4 } from "@apicircle/core/workspace/file-backed";
 import {
   parseInsomniaToEndpoints,
   parseOpenApiToEndpoints,
@@ -444,7 +563,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 {
@@ -456,13 +575,13 @@ function registerImportCommand(program) {
       dir = resolved.dir;
       if (resolved.fromRegistry) {
         process.stderr.write(
-          `${kleur3.dim("workspace")}: ${kleur3.cyan(resolved.name ?? resolved.id ?? "")} ${kleur3.dim(`(${dir})`)}
+          `${kleur4.dim("workspace")}: ${kleur4.cyan(resolved.name ?? resolved.id ?? "")} ${kleur4.dim(`(${dir})`)}
 `
         );
       }
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${kleur3.red("error")}: ${err.message}
+        process.stderr.write(`${kleur4.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -535,7 +654,7 @@ function registerImportCommand(program) {
         parsedEnvelope = parseApicircleFolderExport(raw);
       } catch (err) {
         process.stderr.write(
-          `${kleur3.red("error")}: ${err instanceof Error ? err.message : String(err)}
+          `${kleur4.red("error")}: ${err instanceof Error ? err.message : String(err)}
 `
         );
         process.exit(2);
@@ -548,29 +667,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(`${kleur3.yellow("warning")}: ${w}
+        process.stderr.write(`${kleur4.yellow("warning")}: ${w}
 `);
       }
-      await saveToFile3(dir, { synced: nextSynced, local: nextLocal });
+      await saveToFile4(dir, { synced: nextSynced, local: nextLocal });
       process.stdout.write(
-        `${kleur3.green("imported")} folder "${parsedEnvelope.rootFolder.name}" (${parsedEnvelope.subfolders.length + 1} folders, ${parsedEnvelope.requests.length} requests) into ${dir}
+        `${kleur4.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(
-          `${kleur3.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.
+          `${kleur4.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(`${kleur3.red("error")}: unknown type '${String(type)}'
+      process.stderr.write(`${kleur4.red("error")}: unknown type '${String(type)}'
 `);
       process.exit(2);
     }
-    await saveToFile3(dir, { synced: nextSynced, local: nextLocal });
+    await saveToFile4(dir, { synced: nextSynced, local: nextLocal });
     process.stdout.write(
-      `${kleur3.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
+      `${kleur4.green("imported")} ${created.length} request${created.length === 1 ? "" : "s"} into ${dir}
 `
     );
   });
@@ -610,7 +729,7 @@ function blankRequest(partial) {
 // src/commands/export.ts
 import { promises as fs5 } from "fs";
 import * as path5 from "path";
-import kleur4 from "kleur";
+import kleur5 from "kleur";
 import {
   collectFolderExport,
   redactFolderExportCredentials,
@@ -635,7 +754,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 {
@@ -646,7 +765,7 @@ function registerExportCommand(program) {
       dir = resolved.dir;
     } catch (err) {
       if (err instanceof WorkspaceResolutionError) {
-        process.stderr.write(`${kleur4.red("error")}: ${err.message}
+        process.stderr.write(`${kleur5.red("error")}: ${err.message}
 `);
         process.exit(2);
       }
@@ -655,13 +774,13 @@ function registerExportCommand(program) {
     const state = await ensureWorkspace(dir);
     const folderId = resolveFolderId(state.synced.collections.folders, folder);
     if (!folderId) {
-      process.stderr.write(`${kleur4.red("error")}: no folder matches "${folder}" in ${dir}
+      process.stderr.write(`${kleur5.red("error")}: no folder matches "${folder}" in ${dir}
 `);
       process.exit(2);
     }
     const collected = collectFolderExport({ synced: state.synced, folderId });
     if (!collected) {
-      process.stderr.write(`${kleur4.red("error")}: folder "${folder}" no longer exists
+      process.stderr.write(`${kleur5.red("error")}: folder "${folder}" no longer exists
 `);
       process.exit(2);
     }
@@ -683,20 +802,20 @@ function registerExportCommand(program) {
       const outPath = path5.resolve(opts.out);
       await fs5.writeFile(outPath, json, "utf-8");
       process.stderr.write(
-        `${kleur4.green("exported")} folder "${collected.report.folderName}" \u2192 ${outPath}
+        `${kleur5.green("exported")} folder "${collected.report.folderName}" \u2192 ${outPath}
 `
       );
     } else {
       process.stdout.write(json);
       process.stdout.write("\n");
       process.stderr.write(
-        `${kleur4.green("exported")} folder "${collected.report.folderName}" (${collected.report.totalFolderCount} folders, ${collected.report.requestCount} requests, ${collected.report.credentials.length - includeIds.size} credentials redacted)
+        `${kleur5.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(
-        `${kleur4.dim("hint")}: save with .apicircle.json, e.g. ${suggestFolderExportFilename(envelope)}
+        `${kleur5.dim("hint")}: save with .apicircle.json, e.g. ${suggestFolderExportFilename(envelope)}
 `
       );
     }
@@ -712,14 +831,14 @@ function resolveFolderId(folders, query) {
 
 // src/commands/run.ts
 import * as os2 from "os";
-import kleur5 from "kleur";
+import kleur6 from "kleur";
 import {
   ANONYMOUS_ACTOR,
   PlanRunDeniedError,
   resolvePlanRef,
   runPlan
 } from "@apicircle/core";
-import { loadFromFile as loadFromFile2, saveToFile as saveToFile4 } from "@apicircle/core/workspace/file-backed";
+import { loadFromFile as loadFromFile2, saveToFile as saveToFile5 } from "@apicircle/core/workspace/file-backed";
 
 // src/util/secrets.ts
 import * as path6 from "path";
@@ -760,7 +879,7 @@ import * as path7 from "path";
 import {
   collectAttachmentSlots
 } from "@apicircle/core";
-var ATTACHMENTS_DIR = path7.join(".apicircle", "attachments");
+var ATTACHMENTS_DIR = "attachments";
 async function prepareExecutionAttachments(workspaceDir, state, plan) {
   const cacheDir = path7.resolve(workspaceDir, ATTACHMENTS_DIR);
   const requirements = collectExecutionAttachmentRequirements(state, plan);
@@ -774,6 +893,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++;
@@ -874,6 +997,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,
@@ -905,6 +1029,7 @@ function collectExecutionAttachmentRequirements(state, plan) {
       addRequirement(seen, {
         ...slot,
         source: "linked-workspace",
+        sourceWorkspaceId: link.sourceWorkspaceId,
         linkedWorkspaceId,
         repoFullName: link.source.repoFullName,
         branch: link.source.branch,
@@ -976,7 +1101,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)}`;
@@ -1029,7 +1159,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 {
@@ -1041,7 +1171,7 @@ function registerRunCommand(program) {
       dir = resolved.dir;
       if (resolved.fromRegistry) {
         process.stderr.write(
-          `${kleur5.dim("workspace")}: ${kleur5.cyan(resolved.name ?? resolved.id ?? "")} ${kleur5.dim(`(${dir})`)}
+          `${kleur6.dim("workspace")}: ${kleur6.cyan(resolved.name ?? resolved.id ?? "")} ${kleur6.dim(`(${dir})`)}
 `
         );
       }
@@ -1059,7 +1189,7 @@ function registerRunCommand(program) {
     }
     const state = await loadFromFile2(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 = resolvePlanRef(state.synced, planRef);
@@ -1129,7 +1259,7 @@ function registerRunCommand(program) {
     process.off("SIGINT", onSigint);
     const aborted = controller.signal.aborted;
     const saved = opts.save !== false;
-    if (saved) await saveToFile4(dir, result.nextState);
+    if (saved) await saveToFile5(dir, result.nextState);
     if (reporter === "json") {
       process.stdout.write(
         JSON.stringify(
@@ -1170,17 +1300,17 @@ function formatHeader(plan, actor, withAssertions, opts) {
     opts.bail ? "bail" : null,
     opts.env ? `env=${opts.env}` : null
   ].filter((f) => f !== null);
-  return `${kleur5.bold("Plan")} ${plan.name}  ${kleur5.dim(
+  return `${kleur6.bold("Plan")} ${plan.name}  ${kleur6.dim(
     `(${enabled}/${plan.steps.length} steps \xB7 ${flags.join(" \xB7 ")})`
   )}
-${kleur5.dim("Run by")} ${actor.name} ${kleur5.dim(`(${actor.kind})`)}
+${kleur6.dim("Run by")} ${actor.name} ${kleur6.dim(`(${actor.kind})`)}
 
 `;
 }
 function formatAttachmentPreparation(summary) {
   const status = `${summary.downloaded} downloaded, ${summary.alreadyPresent} already local`;
   const lines = [
-    `${kleur5.bold("Attachments")} ${summary.total} required ${kleur5.dim(
+    `${kleur6.bold("Attachments")} ${summary.total} required ${kleur6.dim(
       `(${status} - ${summary.cacheDir})`
     )}`
   ];
@@ -1188,7 +1318,7 @@ function formatAttachmentPreparation(summary) {
     const source = entry2.source === "linked-workspace" ? `linked:${entry2.linkedWorkspaceId ?? "unknown"}` : "workspace";
     const requiredBy = entry2.requiredBy.map((item) => item.requestName).join(", ");
     lines.push(
-      `  ${kleur5.dim("file")} ${entry2.filename} ${kleur5.dim(
+      `  ${kleur6.dim("file")} ${entry2.filename} ${kleur6.dim(
         `${source} - ${requiredBy} - ${entry2.localPath}`
       )}`
     );
@@ -1201,31 +1331,31 @@ function formatStepLine(step) {
   const n = `${step.stepIndex + 1}.`.padEnd(3);
   const method = (step.requestMethod || "\u2014").padEnd(7);
   if (step.skipped) {
-    return `  ${kleur5.dim("\u2013")} ${kleur5.dim(n)} ${kleur5.dim(method)} ${kleur5.dim(
+    return `  ${kleur6.dim("\u2013")} ${kleur6.dim(n)} ${kleur6.dim(method)} ${kleur6.dim(
       `${step.requestName}  skipped`
     )}
 `;
   }
-  const mark = step.passed ? kleur5.green("\u2713") : kleur5.red("\u2717");
+  const mark = step.passed ? kleur6.green("\u2713") : kleur6.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)} ${kleur5.dim(duration)}`;
+  let line = `  ${mark} ${n} ${method} ${name} ${status.padEnd(4)} ${kleur6.dim(duration)}`;
   if (step.assertionResults.length > 0) {
     const passed = step.assertionResults.filter((a) => a.passed).length;
-    line += `  ${kleur5.dim(`${passed}/${step.assertionResults.length} assertions`)}`;
+    line += `  ${kleur6.dim(`${passed}/${step.assertionResults.length} assertions`)}`;
   }
   line += "\n";
   if (step.error) {
-    line += `      ${kleur5.red(step.error)}
+    line += `      ${kleur6.red(step.error)}
 `;
   }
   for (const a of step.assertionResults) {
-    if (!a.passed) line += `      ${kleur5.red("\u2717")} ${a.detail ?? `${a.kind} ${a.op}`}
+    if (!a.passed) line += `      ${kleur6.red("\u2717")} ${a.detail ?? `${a.kind} ${a.op}`}
 `;
   }
   if (step.missingVariables.length > 0) {
-    line += `      ${kleur5.yellow("\u26A0")} unresolved: ${step.missingVariables.map((v) => `{{${v}}}`).join(", ")}
+    line += `      ${kleur6.yellow("\u26A0")} unresolved: ${step.missingVariables.map((v) => `{{${v}}}`).join(", ")}
 `;
   }
   return line;
@@ -1244,24 +1374,24 @@ function tally(result) {
 function formatSummary(result, saved, aborted) {
   if (result.steps.length === 0) {
     return `
-${kleur5.yellow("Plan has no steps.")}
+${kleur6.yellow("Plan has no steps.")}
 `;
   }
   const { passed, failed, skipped } = tally(result);
   const parts = [
-    kleur5.green(`${passed} passed`),
-    failed > 0 ? kleur5.red(`${failed} failed`) : kleur5.dim(`${failed} failed`),
-    kleur5.dim(`${skipped} skipped`)
+    kleur6.green(`${passed} passed`),
+    failed > 0 ? kleur6.red(`${failed} failed`) : kleur6.dim(`${failed} failed`),
+    kleur6.dim(`${skipped} skipped`)
   ];
-  const verdict = result.passed && !aborted ? kleur5.green("PASS") : kleur5.red("FAIL");
+  const verdict = result.passed && !aborted ? kleur6.green("PASS") : kleur6.red("FAIL");
   let out = `
-${verdict}  ${parts.join(kleur5.dim(" \xB7 "))}  ${kleur5.dim(
+${verdict}  ${parts.join(kleur6.dim(" \xB7 "))}  ${kleur6.dim(
     `\xB7 ${result.planRun.durationMs}ms`
   )}
 `;
-  if (aborted) out += `${kleur5.yellow("Run aborted before every step finished.")}
+  if (aborted) out += `${kleur6.yellow("Run aborted before every step finished.")}
 `;
-  out += saved ? kleur5.dim("Plan run saved to workspace history.\n") : kleur5.dim("Plan run not saved (--no-save).\n");
+  out += saved ? kleur6.dim("Plan run saved to workspace history.\n") : kleur6.dim("Plan run not saved (--no-save).\n");
   return out;
 }
 function buildJsonReport(workspace, planId, plan, actor, result, saved, aborted, attachments) {
@@ -1337,13 +1467,13 @@ ${cases.join("\n")}
 `;
 }
 function fail(message, code = 2, kind = "error") {
-  process.stderr.write(`${kleur5.red(kind)}: ${message}
+  process.stderr.write(`${kleur6.red(kind)}: ${message}
 `);
   process.exitCode = code;
 }
 
 // src/commands/workspaces.ts
-import kleur6 from "kleur";
+import kleur7 from "kleur";
 import { findWorkspaceEntry as findWorkspaceEntry2, setActiveWorkspace } from "@apicircle/core/workspace/registry";
 function registerWorkspacesCommand(program) {
   const ws = program.command("workspaces").description("List, create, or switch the active workspace");
@@ -1355,15 +1485,15 @@ function registerWorkspacesCommand(program) {
     }
     if (registry.workspaces.length === 0) {
       process.stdout.write(
-        `${kleur6.dim("No workspaces registered yet at")} ${root}
-${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces create <name>")} ${kleur6.dim(
+        `${kleur7.dim("No workspaces registered yet at")} ${root}
+${kleur7.dim("Run")} ${kleur7.cyan("apicircle workspaces create <name>")} ${kleur7.dim(
           "or open the desktop app to seed one."
         )}
 `
       );
       return;
     }
-    process.stdout.write(`${kleur6.dim("registry")}: ${root}
+    process.stdout.write(`${kleur7.dim("registry")}: ${root}
 
 `);
     const rows = [...registry.workspaces].sort(
@@ -1372,22 +1502,22 @@ ${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces create <name>")} ${kleu
     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(
-      kleur6.bold(
+      kleur7.bold(
         `  ${"".padEnd(1)} ${"NAME".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  LAST OPENED
 `
       )
     );
     for (const w of rows) {
-      const mark = w.id === registry.activeWorkspaceId ? kleur6.green("\u25CF") : " ";
+      const mark = w.id === registry.activeWorkspaceId ? kleur7.green("\u25CF") : " ";
       process.stdout.write(
-        `  ${mark} ${w.name.padEnd(nameWidth)}  ${kleur6.dim(
+        `  ${mark} ${w.name.padEnd(nameWidth)}  ${kleur7.dim(
           w.id.padEnd(idWidth)
-        )}  ${kleur6.dim(w.lastOpenedAt)}
+        )}  ${kleur7.dim(w.lastOpenedAt)}
 `
       );
     }
     process.stdout.write(`
-${kleur6.dim("\u25CF = active")}
+${kleur7.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) => {
@@ -1397,17 +1527,17 @@ ${kleur6.dim("\u25CF = active")}
         sampleRequest: opts.sample ?? false
       });
       process.stdout.write(
-        `${kleur6.green("created")} workspace ${kleur6.cyan(entry2.name)} ${kleur6.dim(`(${entry2.id})`)}
+        `${kleur7.green("created")} workspace ${kleur7.cyan(entry2.name)} ${kleur7.dim(`(${entry2.id})`)}
   at ${dir}
 `
       );
       if (registry.activeWorkspaceId === entry2.id) {
-        process.stdout.write(`${kleur6.dim("marked as active")}
+        process.stdout.write(`${kleur7.dim("marked as active")}
 `);
       }
     } catch (err) {
       process.stderr.write(
-        `${kleur6.red("error")}: ${err instanceof Error ? err.message : String(err)}
+        `${kleur7.red("error")}: ${err instanceof Error ? err.message : String(err)}
 `
       );
       process.exit(2);
@@ -1418,8 +1548,8 @@ ${kleur6.dim("\u25CF = active")}
     const entry2 = findWorkspaceEntry2(registry, selector);
     if (!entry2) {
       process.stderr.write(
-        `${kleur6.red("error")}: no workspace named "${selector}" in the registry at ${root}.
-${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces list")} ${kleur6.dim("to see what is available.")}
+        `${kleur7.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+${kleur7.dim("Run")} ${kleur7.cyan("apicircle workspaces list")} ${kleur7.dim("to see what is available.")}
 `
       );
       process.exit(2);
@@ -1428,7 +1558,7 @@ ${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces list")} ${kleur6.dim("t
     const next = await setActiveWorkspace(root, entry2.id);
     void next;
     process.stdout.write(
-      `${kleur6.green("active")} workspace is now ${kleur6.cyan(entry2.name)} ${kleur6.dim(`(${entry2.id})`)}
+      `${kleur7.green("active")} workspace is now ${kleur7.cyan(entry2.name)} ${kleur7.dim(`(${entry2.id})`)}
 `
     );
   });
@@ -1441,7 +1571,7 @@ ${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces list")} ${kleur6.dim("t
     const entry2 = findWorkspaceEntry2(registry, selector);
     if (!entry2) {
       process.stderr.write(
-        `${kleur6.red("error")}: no workspace named "${selector}" in the registry at ${root}.
+        `${kleur7.red("error")}: no workspace named "${selector}" in the registry at ${root}.
 `
       );
       process.exit(2);
@@ -1453,16 +1583,1399 @@ ${kleur6.dim("Run")} ${kleur6.cyan("apicircle workspaces list")} ${kleur6.dim("t
   });
 }
 
+// src/commands/linked.ts
+import kleur8 from "kleur";
+import {
+  fetchRemoteWorkspaceJson,
+  applyMutation as applyMutation2,
+  buildLinkedSnapshot,
+  ledgerFromProbe,
+  parseLinkedWorkspaceJson
+} from "@apicircle/core";
+import { saveToFile as saveToFile6 } from "@apicircle/core/workspace/file-backed";
+import { generateId as generateId5 } from "@apicircle/shared";
+
+// ../git/src/github/errors.ts
+var GitHubError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "GitHubError";
+  }
+  status;
+  body;
+};
+var 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;
+  }
+};
+var 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;
+  }
+};
+var UnauthorizedError = class extends GitHubError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "UnauthorizedError";
+  }
+};
+var 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
+var API_BASE = "https://api.github.com";
+var LOGIN_BASE = "https://github.com";
+var DEFAULT_TIMEOUT_MS = 15e3;
+var 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 ?? []);
+  }
+};
+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;
+  }
+}
+
+// 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(
+        `${kleur8.dim("workspace")}: ${kleur8.cyan(resolved.name ?? resolved.id ?? "")} ${kleur8.dim(`(${resolved.dir})`)}
+`
+      );
+    }
+    return resolved.dir;
+  } catch (err) {
+    if (err instanceof WorkspaceResolutionError) {
+      process.stderr.write(`${kleur8.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(`${kleur8.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(
+        `${kleur8.cyan(l.id)}  ${kleur8.bold(l.name)}  ${kleur8.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(`${kleur8.red("error")}: repo must be owner/name
+`);
+        process.exit(2);
+      }
+      if (opts.kind !== "public" && opts.kind !== "private") {
+        process.stderr.write(`${kleur8.red("error")}: --kind must be private or public
+`);
+        process.exit(2);
+      }
+      const token = resolveToken(opts);
+      if (opts.kind === "private" && !token) {
+        process.stderr.write(
+          `${kleur8.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(
+          `${kleur8.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 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(`${kleur8.red("error")}: ${repo}@${opts.branch}: ${result.error}
+`);
+        process.exit(2);
+      }
+      const probe = parseLinkedWorkspaceJson(result.content);
+      const ledger = ledgerFromProbe(probe);
+      const link = {
+        id: generateId5(),
+        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 = buildLinkedSnapshot(probe, link) ?? void 0;
+      const out = applyMutation2(state, {
+        kind: "linkedWorkspace.upsert",
+        link,
+        ledger,
+        ...snapshot ? { snapshot } : {}
+      });
+      await saveToFile6(dir, out.next);
+      process.stdout.write(
+        `${kleur8.green("linked")} ${kleur8.bold(repo)} ${kleur8.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(`${kleur8.red("error")}: linked workspace ${id} not found
+`);
+      process.exit(2);
+    }
+    const token = resolveToken(opts);
+    if (link.kind === "private" && !token) {
+      process.stderr.write(
+        `${kleur8.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 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(
+        `${kleur8.red("error")}: ${link.source.repoFullName}@${link.source.branch}: ${result.error}
+`
+      );
+      process.exit(2);
+    }
+    const probe = parseLinkedWorkspaceJson(result.content);
+    const ledger = ledgerFromProbe(probe);
+    const needsSnapshot = !state.local.linkedCollections[id];
+    const snapshot = needsSnapshot ? buildLinkedSnapshot(probe, link) ?? void 0 : void 0;
+    const out = applyMutation2(state, {
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    await saveToFile6(dir, out.next);
+    process.stdout.write(
+      `${kleur8.green("refreshed")} ${kleur8.bold(link.name)} ${kleur8.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(`${kleur8.red("error")}: linked workspace ${id} not found
+`);
+      process.exit(2);
+    }
+    const out = applyMutation2(state, { kind: "linkedWorkspace.remove", id });
+    await saveToFile6(dir, out.next);
+    process.stdout.write(`${kleur8.green("unlinked")} ${kleur8.dim(id)}
+`);
+  });
+}
+
+// src/commands/release.ts
+import kleur9 from "kleur";
+var TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+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(`${kleur9.red("error")}: repo must be owner/name
+`);
+      process.exit(2);
+    }
+    const token = resolveToken2(opts);
+    if (!token) {
+      process.stderr.write(
+        `${kleur9.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(
+            `${kleur9.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(
+        `${kleur9.green("tagged")} ${kleur9.bold(tagName)} ${kleur9.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(`${kleur9.green("release")} ${kleur9.dim(r.htmlUrl)}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `${kleur9.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(`${kleur9.red("error")}: repo must be owner/name
+`);
+      process.exit(2);
+    }
+    const token = resolveToken2(opts);
+    if (!token) {
+      process.stderr.write(
+        `${kleur9.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(`${kleur9.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(`${kleur9.red("error")}: invalid topic "${t}"
+`);
+          process.exit(2);
+        }
+        if (t.length > 50) {
+          process.stderr.write(`${kleur9.red("error")}: topic "${t}" exceeds 50 characters
+`);
+          process.exit(2);
+        }
+      }
+      if (normalized.length > 20) {
+        process.stderr.write(`${kleur9.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(`${kleur9.green("topics set")} ${kleur9.dim(`(${saved.length})`)}
+`);
+      for (const t of saved) process.stdout.write(`  ${t}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `${kleur9.red("error")}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(2);
+    }
+  });
+}
+
+// src/commands/folder.ts
+import kleur10 from "kleur";
+import { generateId as generateId6 } from "@apicircle/shared";
+import { FileBackedWorkspaceProvider as FileBackedWorkspaceProvider2 } from "@apicircle/mcp-server";
+var 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)."
+);
+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(`${kleur10.red("error")}: ${err.message}
+`);
+      process.exit(2);
+    }
+    throw err;
+  }
+  await ensureWorkspace(dir);
+  return { provider: new FileBackedWorkspaceProvider2(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(`${kleur10.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: generateId6(),
+      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(`${kleur10.red("error")}: folder.create no-op (duplicate id?)
+`);
+      process.exit(1);
+    }
+    const authNote = initialAuth ? `  auth=${initialAuth.type}` : "";
+    process.stdout.write(`${kleur10.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(
+        `${kleur10.red("error")}: rename rejected \u2014 folder not found, or a sibling already has the name "${opts.name}".
+`
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`${kleur10.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(`${kleur10.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${kleur10.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(`${kleur10.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${kleur10.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(
+        `${kleur10.red("error")}: move rejected \u2014 folder not found, same parent, self-parent, or cycle.
+`
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`${kleur10.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(`${kleur10.red("error")}: folder ${id} not found.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${kleur10.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(
+        `${kleur10.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" ? `  ${kleur10.cyan(`[auth: ${folder.auth.type}]`)}` : "";
+  process.stdout.write(`${indent}${kleur10.bold(folder.name)}  ${kleur10.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);
+}
+
 // src/index.ts
 function buildProgram() {
   const program = new 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) {