@apicircle/mcp-server 1.0.8 → 1.1.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,21 +17,37 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AI_CLIENTS: () => AI_CLIENTS,
   FileBackedWorkspaceProvider: () => FileBackedWorkspaceProvider,
+  GitBackedWorkspaceProvider: () => GitBackedWorkspaceProvider,
   InMemoryWorkspaceProvider: () => InMemoryWorkspaceProvider,
   InProcessMockController: () => InProcessMockController,
+  MCP_PROMPTS: () => MCP_PROMPTS,
+  MCP_PROMPT_CATEGORIES: () => MCP_PROMPT_CATEGORIES,
   McpHost: () => McpHost,
   MultiWorkspaceProvider: () => MultiWorkspaceProvider,
   SingleWorkspaceAdapter: () => SingleWorkspaceAdapter,
+  StdioServerTransport: () => import_stdio2.StdioServerTransport,
+  StreamableHTTPServerTransport: () => import_streamableHttp.StreamableHTTPServerTransport,
   TOOL_REGISTRY: () => TOOL_REGISTRY,
   WorkspaceNotFoundError: () => WorkspaceNotFoundError,
+  buildSnippetVariants: () => buildSnippetVariants,
   createMcpServer: () => createMcpServer,
-  getTool: () => getTool
+  getTool: () => getTool,
+  resolveAiClientConfigPath: () => resolveAiClientConfigPath
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -41,9 +59,10 @@ var import_zod = require("zod");
 // package.json
 var package_default = {
   name: "@apicircle/mcp-server",
-  version: "1.0.8",
+  version: "1.1.0",
   private: false,
   type: "module",
+  sideEffects: false,
   description: "Model Context Protocol server exposing API Circle Studio's workspace as a tool catalog. Used by Claude Desktop, ChatGPT, Cursor, GitHub Copilot, and any other MCP-compatible AI client.",
   keywords: [
     "apicircle",
@@ -86,7 +105,8 @@ var package_default = {
     "apicircle-mcp": "./dist/bin/mcp-server.cjs"
   },
   exports: {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./prompts": "./src/prompts/mcpPrompts.ts"
   },
   files: [
     "dist"
@@ -105,6 +125,16 @@ var package_default = {
           types: "./dist/index.d.cts",
           default: "./dist/index.cjs"
         }
+      },
+      "./prompts": {
+        import: {
+          types: "./dist/prompts/mcpPrompts.d.ts",
+          default: "./dist/prompts/mcpPrompts.js"
+        },
+        require: {
+          types: "./dist/prompts/mcpPrompts.d.cts",
+          default: "./dist/prompts/mcpPrompts.cjs"
+        }
       }
     }
   },
@@ -122,6 +152,7 @@ var package_default = {
     zod: "^3.23.0"
   },
   devDependencies: {
+    "@apicircle/git": "workspace:*",
     "@types/node": "^20.0.0",
     tsup: "^8.3.0",
     typescript: "^5.4.0",
@@ -590,6 +621,7 @@ var workspaceListTool = {
 var import_zod5 = require("zod");
 var import_shared2 = require("@apicircle/shared");
 var import_core2 = require("@apicircle/core");
+var FULL_REQUEST_AUTH = import_zod5.z.object({ type: import_zod5.z.string() }).passthrough();
 var HTTP_METHOD = import_zod5.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 var requestCreateTool = {
   name: "request.create",
@@ -677,16 +709,18 @@ var requestDeleteTool = {
 };
 var folderCreateTool = {
   name: "folder.create",
-  description: "Create a folder under an optional parent folder.",
+  description: "Create a folder under an optional parent folder. Optionally seed folder-level `auth` so descendants with `auth: inherit` resolve to it immediately \u2014 saves a follow-up `folder.update` round-trip.",
   inputSchema: import_zod5.z.object({
     name: import_zod5.z.string().default("New folder"),
-    parentId: import_zod5.z.string().nullable().optional()
+    parentId: import_zod5.z.string().nullable().optional(),
+    auth: FULL_REQUEST_AUTH.optional()
   }),
   async handler(input, ctx) {
     const folder = {
       id: (0, import_shared2.generateId)(),
       name: input.name,
-      parentId: input.parentId ?? null
+      parentId: input.parentId ?? null,
+      ...input.auth ? { auth: input.auth } : {}
     };
     const out = await ctx.workspace.apply({ kind: "folder.create", folder });
     return { id: folder.id, changedIds: out.changedIds };
@@ -710,18 +744,39 @@ var folderReadTool = {
 };
 var folderUpdateTool = {
   name: "folder.update",
-  description: "Move a folder to a new parent (or to root with parentId: null).",
+  description: 'Update a folder. Supply `parentId` to move it (use `null` for root), `name` to rename, and/or `auth` to set the folder-level auth that descendants inherit when their `auth.type === "inherit"`. Set `clearAuth: true` to remove the folder-level auth entirely (descendants then fall through to the next ancestor). The `auth` field accepts any of the 17 RequestAuth types \u2014 same surface as `request.update`. The simple ones (bearer / basic / api-key / custom-header / none / inherit) are easy to author by hand; OAuth2 / AWS SigV4 / Digest / NTLM / Hawk / JWT Bearer require the full canonical shape (see `RequestAuth` in `@apicircle/shared/types.ts`).',
   inputSchema: import_zod5.z.object({
     id: import_zod5.z.string(),
-    parentId: import_zod5.z.string().nullable()
+    parentId: import_zod5.z.string().nullable().optional(),
+    name: import_zod5.z.string().optional(),
+    auth: FULL_REQUEST_AUTH.optional(),
+    clearAuth: import_zod5.z.boolean().optional()
+  }).refine((v) => !(v.auth !== void 0 && v.clearAuth === true), {
+    message: "Pass either `auth` or `clearAuth: true`, not both."
   }),
   async handler(input, ctx) {
-    const out = await ctx.workspace.apply({
-      kind: "folder.move",
-      id: input.id,
-      newParentId: input.parentId
-    });
-    return { changedIds: out.changedIds };
+    const changedIds = [];
+    if (input.parentId !== void 0) {
+      const out = await ctx.workspace.apply({
+        kind: "folder.move",
+        id: input.id,
+        newParentId: input.parentId
+      });
+      changedIds.push(...out.changedIds);
+    }
+    const updatePatch = {};
+    if (input.name !== void 0) updatePatch.name = input.name;
+    if (input.auth !== void 0) updatePatch.auth = input.auth;
+    else if (input.clearAuth === true) updatePatch.auth = void 0;
+    if (input.name !== void 0 || input.auth !== void 0 || input.clearAuth === true) {
+      const out = await ctx.workspace.apply({
+        kind: "folder.update",
+        id: input.id,
+        patch: updatePatch
+      });
+      changedIds.push(...out.changedIds);
+    }
+    return { changedIds: Array.from(new Set(changedIds)) };
   }
 };
 var folderDeleteTool = {
@@ -1695,7 +1750,9 @@ var CONDITION_CLAUSE_NL = import_zod9.z.object({
 var RESPONSE_RULE_NL = import_zod9.z.object({
   name: import_zod9.z.string(),
   enabled: import_zod9.z.boolean().default(true),
-  when: import_zod9.z.array(CONDITION_CLAUSE_NL).default([]),
+  // At least one clause — a no-condition rule is dead (the runtime engine skips
+  // clause-less rules), so it never fires (mirrors the VS Code parser's reject).
+  when: import_zod9.z.array(CONDITION_CLAUSE_NL).min(1),
   response: import_zod9.z.object({
     status: import_zod9.z.number().int().min(100).max(599).default(200),
     jsonBody: import_zod9.z.string().default("{}")
@@ -1745,7 +1802,7 @@ function buildEndpoint(input) {
   };
   const validationRules = input.validationRules ?? [];
   const responseRules = input.responseRules ?? [];
-  const multipliers = input.multipliers ?? [];
+  const multipliers = (input.multipliers ?? []).slice(0, import_shared3.MAX_RESPONSE_MULTIPLIERS);
   if (multipliers.length > 0) {
     defaultResponse.multipliers = multipliers.map((m) => ({
       id: (0, import_shared3.generateId)(),
@@ -1978,10 +2035,13 @@ var promptSetPlanVariablesTool = {
 };
 var promptCreateMockServerTool = {
   name: "prompt.create_mock_server",
-  description: "Create a manual-mode mock server with optional inline endpoints from an LLM-shaped JSON envelope. The model produces `{ name, defaultPort?, endpoints: [{ method, pathPattern, name?, response?, validationRules?, responseRules?, multipliers? }] }`; this tool generates ids for the server and every endpoint / rule, then persists in one shot.",
+  description: "Create a manual-mode mock server with optional inline endpoints from an LLM-shaped JSON envelope. The model produces `{ name, defaultPort?, endpoints: [{ method, pathPattern, name?, response?, validationRules?, responseRules?, multiplier? }] }`; this tool generates ids for the server and every endpoint / rule, then persists in one shot.",
   inputSchema: import_zod9.z.object({
     name: import_zod9.z.string().min(1),
-    defaultPort: import_zod9.z.number().int().positive().nullable().optional(),
+    // Mirrors mock.create_manual / mock.start / mock.set_default_port:
+    // reject out-of-range ports at the tool boundary so a prompt that
+    // returns a stray port (1, 80, 999999) never leaks into the synced doc.
+    defaultPort: import_zod9.z.number().int().min(1024).max(65535).nullable().optional(),
     endpoints: import_zod9.z.array(ENDPOINT_INPUT).default([])
   }),
   async handler(input, ctx) {
@@ -2008,7 +2068,7 @@ var promptCreateMockServerTool = {
 };
 var promptAddMockEndpointTool = {
   name: "prompt.add_mock_endpoint",
-  description: "Append a new endpoint (with optional inline validation rules, response rules, and multipliers) to an existing mock server from an LLM-shaped JSON envelope. All ids are auto-generated; the existing endpoints stay in place.",
+  description: "Append a new endpoint (with optional inline validation rules, response rules, and a single response multiplier) to an existing mock server from an LLM-shaped JSON envelope. All ids are auto-generated; the existing endpoints stay in place.",
   inputSchema: import_zod9.z.object({
     mockId: import_zod9.z.string(),
     method: HTTP_METHOD2,
@@ -2111,7 +2171,7 @@ var promptSetEndpointResponseRulesTool = {
 };
 var promptSetEndpointMultipliersTool = {
   name: "prompt.set_endpoint_multipliers",
-  description: "Replace the response multipliers on an endpoint's defaultResponse with an LLM-shaped list. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Every multiplier gets a fresh id. Empty array clears all multipliers.",
+  description: "Replace the response multipliers on an endpoint's defaultResponse with an LLM-shaped list. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Every multiplier gets a fresh id. Empty array clears all. Capped at MAX_RESPONSE_MULTIPLIERS (1) \u2014 extra entries are rejected.",
   inputSchema: import_zod9.z.object({
     mockId: import_zod9.z.string(),
     endpointId: import_zod9.z.string(),
@@ -2122,6 +2182,9 @@ var promptSetEndpointMultipliersTool = {
     const mock = state.synced.mockServers[input.mockId];
     if (!mock) return { ok: false, error: "mock not found" };
     const multipliers = input.multipliers;
+    if (multipliers.length > import_shared3.MAX_RESPONSE_MULTIPLIERS) {
+      return { ok: false, error: "too many multipliers" };
+    }
     const next = patchEndpoint(mock, input.endpointId, (e) => ({
       ...e,
       defaultResponse: {
@@ -2142,16 +2205,191 @@ var promptSetEndpointMultipliersTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
+var PARAM_NL = import_zod9.z.object({
+  name: import_zod9.z.string(),
+  typeHint: import_zod9.z.string().optional(),
+  required: import_zod9.z.boolean().optional(),
+  description: import_zod9.z.string().optional(),
+  example: import_zod9.z.string().optional()
+});
+var promptSetEndpointRequestSchemaTool = {
+  name: "prompt.set_endpoint_request_schema",
+  description: "Declare an endpoint's expected inputs with an LLM-shaped list: path / query / header / cookie params (name + optional typeHint / required / description / example) plus an optional body-shape doc. Every param gets a fresh id; omitted lists are cleared. Documentation-only \u2014 it drives the editor UI + OpenAPI export, not runtime gating (use validation rules for that).",
+  inputSchema: import_zod9.z.object({
+    mockId: import_zod9.z.string(),
+    endpointId: import_zod9.z.string(),
+    pathParams: import_zod9.z.array(PARAM_NL).default([]),
+    queryParams: import_zod9.z.array(PARAM_NL).default([]),
+    headers: import_zod9.z.array(PARAM_NL).default([]),
+    cookies: import_zod9.z.array(PARAM_NL).default([]),
+    body: import_zod9.z.object({ description: import_zod9.z.string().optional(), example: import_zod9.z.string().optional() }).optional()
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.mockId];
+    if (!mock) return { ok: false, error: "mock not found" };
+    const toParams = (list) => list.map((p) => ({
+      id: (0, import_shared3.generateId)(),
+      name: p.name,
+      typeHint: p.typeHint,
+      required: p.required,
+      description: p.description,
+      example: p.example
+    }));
+    const body = input.body && (input.body.description || input.body.example) ? input.body : void 0;
+    const next = patchEndpoint(mock, input.endpointId, (e) => ({
+      ...e,
+      requestSchema: {
+        pathParams: toParams(input.pathParams),
+        queryParams: toParams(input.queryParams),
+        headers: toParams(input.headers),
+        cookies: toParams(input.cookies),
+        body
+      }
+    }));
+    if (!next) return { ok: false, error: "endpoint not found" };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
 
-// src/tools/mocks.ts
+// src/tools/globalAssets.ts
 var import_zod10 = require("zod");
 var import_shared4 = require("@apicircle/shared");
+function deriveState(asset, hasPendingUpload) {
+  const w = asset.workingBranchRef ?? null;
+  const b = asset.baseBranchRef ?? null;
+  if (w && b) {
+    if (w.blobSha && b.blobSha && w.blobSha !== b.blobSha) return "diverged";
+    return "merged";
+  }
+  if (w && !b) return "workingOnly";
+  if (!w && b) return "baseOnly";
+  if (hasPendingUpload) return "uploading";
+  return "missing";
+}
+var globalAssetsFilesListTool = {
+  name: "assets.list_files",
+  description: "List every Global File Asset with its provenance state and reference count. Each entry includes id, name, filename, size, mimeType, sha256, state (uploading | workingOnly | merged | baseOnly | missing | diverged), workingBranchRef, baseBranchRef, and usage { requests, mockEndpoints, total }.",
+  inputSchema: import_zod10.z.object({}).strict(),
+  async handler(_input, ctx) {
+    const state = await ctx.workspace.read();
+    const files = state.synced.globalAssets.files ?? {};
+    const pending = state.local.pendingFileUploads ?? {};
+    const usage = state.local.assetUsageIndex ?? {};
+    const items = Object.values(files).map((asset) => {
+      const hasPending = Boolean(pending[asset.id]);
+      const u = usage[asset.id] ?? { requests: [], mockEndpoints: [], total: 0 };
+      return {
+        id: asset.id,
+        name: asset.name,
+        description: asset.description ?? null,
+        filename: asset.filename,
+        size: asset.size,
+        mimeType: asset.mimeType,
+        sha256: asset.sha256 ?? null,
+        state: deriveState(asset, hasPending),
+        workingBranchRef: asset.workingBranchRef ?? null,
+        baseBranchRef: asset.baseBranchRef ?? null,
+        usage: { ...u }
+      };
+    });
+    return { count: items.length, files: items };
+  }
+};
+var globalAssetsFilesCreateTool = {
+  name: "assets.create_file",
+  description: 'Register a Global File Asset entry. Bytes are NOT carried \u2014 MCP returns the new asset id and the asset enters the "missing" state. The user fills the bytes from the Global Assets panel (a "Fill bytes" button surfaces on missing-state assets) which preserves the slot id and queues the bytes for the next push. Use this when an AI client wants to claim an asset slot for a file the user will provide later.',
+  inputSchema: import_zod10.z.object({
+    name: import_zod10.z.string().min(1, "name is required"),
+    description: import_zod10.z.string().optional(),
+    filename: import_zod10.z.string().min(1, "filename is required"),
+    size: import_zod10.z.number().int().nonnegative(),
+    mimeType: import_zod10.z.string().default("application/octet-stream"),
+    sha256: import_zod10.z.string().optional()
+  }).strict(),
+  async handler(input, ctx) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const file = {
+      id: (0, import_shared4.generateId)(),
+      name: input.name,
+      description: input.description,
+      slotId: (0, import_shared4.generateId)(),
+      filename: input.filename,
+      size: input.size,
+      mimeType: input.mimeType,
+      sha256: input.sha256,
+      createdAt: now,
+      updatedAt: now
+    };
+    const out = await ctx.workspace.apply({ kind: "globalAsset.upsertFile", file });
+    return { id: file.id, slotId: file.slotId, changedIds: out.changedIds };
+  }
+};
+var globalAssetsFilesUpdateTool = {
+  name: "assets.update_file",
+  description: "Rename or re-describe a Global File Asset. Provenance refs (workingBranchRef, baseBranchRef) and binary metadata (slotId, sha256, size, mimeType) are preserved verbatim.",
+  inputSchema: import_zod10.z.object({
+    id: import_zod10.z.string().min(1),
+    patch: import_zod10.z.object({
+      name: import_zod10.z.string().optional(),
+      description: import_zod10.z.string().nullable().optional()
+    }).strict()
+  }).strict(),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const existing = state.synced.globalAssets.files?.[input.id];
+    if (!existing) {
+      return { found: false, changedIds: [] };
+    }
+    const next = {
+      ...existing,
+      name: input.patch.name ?? existing.name,
+      description: input.patch.description === null ? void 0 : input.patch.description ?? existing.description
+    };
+    const out = await ctx.workspace.apply({ kind: "globalAsset.upsertFile", file: next });
+    return { found: true, id: next.id, changedIds: out.changedIds };
+  }
+};
+var globalAssetsFilesDeleteTool = {
+  name: "assets.delete_file",
+  description: "Delete a Global File Asset. Cascades \u2014 every request body and mock-response body that referenced the asset is unbound in the same mutation. The result envelope includes the consumer list that was cleared so the caller can report what changed.",
+  inputSchema: import_zod10.z.object({ id: import_zod10.z.string().min(1) }).strict(),
+  async handler(input, ctx) {
+    const before = await ctx.workspace.read();
+    const usage = before.local.assetUsageIndex?.[input.id] ?? {
+      requests: [],
+      mockEndpoints: [],
+      total: 0
+    };
+    const existing = before.synced.globalAssets.files?.[input.id];
+    if (!existing) {
+      return { found: false, changedIds: [] };
+    }
+    const out = await ctx.workspace.apply({ kind: "globalAsset.removeFile", id: input.id });
+    return {
+      found: true,
+      id: input.id,
+      filename: existing.filename,
+      unbound: {
+        requests: usage.requests,
+        mockEndpoints: usage.mockEndpoints,
+        total: usage.total
+      },
+      changedIds: out.changedIds
+    };
+  }
+};
+
+// src/tools/mocks.ts
+var import_zod11 = require("zod");
+var import_shared5 = require("@apicircle/shared");
 var import_mock_server_core2 = require("@apicircle/mock-server-core");
 async function ingestSource(source, name) {
   const { endpoints, warnings } = await (0, import_mock_server_core2.parseSourceToEndpoints)(source);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const mock = {
-    id: (0, import_shared4.generateId)(),
+    id: (0, import_shared5.generateId)(),
     name,
     source,
     endpoints,
@@ -2167,10 +2405,10 @@ async function ingestSource(source, name) {
 var mockCreateFromOpenApiTool = {
   name: "mock.create_from_openapi",
   description: "Create a mock server from an OpenAPI / Swagger spec (YAML or JSON).",
-  inputSchema: import_zod10.z.object({
-    name: import_zod10.z.string(),
-    spec: import_zod10.z.string().min(1),
-    format: import_zod10.z.enum(["json", "yaml"]).default("json")
+  inputSchema: import_zod11.z.object({
+    name: import_zod11.z.string(),
+    spec: import_zod11.z.string().min(1),
+    format: import_zod11.z.enum(["json", "yaml"]).default("json")
   }),
   async handler(input, ctx) {
     const { mock, warnings } = await ingestSource(
@@ -2189,7 +2427,7 @@ var mockCreateFromOpenApiTool = {
 var mockCreateFromPostmanTool = {
   name: "mock.create_from_postman",
   description: "Create a mock server from a Postman v2/v2.1 collection.",
-  inputSchema: import_zod10.z.object({ name: import_zod10.z.string(), collection: import_zod10.z.string().min(1) }),
+  inputSchema: import_zod11.z.object({ name: import_zod11.z.string(), collection: import_zod11.z.string().min(1) }),
   async handler(input, ctx) {
     const { mock, warnings } = await ingestSource(
       { kind: "postman", collection: input.collection },
@@ -2207,7 +2445,7 @@ var mockCreateFromPostmanTool = {
 var mockCreateFromInsomniaTool = {
   name: "mock.create_from_insomnia",
   description: "Create a mock server from an Insomnia v4 export.",
-  inputSchema: import_zod10.z.object({ name: import_zod10.z.string(), export: import_zod10.z.string().min(1) }),
+  inputSchema: import_zod11.z.object({ name: import_zod11.z.string(), export: import_zod11.z.string().min(1) }),
   async handler(input, ctx) {
     const { mock, warnings } = await ingestSource(
       { kind: "insomnia", export: input.export },
@@ -2225,7 +2463,7 @@ var mockCreateFromInsomniaTool = {
 var mockImportPostmanMockCollectionTool = {
   name: "mock.import_postman_mock_collection",
   description: "Import a Postman Mock Collection (collections previously hosted on Postman's mock service). Same parser as a regular Postman collection but marked as a mock import.",
-  inputSchema: import_zod10.z.object({ name: import_zod10.z.string(), collection: import_zod10.z.string().min(1) }),
+  inputSchema: import_zod11.z.object({ name: import_zod11.z.string(), collection: import_zod11.z.string().min(1) }),
   async handler(input, ctx) {
     const { mock, warnings } = await ingestSource(
       { kind: "postman", collection: input.collection },
@@ -2243,7 +2481,7 @@ var mockImportPostmanMockCollectionTool = {
 var mockListTool = {
   name: "mock.list",
   description: "List all mock servers in the workspace plus their runtime status (running / stopped, port).",
-  inputSchema: import_zod10.z.object({}),
+  inputSchema: import_zod11.z.object({}),
   async handler(_input, ctx) {
     const state = await ctx.workspace.read();
     const running = await ctx.mock.list();
@@ -2264,10 +2502,14 @@ var mockListTool = {
 };
 var mockStartTool = {
   name: "mock.start",
-  description: "Start a mock server by id. Returns the bound port. Errors if the mock is already running or the requested port is in use.",
-  inputSchema: import_zod10.z.object({
-    id: import_zod10.z.string(),
-    port: import_zod10.z.number().int().positive().optional()
+  description: "Start a mock server by id. Returns the bound port. Errors if the mock is already running or the requested port is in use. Optional `port` (1024-65535) overrides the saved `defaultPort` for this run only \u2014 to persist a new default port, use `mock.set_default_port`.",
+  inputSchema: import_zod11.z.object({
+    id: import_zod11.z.string(),
+    // Mirrors the UI 1024-65535 window: <1024 needs OS privileges, and
+    // outside that window the runtime would throw INVALID_PORT anyway —
+    // surface the rejection at the tool boundary so the client sees a
+    // schema error instead of a runtime exception.
+    port: import_zod11.z.number().int().min(1024).max(65535).optional()
   }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
@@ -2284,7 +2526,7 @@ var mockStartTool = {
 var mockStopTool = {
   name: "mock.stop",
   description: "Stop a running mock server by id (no-op if not running).",
-  inputSchema: import_zod10.z.object({ id: import_zod10.z.string() }),
+  inputSchema: import_zod11.z.object({ id: import_zod11.z.string() }),
   async handler(input, ctx) {
     try {
       await ctx.mock.stop(input.id);
@@ -2297,7 +2539,7 @@ var mockStopTool = {
 var mockDeleteTool = {
   name: "mock.delete",
   description: "Delete a mock server definition. Stops it first if it's running.",
-  inputSchema: import_zod10.z.object({ id: import_zod10.z.string() }),
+  inputSchema: import_zod11.z.object({ id: import_zod11.z.string() }),
   async handler(input, ctx) {
     try {
       await ctx.mock.stop(input.id);
@@ -2307,18 +2549,49 @@ var mockDeleteTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
-var HTTP_METHOD3 = import_zod10.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+var mockSetDefaultPortTool = {
+  name: "mock.set_default_port",
+  description: "Persist a new `defaultPort` on an existing mock server. Pass an integer 1024-65535 to pin the port, or `null` for 'pick a free port at next start'. Does NOT restart a running mock \u2014 the change takes effect on the next mock.start.",
+  inputSchema: import_zod11.z.object({
+    id: import_zod11.z.string(),
+    defaultPort: import_zod11.z.number().int().min(1024).max(65535).nullable()
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.id];
+    if (!mock) return { ok: false, error: "mock not found" };
+    if (mock.defaultPort === input.defaultPort) {
+      return { ok: true, defaultPort: mock.defaultPort, changed: false };
+    }
+    const next = {
+      ...mock,
+      defaultPort: input.defaultPort,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return {
+      ok: true,
+      defaultPort: input.defaultPort,
+      changed: true,
+      changedIds: out.changedIds
+    };
+  }
+};
+var HTTP_METHOD3 = import_zod11.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 var mockCreateManualTool = {
   name: "mock.create_manual",
   description: "Create an empty manual-mode mock server. Use `mock.add_endpoint` afterward to populate it. CORS defaults to off (same-origin only); enable + list explicit origins via `mock.update_cors` if cross-origin access is needed.",
-  inputSchema: import_zod10.z.object({
-    name: import_zod10.z.string().min(1),
-    defaultPort: import_zod10.z.number().int().positive().nullable().optional()
+  inputSchema: import_zod11.z.object({
+    name: import_zod11.z.string().min(1),
+    // Same 1024-65535 window as mock.start / mock.set_default_port — pin
+    // the validation at the tool boundary so a malformed AI call doesn't
+    // persist a port the runtime will later reject as INVALID_PORT.
+    defaultPort: import_zod11.z.number().int().min(1024).max(65535).nullable().optional()
   }),
   async handler(input, ctx) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const mock = {
-      id: (0, import_shared4.generateId)(),
+      id: (0, import_shared5.generateId)(),
       name: input.name,
       source: { kind: "manual", endpoints: [] },
       endpoints: [],
@@ -2336,7 +2609,7 @@ var mockCreateManualTool = {
 var mockListEndpointsTool = {
   name: "mock.list_endpoints",
   description: "List endpoints for a mock server (id, method, path, name).",
-  inputSchema: import_zod10.z.object({ mockId: import_zod10.z.string() }),
+  inputSchema: import_zod11.z.object({ mockId: import_zod11.z.string() }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
     const mock = state.synced.mockServers[input.mockId];
@@ -2355,10 +2628,10 @@ var mockListEndpointsTool = {
     };
   }
 };
-var ENDPOINT_RESPONSE2 = import_zod10.z.object({
-  status: import_zod10.z.number().int().min(100).max(599).default(200),
-  jsonBody: import_zod10.z.string().default("{}"),
-  contentType: import_zod10.z.string().default("application/json")
+var ENDPOINT_RESPONSE2 = import_zod11.z.object({
+  status: import_zod11.z.number().int().min(100).max(599).default(200),
+  jsonBody: import_zod11.z.string().default("{}"),
+  contentType: import_zod11.z.string().default("application/json")
 });
 function buildDefaultEndpoint(args) {
   const response = args.response ?? {
@@ -2368,16 +2641,16 @@ function buildDefaultEndpoint(args) {
   };
   const headers = [{ key: "Content-Type", value: response.contentType, enabled: true }];
   return {
-    id: (0, import_shared4.generateId)(),
+    id: (0, import_shared5.generateId)(),
     name: args.name ?? `${args.method} ${args.pathPattern}`,
     method: args.method,
     pathPattern: args.pathPattern,
     description: args.description,
-    requestSchema: (0, import_shared4.makeDefaultRequestSchema)(),
+    requestSchema: (0, import_shared5.makeDefaultRequestSchema)(),
     requestValidation: [],
     responseRules: [],
     defaultResponse: {
-      ...(0, import_shared4.makeDefaultMockResponse)(),
+      ...(0, import_shared5.makeDefaultMockResponse)(),
       status: response.status,
       headers,
       body: { type: "json", content: response.jsonBody }
@@ -2387,12 +2660,12 @@ function buildDefaultEndpoint(args) {
 var mockAddEndpointTool = {
   name: "mock.add_endpoint",
   description: "Append a new endpoint to a mock server. Defaults to a 200 JSON response of `{}`. Returns the new endpoint id.",
-  inputSchema: import_zod10.z.object({
-    mockId: import_zod10.z.string(),
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
     method: HTTP_METHOD3,
-    pathPattern: import_zod10.z.string().min(1),
-    name: import_zod10.z.string().optional(),
-    description: import_zod10.z.string().optional(),
+    pathPattern: import_zod11.z.string().min(1),
+    name: import_zod11.z.string().optional(),
+    description: import_zod11.z.string().optional(),
     response: ENDPOINT_RESPONSE2.optional()
   }),
   async handler(input, ctx) {
@@ -2415,13 +2688,13 @@ var mockAddEndpointTool = {
 var mockUpdateEndpointTool = {
   name: "mock.update_endpoint",
   description: "Patch fields on a single mock endpoint (method, pathPattern, name, description, defaultResponse status / contentType / json body). Pass only the fields you want to change.",
-  inputSchema: import_zod10.z.object({
-    mockId: import_zod10.z.string(),
-    endpointId: import_zod10.z.string(),
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
     method: HTTP_METHOD3.optional(),
-    pathPattern: import_zod10.z.string().optional(),
-    name: import_zod10.z.string().optional(),
-    description: import_zod10.z.string().optional(),
+    pathPattern: import_zod11.z.string().optional(),
+    name: import_zod11.z.string().optional(),
+    description: import_zod11.z.string().optional(),
     response: ENDPOINT_RESPONSE2.partial().optional()
   }),
   async handler(input, ctx) {
@@ -2462,7 +2735,7 @@ var mockUpdateEndpointTool = {
 var mockDeleteEndpointTool = {
   name: "mock.delete_endpoint",
   description: "Remove an endpoint from a mock server.",
-  inputSchema: import_zod10.z.object({ mockId: import_zod10.z.string(), endpointId: import_zod10.z.string() }),
+  inputSchema: import_zod11.z.object({ mockId: import_zod11.z.string(), endpointId: import_zod11.z.string() }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
     const mock = state.synced.mockServers[input.mockId];
@@ -2482,9 +2755,9 @@ var mockDeleteEndpointTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
-var VALIDATION_RULE = import_zod10.z.object({
-  id: import_zod10.z.string().optional(),
-  kind: import_zod10.z.enum([
+var VALIDATION_RULE = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  kind: import_zod11.z.enum([
     "header-required",
     "header-equals",
     "header-matches",
@@ -2495,43 +2768,46 @@ var VALIDATION_RULE = import_zod10.z.object({
     "body-required",
     "content-type-equals"
   ]),
-  target: import_zod10.z.string().default(""),
-  expected: import_zod10.z.string().optional(),
-  message: import_zod10.z.string().optional(),
-  enabled: import_zod10.z.boolean().default(true),
-  failResponse: import_zod10.z.object({
-    status: import_zod10.z.number().int().min(100).max(599).default(400),
-    jsonBody: import_zod10.z.string().default('{"error":"validation failed"}')
+  target: import_zod11.z.string().default(""),
+  expected: import_zod11.z.string().optional(),
+  message: import_zod11.z.string().optional(),
+  enabled: import_zod11.z.boolean().default(true),
+  failResponse: import_zod11.z.object({
+    status: import_zod11.z.number().int().min(100).max(599).default(400),
+    jsonBody: import_zod11.z.string().default('{"error":"validation failed"}')
   }).default({})
 });
-var CONDITION_CLAUSE = import_zod10.z.object({
-  id: import_zod10.z.string().optional(),
-  scope: import_zod10.z.enum(["query", "pathParam", "header", "cookie", "body-json-path"]),
-  target: import_zod10.z.string(),
-  op: import_zod10.z.enum(["equals", "not-equals", "matches", "gt", "lt", "gte", "lte", "present", "absent"]),
-  value: import_zod10.z.string().optional()
+var CONDITION_CLAUSE = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  scope: import_zod11.z.enum(["query", "pathParam", "header", "cookie", "body-json-path"]),
+  target: import_zod11.z.string(),
+  op: import_zod11.z.enum(["equals", "not-equals", "matches", "gt", "lt", "gte", "lte", "present", "absent"]),
+  value: import_zod11.z.string().optional()
 });
-var RESPONSE_RULE = import_zod10.z.object({
-  id: import_zod10.z.string().optional(),
-  name: import_zod10.z.string(),
-  enabled: import_zod10.z.boolean().default(true),
-  when: import_zod10.z.array(CONDITION_CLAUSE).default([]),
-  response: import_zod10.z.object({
-    status: import_zod10.z.number().int().min(100).max(599).default(200),
-    jsonBody: import_zod10.z.string().default("{}")
+var RESPONSE_RULE = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  name: import_zod11.z.string(),
+  enabled: import_zod11.z.boolean().default(true),
+  // At least one clause — a rule with no `when` is dead (the runtime engine
+  // skips clause-less rules), so it can never fire. The VS Code endpoint parser
+  // rejects the same shape, keeping the surfaces consistent.
+  when: import_zod11.z.array(CONDITION_CLAUSE).min(1),
+  response: import_zod11.z.object({
+    status: import_zod11.z.number().int().min(100).max(599).default(200),
+    jsonBody: import_zod11.z.string().default("{}")
   }).default({})
 });
-var MULTIPLIER = import_zod10.z.object({
-  id: import_zod10.z.string().optional(),
-  name: import_zod10.z.string().optional(),
-  source: import_zod10.z.object({
-    kind: import_zod10.z.enum(["query", "pathParam", "header", "body-json-path"]),
-    key: import_zod10.z.string()
-  }),
-  targetJsonPath: import_zod10.z.string(),
-  defaultCount: import_zod10.z.number().int().nonnegative().default(0),
-  min: import_zod10.z.number().int().nonnegative().optional(),
-  max: import_zod10.z.number().int().nonnegative().optional()
+var MULTIPLIER = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  name: import_zod11.z.string().optional(),
+  source: import_zod11.z.object({
+    kind: import_zod11.z.enum(["query", "pathParam", "header", "body-json-path"]),
+    key: import_zod11.z.string()
+  }),
+  targetJsonPath: import_zod11.z.string(),
+  defaultCount: import_zod11.z.number().int().nonnegative().default(0),
+  min: import_zod11.z.number().int().nonnegative().optional(),
+  max: import_zod11.z.number().int().nonnegative().optional()
 });
 function defaultJsonResponseConfig(args) {
   return {
@@ -2556,10 +2832,10 @@ function patchEndpoint2(mock, endpointId, patcher) {
 var mockSetValidationRulesTool = {
   name: "mock.set_validation_rules",
   description: "Replace an endpoint's validation rules. Rules without an `id` get a fresh one; existing rules can keep theirs to preserve client-side selection state. Empty array clears all rules.",
-  inputSchema: import_zod10.z.object({
-    mockId: import_zod10.z.string(),
-    endpointId: import_zod10.z.string(),
-    rules: import_zod10.z.array(VALIDATION_RULE)
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
+    rules: import_zod11.z.array(VALIDATION_RULE)
   }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
@@ -2569,7 +2845,7 @@ var mockSetValidationRulesTool = {
     const next = patchEndpoint2(mock, input.endpointId, (e) => ({
       ...e,
       requestValidation: rules.map((r) => ({
-        id: r.id ?? (0, import_shared4.generateId)(),
+        id: r.id ?? (0, import_shared5.generateId)(),
         kind: r.kind,
         target: r.target,
         expected: r.expected,
@@ -2586,10 +2862,10 @@ var mockSetValidationRulesTool = {
 var mockSetResponseRulesTool = {
   name: "mock.set_response_rules",
   description: "Replace an endpoint's conditional response rules. Rules fire in order; the first whose every clause matches wins. Disabled rules are skipped. Empty array falls back to defaultResponse.",
-  inputSchema: import_zod10.z.object({
-    mockId: import_zod10.z.string(),
-    endpointId: import_zod10.z.string(),
-    rules: import_zod10.z.array(RESPONSE_RULE)
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
+    rules: import_zod11.z.array(RESPONSE_RULE)
   }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
@@ -2599,11 +2875,11 @@ var mockSetResponseRulesTool = {
     const next = patchEndpoint2(mock, input.endpointId, (e) => ({
       ...e,
       responseRules: rules.map((r) => ({
-        id: r.id ?? (0, import_shared4.generateId)(),
+        id: r.id ?? (0, import_shared5.generateId)(),
         name: r.name,
         enabled: r.enabled,
         when: r.when.map((c) => ({
-          id: c.id ?? (0, import_shared4.generateId)(),
+          id: c.id ?? (0, import_shared5.generateId)(),
           scope: c.scope,
           target: c.target,
           op: c.op,
@@ -2617,25 +2893,80 @@ var mockSetResponseRulesTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
+var PARAM = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  name: import_zod11.z.string(),
+  typeHint: import_zod11.z.string().optional(),
+  required: import_zod11.z.boolean().optional(),
+  description: import_zod11.z.string().optional(),
+  example: import_zod11.z.string().optional()
+});
+var REQUEST_SCHEMA_BODY = import_zod11.z.object({ description: import_zod11.z.string().optional(), example: import_zod11.z.string().optional() }).optional();
+function normalizeSchemaBody(body) {
+  if (!body || !body.description && !body.example) return void 0;
+  return body;
+}
+var mockSetRequestSchemaTool = {
+  name: "mock.set_request_schema",
+  description: "Replace an endpoint's requestSchema \u2014 the declared path / query / header / cookie params plus an optional body-shape doc. Params without an `id` get a fresh one; omitted lists are cleared. Documentation-only (drives the editor UI + OpenAPI export); runtime gating lives in the validation rules.",
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
+    pathParams: import_zod11.z.array(PARAM).default([]),
+    queryParams: import_zod11.z.array(PARAM).default([]),
+    headers: import_zod11.z.array(PARAM).default([]),
+    cookies: import_zod11.z.array(PARAM).default([]),
+    body: REQUEST_SCHEMA_BODY
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.mockId];
+    if (!mock) return { ok: false, error: "mock not found" };
+    const toParams = (list) => list.map((p) => ({
+      id: p.id ?? (0, import_shared5.generateId)(),
+      name: p.name,
+      typeHint: p.typeHint,
+      required: p.required,
+      description: p.description,
+      example: p.example
+    }));
+    const next = patchEndpoint2(mock, input.endpointId, (e) => ({
+      ...e,
+      requestSchema: {
+        pathParams: toParams(input.pathParams),
+        queryParams: toParams(input.queryParams),
+        headers: toParams(input.headers),
+        cookies: toParams(input.cookies),
+        body: normalizeSchemaBody(input.body)
+      }
+    }));
+    if (!next) return { ok: false, error: "endpoint not found" };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
 var mockSetMultipliersTool = {
   name: "mock.set_multipliers",
-  description: "Replace the response multipliers on an endpoint's defaultResponse. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Empty array clears all multipliers.",
-  inputSchema: import_zod10.z.object({
-    mockId: import_zod10.z.string(),
-    endpointId: import_zod10.z.string(),
-    multipliers: import_zod10.z.array(MULTIPLIER)
+  description: "Replace the response multipliers on an endpoint's defaultResponse. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Empty array clears all. The list is currently capped at MAX_RESPONSE_MULTIPLIERS (1) \u2014 passing more is rejected.",
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
+    multipliers: import_zod11.z.array(MULTIPLIER)
   }),
   async handler(input, ctx) {
     const state = await ctx.workspace.read();
     const mock = state.synced.mockServers[input.mockId];
     if (!mock) return { ok: false, error: "mock not found" };
     const multipliers = input.multipliers;
+    if (multipliers.length > import_shared5.MAX_RESPONSE_MULTIPLIERS) {
+      return { ok: false, error: "too many multipliers" };
+    }
     const next = patchEndpoint2(mock, input.endpointId, (e) => ({
       ...e,
       defaultResponse: {
         ...e.defaultResponse,
         multipliers: multipliers.length === 0 ? void 0 : multipliers.map((m) => ({
-          id: m.id ?? (0, import_shared4.generateId)(),
+          id: m.id ?? (0, import_shared5.generateId)(),
           name: m.name,
           source: { kind: m.source.kind, key: m.source.key },
           targetJsonPath: m.targetJsonPath,
@@ -2651,132 +2982,1438 @@ var mockSetMultipliersTool = {
   }
 };
 
-// src/tools/registry.ts
-var TOOL_REGISTRY = [
-  importCurlTool,
-  importOpenApiTool,
-  importPostmanTool,
-  importInsomniaTool,
-  importHarTool,
-  generateCodeTool,
-  workspaceListTool,
-  workspaceReadTool,
-  workspaceWriteTool,
-  requestCreateTool,
-  requestReadTool,
-  requestUpdateTool,
-  requestDeleteTool,
-  folderCreateTool,
-  folderReadTool,
-  folderUpdateTool,
-  folderDeleteTool,
-  folderExportJsonTool,
-  folderImportJsonTool,
-  environmentCreateTool,
-  environmentReadTool,
-  environmentUpdateTool,
-  environmentDeleteTool,
-  environmentSetActiveTool,
-  environmentSetPriorityTool,
-  environmentExportTool,
-  environmentImportTool,
-  planCreateTool,
-  planRunTool,
-  planReadTool,
-  planUpdateTool,
-  planDeleteTool,
-  planAddStepTool,
-  planRemoveStepTool,
-  planReorderStepsTool,
-  planSetVariablesTool,
-  assertionCreateTool,
-  assertionReadTool,
-  assertionUpdateTool,
-  assertionDeleteTool,
-  historyListRunsTool,
-  historyGetRunTool,
-  historyDeleteRunTool,
-  historyPurgeTool,
-  codebaseExtractCollectionTool,
-  promptCreateEnvironmentTool,
-  promptCreateAssertionTool,
-  promptCreatePlanTool,
-  promptCreateRequestTool,
-  promptUpdateRequestTool,
-  promptCreateFolderTreeTool,
-  promptAddPlanStepsTool,
-  promptSetPlanVariablesTool,
-  promptCreateMockServerTool,
-  promptAddMockEndpointTool,
-  promptSetEndpointValidationRulesTool,
-  promptSetEndpointResponseRulesTool,
-  promptSetEndpointMultipliersTool,
-  mockCreateFromOpenApiTool,
-  mockCreateFromPostmanTool,
-  mockCreateFromInsomniaTool,
-  mockCreateManualTool,
-  mockListTool,
-  mockListEndpointsTool,
-  mockStartTool,
-  mockStopTool,
-  mockDeleteTool,
-  mockAddEndpointTool,
-  mockUpdateEndpointTool,
-  mockDeleteEndpointTool,
-  mockSetValidationRulesTool,
-  mockSetResponseRulesTool,
-  mockSetMultipliersTool,
-  mockImportPostmanMockCollectionTool
-];
-function getTool(name) {
-  return TOOL_REGISTRY.find((t) => t.name === name);
-}
-
-// src/providers/Workspaces.ts
-var SingleWorkspaceAdapter = class {
-  constructor(provider, workspaceId, displayName = "Workspace") {
-    this.provider = provider;
-    this.workspaceId = workspaceId;
-    this.displayName = displayName;
-  }
-  provider;
-  workspaceId;
-  displayName;
-  async list() {
-    const state = await this.provider.read();
-    const id = state.synced.workspaceId;
-    this.workspaceId = id;
-    return [
-      {
-        id,
-        name: this.displayName,
-        isActive: true,
-        createdAt: state.synced.meta.createdAt,
-        lastOpenedAt: state.synced.meta.updatedAt,
-        counts: {
-          requests: Object.keys(state.synced.collections.requests).length,
-          folders: Object.keys(state.synced.collections.folders).length,
-          environments: Object.keys(state.synced.environments.items).length,
-          mockServers: Object.keys(state.synced.mockServers ?? {}).length,
-          plans: Object.keys(state.synced.executionPlans ?? {}).length
-        }
-      }
-    ];
-  }
-  for(workspaceId) {
-    if (this.workspaceId && workspaceId !== this.workspaceId) {
-      throw new WorkspaceNotFoundError(workspaceId);
+// src/tools/releases.ts
+var import_zod12 = require("zod");
+var import_core4 = require("@apicircle/core");
+var releaseListTool = {
+  name: "release.list",
+  description: "List this workspace's published releases (newest first) with their notes, snapshot fingerprint, and deprecated / withdrawn flags. Returns the current version too.",
+  inputSchema: import_zod12.z.object({}),
+  async handler(_input, ctx) {
+    const state = await ctx.workspace.read();
+    const ledger = state.synced.releases.self;
+    if (!ledger) {
+      return { currentVersion: null, count: 0, versions: [] };
     }
-    return this.provider;
-  }
-  activeId() {
-    return this.workspaceId;
+    const order = (0, import_core4.sortVersionsDesc)(ledger.versions.map((v) => v.version));
+    const byVersion = new Map(ledger.versions.map((v) => [v.version, v]));
+    const versions = order.map((v) => byVersion.get(v)).filter((v) => v !== void 0).map((v) => ({
+      version: v.version,
+      publishedAt: v.publishedAt,
+      notes: v.notes,
+      workspaceSnapshot: v.workspaceSnapshot,
+      deprecated: v.deprecated,
+      yanked: v.yanked,
+      ...v.sha ? { sha: v.sha } : {},
+      ...v.tagName ? { tagName: v.tagName } : {}
+    }));
+    return { currentVersion: ledger.currentVersion, count: versions.length, versions };
   }
-  setActive(workspaceId) {
-    if (this.workspaceId && workspaceId !== this.workspaceId) {
-      throw new WorkspaceNotFoundError(workspaceId);
+};
+var releasePublishTool = {
+  name: "release.publish",
+  description: "Publish a new release of this workspace. Appends a semver version + markdown notes to the ledger and bumps currentVersion. The release is fingerprinted with a SHA-256 of the workspace at publish time. Rejects invalid semver or a duplicate version. Does NOT create a Git tag or GitHub Release.",
+  inputSchema: import_zod12.z.object({
+    version: import_zod12.z.string().min(1).describe('Semantic version, e.g. "1.2.0".'),
+    notes: import_zod12.z.string().default("").describe("Markdown release notes."),
+    sha: import_zod12.z.string().optional().describe("Optional source commit SHA for bookkeeping."),
+    tagName: import_zod12.z.string().optional().describe("Optional git tag name for bookkeeping.")
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    let entry;
+    try {
+      entry = await (0, import_core4.buildReleaseEntry)(state.synced, {
+        version: input.version,
+        notes: input.notes,
+        sha: input.sha,
+        tagName: input.tagName
+      });
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.publish failed" };
+    }
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.publish", entry });
+      const after = (await ctx.workspace.read()).synced.releases.self;
+      return {
+        ok: true,
+        version: entry.version,
+        currentVersion: after?.currentVersion ?? entry.version,
+        workspaceSnapshot: entry.workspaceSnapshot,
+        changedIds: out.changedIds
+      };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.publish failed" };
     }
-    return Promise.resolve();
+  }
+};
+var releaseDeprecateTool = {
+  name: "release.deprecate",
+  description: "Mark a published version as deprecated (soft signal). Consumers see a warning but the version stays installable. Errors if the version is unknown or no ledger exists.",
+  inputSchema: import_zod12.z.object({ version: import_zod12.z.string().min(1) }),
+  async handler(input, ctx) {
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.deprecate", version: input.version });
+      return { ok: true, version: input.version, changedIds: out.changedIds };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.deprecate failed" };
+    }
+  }
+};
+var releaseYankTool = {
+  name: "release.yank",
+  description: "Withdraw (yank) a published version (hard signal). Consumers are warned the version is broken / unsafe and told to move to a different one. The entry stays in the ledger. Errors if the version is unknown or no ledger exists.",
+  inputSchema: import_zod12.z.object({ version: import_zod12.z.string().min(1) }),
+  async handler(input, ctx) {
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.yank", version: input.version });
+      return { ok: true, version: input.version, changedIds: out.changedIds };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.yank failed" };
+    }
+  }
+};
+
+// src/tools/linkedWorkspaces.ts
+var import_zod13 = require("zod");
+function summarize(link, currentVersion) {
+  return {
+    id: link.id,
+    name: link.name,
+    kind: link.kind,
+    description: link.description,
+    source: link.source,
+    scope: link.scope,
+    pinnedVersion: link.pinnedVersion,
+    requiredSecretKeyIds: link.requiredSecretKeyIds,
+    marketplace: link.marketplace,
+    cachedCurrentVersion: currentVersion
+  };
+}
+var linkedListTool = {
+  name: "linked.list",
+  description: "List the workspaces this workspace links to (consumes). Each entry includes its source repo/branch, scope, pinned version, required secret-key ids, and the current version of its cached release ledger.",
+  inputSchema: import_zod13.z.object({}),
+  async handler(_input, ctx) {
+    const state = await ctx.workspace.read();
+    const links = Object.values(state.synced.linkedWorkspaces);
+    return {
+      count: links.length,
+      links: links.map(
+        (l) => summarize(l, state.synced.releases.perLink[l.id]?.currentVersion ?? null)
+      )
+    };
+  }
+};
+var linkedGetTool = {
+  name: "linked.get",
+  description: "Read one linked workspace by id, including its cached release ledger (the versions available to pin to).",
+  inputSchema: import_zod13.z.object({ id: import_zod13.z.string() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    const ledger = state.synced.releases.perLink[input.id] ?? null;
+    return {
+      ok: true,
+      link: summarize(link, ledger?.currentVersion ?? null),
+      ledger
+    };
+  }
+};
+var linkedSetConfigTool = {
+  name: "linked.set_config",
+  description: "Update an existing linked workspace's config: rename, pin/unpin a version (must exist in the cached ledger), set scope, session mode, required secret-key ids, or marketplace metadata. Only supplied fields change. Does NOT fetch from the network.",
+  inputSchema: import_zod13.z.object({
+    id: import_zod13.z.string(),
+    name: import_zod13.z.string().optional(),
+    description: import_zod13.z.string().optional(),
+    pinnedVersion: import_zod13.z.string().nullable().optional().describe("null = unpin (track source HEAD)."),
+    scope: import_zod13.z.array(import_zod13.z.enum(["collections", "environments"])).optional(),
+    sessionMode: import_zod13.z.enum(["workspace", "dedicated"]).optional(),
+    requiredSecretKeyIds: import_zod13.z.array(import_zod13.z.string()).optional(),
+    marketplace: import_zod13.z.object({
+      listedAs: import_zod13.z.string(),
+      tags: import_zod13.z.array(import_zod13.z.string()),
+      summary: import_zod13.z.string()
+    }).nullable().optional().describe("null = clear marketplace metadata.")
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    if (input.pinnedVersion !== void 0 && input.pinnedVersion !== null) {
+      const cached = state.synced.releases.perLink[input.id]?.versions ?? [];
+      if (!cached.some((v) => v.version === input.pinnedVersion)) {
+        return {
+          ok: false,
+          error: `Version ${input.pinnedVersion} is not in the cached ledger \u2014 refresh the link first`
+        };
+      }
+    }
+    const next = {
+      ...link,
+      ...input.name !== void 0 ? { name: input.name } : {},
+      ...input.description !== void 0 ? { description: input.description } : {},
+      ...input.pinnedVersion !== void 0 ? { pinnedVersion: input.pinnedVersion } : {},
+      ...input.scope !== void 0 ? { scope: input.scope } : {},
+      ...input.requiredSecretKeyIds !== void 0 ? { requiredSecretKeyIds: input.requiredSecretKeyIds } : {},
+      ...input.sessionMode !== void 0 ? { source: { ...link.source, sessionMode: input.sessionMode } } : {}
+    };
+    if (input.marketplace !== void 0) {
+      if (input.marketplace === null) {
+        delete next.marketplace;
+      } else {
+        next.marketplace = input.marketplace;
+      }
+    }
+    const out = await ctx.workspace.apply({ kind: "linkedWorkspace.upsert", link: next });
+    return {
+      ok: true,
+      changedIds: out.changedIds,
+      link: summarize(next, state.synced.releases.perLink[input.id]?.currentVersion ?? null)
+    };
+  }
+};
+var linkedUnlinkTool = {
+  name: "linked.unlink",
+  description: "Unlink a workspace by id. Removes the link, its cached release ledger, every local override for it, the cached collections/environments snapshot, and any per-link session entry. The source repo is untouched.",
+  inputSchema: import_zod13.z.object({ id: import_zod13.z.string() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    if (!state.synced.linkedWorkspaces[input.id]) {
+      return { ok: false, error: `Linked workspace ${input.id} not found` };
+    }
+    const out = await ctx.workspace.apply({ kind: "linkedWorkspace.remove", id: input.id });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
+
+// src/tools/githubOps.ts
+var import_zod14 = require("zod");
+var import_core5 = require("@apicircle/core");
+var import_shared6 = require("@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 path2 = `/search/repositories?q=${encodeURIComponent(fullQuery)}&per_page=30${sortParam}`;
+    const { json } = await this.call(token, path2, 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, path2, ref, opts = {}) {
+    const query = `?ref=${encodeURIComponent(ref)}`;
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path2.split("/").map(encodeURIComponent).join("/")}${query}`,
+        opts
+      );
+      if (Array.isArray(json) || json.type !== "file") {
+        throw new GitHubError(`Path ${path2} 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, path2, 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/${path2.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, path2, ref, opts = {}) {
+    const query = `?ref=${encodeURIComponent(ref)}`;
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path2.split("/").map(encodeURIComponent).join("/")}${query}`,
+        opts
+      );
+      if (Array.isArray(json) || json.type !== "file") {
+        throw new GitHubError(`Path ${path2} 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, path2, opts = {}) {
+    const url = path2.startsWith("http") ? path2 : `${this.baseUrl}${path2}`;
+    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/tools/githubOps.ts
+function resolveToken(input) {
+  const t = (input ?? process.env.GITHUB_TOKEN ?? "").trim();
+  return t;
+}
+var TOKEN_HELP = "Pass `token`, or set the GITHUB_TOKEN env var on the MCP process.";
+var linkedLinkTool = {
+  name: "linked.link",
+  description: "Link a workspace by fetching its `.apicircle/` workspace from GitHub (registry.json \u2192 workspace-<id>/workspace.json). Caches the release ledger + a collections/environments snapshot. Needs a token for private repos. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    repoFullName: import_zod14.z.string().describe("owner/name of the source workspace repo."),
+    branch: import_zod14.z.string().default("main"),
+    pinnedVersion: import_zod14.z.string().nullable().optional().describe("null/omitted = source current version."),
+    kind: import_zod14.z.enum(["private", "public"]).default("private"),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, ctx) {
+    const token = resolveToken(input.token);
+    const repoFullName = input.repoFullName.trim();
+    if (!repoFullName.includes("/")) return { ok: false, error: "repoFullName must be owner/name" };
+    if (input.kind === "private" && !token)
+      return { ok: false, error: `A token is required for private repos. ${TOKEN_HELP}` };
+    const [owner, name] = repoFullName.split("/", 2);
+    const state = await ctx.workspace.read();
+    const dup = Object.values(state.synced.linkedWorkspaces).find(
+      (l) => l.source.repoFullName === repoFullName && l.source.branch === input.branch
+    );
+    if (dup)
+      return { ok: false, error: `Already linked to ${repoFullName}@${input.branch} (${dup.id})` };
+    const client = new GitHubClient();
+    let result;
+    try {
+      result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+        const f = await client.getContents(token, owner, name, p, input.branch);
+        return f?.content ?? null;
+      });
+    } catch (e) {
+      return {
+        ok: false,
+        error: e instanceof GitHubError ? e.message : e instanceof Error ? e.message : "fetch failed"
+      };
+    }
+    if ("error" in result)
+      return { ok: false, error: `${repoFullName}@${input.branch}: ${result.error}` };
+    const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+    const ledger = (0, import_core5.ledgerFromProbe)(probe);
+    const link = {
+      id: (0, import_shared6.generateId)(),
+      kind: input.kind,
+      name: repoFullName,
+      sourceWorkspaceId: result.workspaceId,
+      source: { provider: "github", repoFullName, branch: input.branch, sessionMode: "workspace" },
+      scope: ["collections", "environments"],
+      pinnedVersion: input.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 = await ctx.workspace.apply({
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    return { ok: true, id: link.id, pinnedVersion: link.pinnedVersion, changedIds: out.changedIds };
+  }
+};
+var linkedRefreshTool = {
+  name: "linked.refresh",
+  description: "Re-pull a linked workspace's cached release ledger (+ bootstrap snapshot if missing) from GitHub. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({ id: import_zod14.z.string(), token: import_zod14.z.string().optional() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    const token = resolveToken(input.token);
+    if (link.kind === "private" && !token)
+      return { ok: false, error: `A token is required for private links. ${TOKEN_HELP}` };
+    const [owner, name] = link.source.repoFullName.split("/", 2);
+    const client = new GitHubClient();
+    let result;
+    try {
+      result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+        const f = await client.getContents(token, owner, name, p, link.source.branch);
+        return f?.content ?? null;
+      });
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "fetch failed" };
+    }
+    if ("error" in result)
+      return {
+        ok: false,
+        error: `${link.source.repoFullName}@${link.source.branch}: ${result.error}`
+      };
+    const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+    const ledger = (0, import_core5.ledgerFromProbe)(probe);
+    const needsSnapshot = !state.local.linkedCollections[input.id];
+    const snapshot = needsSnapshot ? (0, import_core5.buildLinkedSnapshot)(probe, link) ?? void 0 : void 0;
+    await ctx.workspace.apply({
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    return {
+      ok: true,
+      currentVersion: ledger.currentVersion,
+      versionCount: ledger.versions.length
+    };
+  }
+};
+var releaseTagTool = {
+  name: "release.tag",
+  description: "Create a `v<version>` Git tag (optionally a GitHub Release) on the workspace's own repo. The version should already exist in the release ledger. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    owner: import_zod14.z.string(),
+    name: import_zod14.z.string(),
+    version: import_zod14.z.string(),
+    createGitHubRelease: import_zod14.z.boolean().default(false),
+    notes: import_zod14.z.string().optional(),
+    overrideExisting: import_zod14.z.boolean().default(false),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token);
+    if (!token) return { ok: false, error: `A token is required to tag. ${TOKEN_HELP}` };
+    const client = new GitHubClient();
+    const tagName = `v${input.version.replace(/^v/, "")}`;
+    try {
+      const repo = await client.getRepo(token, input.owner, input.name);
+      const ref = await client.getRef(token, input.owner, input.name, repo.defaultBranch);
+      const existing = await client.getTagSha(token, input.owner, input.name, tagName);
+      if (existing !== null) {
+        if (!input.overrideExisting) {
+          return {
+            ok: false,
+            error: `Tag ${tagName} already exists at ${existing.slice(0, 7)}. Pass overrideExisting:true to replace.`
+          };
+        }
+        await client.deleteRef(token, input.owner, input.name, `tags/${tagName}`);
+      }
+      await client.createTag(token, input.owner, input.name, { tagName, sha: ref.sha });
+      let releaseUrl;
+      if (input.createGitHubRelease) {
+        const release = await client.createRelease(token, input.owner, input.name, {
+          tagName,
+          releaseName: tagName,
+          body: input.notes ?? ""
+        });
+        releaseUrl = release.htmlUrl;
+      }
+      return {
+        ok: true,
+        tagName,
+        sha: ref.sha,
+        branch: repo.defaultBranch,
+        ...releaseUrl ? { releaseUrl } : {}
+      };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "tag failed" };
+    }
+  }
+};
+var marketplaceSearchTool = {
+  name: "marketplace.search",
+  description: "Search the API Circle marketplace for public workspaces tagged with `apicircle` on GitHub. Returns up to 30 results sorted by relevance (default), stars, or recent updates. Token is optional \u2014 anonymous browsing is supported (lower rate limits); pass a token to lift them. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    query: import_zod14.z.string().default("").describe("Search query \u2014 matches repo name, description, and topics. Empty = browse all."),
+    sort: import_zod14.z.enum(["best-match", "stars", "updated"]).default("best-match").describe(
+      "Sort order: best-match (default relevance), stars (most starred first), updated (recently pushed first)."
+    ),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token) || null;
+    const client = new GitHubClient();
+    try {
+      const repos = await client.searchMarketplaceRepos(token, input.query, {
+        sort: input.sort === "best-match" ? void 0 : input.sort
+      });
+      return { ok: true, count: repos.length, results: repos };
+    } catch (e) {
+      return {
+        ok: false,
+        error: e instanceof GitHubError ? e.message : e instanceof Error ? e.message : "search failed"
+      };
+    }
+  }
+};
+var TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+var repoSetTopicsTool = {
+  name: "repo.set_topics",
+  description: "Replace a repo's topics (the `apicircle` topic is always kept \u2014 it drives marketplace discovery). Topics must be lowercase, start with a letter/digit, \u226450 chars, \u226420 total. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    owner: import_zod14.z.string(),
+    name: import_zod14.z.string(),
+    topics: import_zod14.z.array(import_zod14.z.string()),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token);
+    if (!token) return { ok: false, error: `A token is required to set topics. ${TOKEN_HELP}` };
+    const requested = input.topics;
+    const normalized = Array.from(
+      /* @__PURE__ */ new Set(["apicircle", ...requested.map((t) => t.trim().toLowerCase()).filter(Boolean)])
+    );
+    for (const t of normalized) {
+      if (!TOPIC_RE.test(t))
+        return {
+          ok: false,
+          error: `Invalid topic "${t}" \u2014 lowercase letters/digits/"-", starting with a letter or digit.`
+        };
+      if (t.length > 50) return { ok: false, error: `Topic "${t}" exceeds 50 characters.` };
+    }
+    if (normalized.length > 20) return { ok: false, error: "GitHub allows at most 20 topics." };
+    const client = new GitHubClient();
+    try {
+      const saved = await client.setRepoTopics(token, input.owner, input.name, normalized);
+      return { ok: true, topics: saved };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "set topics failed" };
+    }
+  }
+};
+
+// src/tools/registry.ts
+var TOOL_REGISTRY = [
+  importCurlTool,
+  importOpenApiTool,
+  importPostmanTool,
+  importInsomniaTool,
+  importHarTool,
+  generateCodeTool,
+  workspaceListTool,
+  workspaceReadTool,
+  workspaceWriteTool,
+  requestCreateTool,
+  requestReadTool,
+  requestUpdateTool,
+  requestDeleteTool,
+  folderCreateTool,
+  folderReadTool,
+  folderUpdateTool,
+  folderDeleteTool,
+  folderExportJsonTool,
+  folderImportJsonTool,
+  environmentCreateTool,
+  environmentReadTool,
+  environmentUpdateTool,
+  environmentDeleteTool,
+  environmentSetActiveTool,
+  environmentSetPriorityTool,
+  environmentExportTool,
+  environmentImportTool,
+  planCreateTool,
+  planRunTool,
+  planReadTool,
+  planUpdateTool,
+  planDeleteTool,
+  planAddStepTool,
+  planRemoveStepTool,
+  planReorderStepsTool,
+  planSetVariablesTool,
+  assertionCreateTool,
+  assertionReadTool,
+  assertionUpdateTool,
+  assertionDeleteTool,
+  historyListRunsTool,
+  historyGetRunTool,
+  historyDeleteRunTool,
+  historyPurgeTool,
+  codebaseExtractCollectionTool,
+  promptCreateEnvironmentTool,
+  promptCreateAssertionTool,
+  promptCreatePlanTool,
+  promptCreateRequestTool,
+  promptUpdateRequestTool,
+  promptCreateFolderTreeTool,
+  promptAddPlanStepsTool,
+  promptSetPlanVariablesTool,
+  promptCreateMockServerTool,
+  promptAddMockEndpointTool,
+  promptSetEndpointValidationRulesTool,
+  promptSetEndpointResponseRulesTool,
+  promptSetEndpointMultipliersTool,
+  promptSetEndpointRequestSchemaTool,
+  globalAssetsFilesListTool,
+  globalAssetsFilesCreateTool,
+  globalAssetsFilesUpdateTool,
+  globalAssetsFilesDeleteTool,
+  mockCreateFromOpenApiTool,
+  mockCreateFromPostmanTool,
+  mockCreateFromInsomniaTool,
+  mockCreateManualTool,
+  mockListTool,
+  mockListEndpointsTool,
+  mockStartTool,
+  mockStopTool,
+  mockDeleteTool,
+  mockAddEndpointTool,
+  mockUpdateEndpointTool,
+  mockDeleteEndpointTool,
+  mockSetValidationRulesTool,
+  mockSetResponseRulesTool,
+  mockSetMultipliersTool,
+  mockSetRequestSchemaTool,
+  mockSetDefaultPortTool,
+  mockImportPostmanMockCollectionTool,
+  releaseListTool,
+  releasePublishTool,
+  releaseDeprecateTool,
+  releaseYankTool,
+  linkedListTool,
+  linkedGetTool,
+  linkedSetConfigTool,
+  linkedUnlinkTool,
+  linkedLinkTool,
+  linkedRefreshTool,
+  releaseTagTool,
+  repoSetTopicsTool,
+  marketplaceSearchTool
+];
+function getTool(name) {
+  return TOOL_REGISTRY.find((t) => t.name === name);
+}
+
+// src/providers/Workspaces.ts
+var SingleWorkspaceAdapter = class {
+  constructor(provider, workspaceId, displayName = "Workspace") {
+    this.provider = provider;
+    this.workspaceId = workspaceId;
+    this.displayName = displayName;
+  }
+  provider;
+  workspaceId;
+  displayName;
+  async list() {
+    const state = await this.provider.read();
+    const s = state.synced;
+    const id = s.workspaceId ?? this.workspaceId ?? "unknown";
+    this.workspaceId = id;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return [
+      {
+        id,
+        name: this.displayName,
+        isActive: true,
+        createdAt: s.meta?.createdAt ?? now,
+        lastOpenedAt: s.meta?.updatedAt ?? now,
+        counts: s.collections ? {
+          requests: Object.keys(s.collections.requests ?? {}).length,
+          folders: Object.keys(s.collections.folders ?? {}).length,
+          environments: Object.keys(s.environments?.items ?? {}).length,
+          mockServers: Object.keys(s.mockServers ?? {}).length,
+          plans: Object.keys(s.executionPlans ?? {}).length
+        } : null
+      }
+    ];
+  }
+  for(workspaceId) {
+    if (this.workspaceId && workspaceId !== this.workspaceId) {
+      throw new WorkspaceNotFoundError(workspaceId);
+    }
+    return this.provider;
+  }
+  activeId() {
+    return this.workspaceId;
+  }
+  setActive(workspaceId) {
+    if (this.workspaceId && workspaceId !== this.workspaceId) {
+      throw new WorkspaceNotFoundError(workspaceId);
+    }
+    return Promise.resolve();
   }
 };
 var WorkspaceNotFoundError = class extends Error {
@@ -2790,7 +4427,7 @@ var WorkspaceNotFoundError = class extends Error {
 };
 
 // src/providers/InMemoryWorkspaceProvider.ts
-var import_core4 = require("@apicircle/core");
+var import_core6 = require("@apicircle/core");
 var InMemoryWorkspaceProvider = class {
   state;
   constructor(initial) {
@@ -2800,7 +4437,7 @@ var InMemoryWorkspaceProvider = class {
     return this.state;
   }
   async apply(patch) {
-    const out = (0, import_core4.applyMutation)(this.state, patch);
+    const out = (0, import_core6.applyMutation)(this.state, patch);
     this.state = out.next;
     return { state: this.state, changedIds: out.changedIds };
   }
@@ -2814,7 +4451,7 @@ var InMemoryWorkspaceProvider = class {
 };
 
 // src/providers/FileBackedWorkspaceProvider.ts
-var import_core5 = require("@apicircle/core");
+var import_core7 = require("@apicircle/core");
 var import_file_backed = require("@apicircle/core/workspace/file-backed");
 var FileBackedWorkspaceProvider = class {
   constructor(dir) {
@@ -2831,7 +4468,7 @@ var FileBackedWorkspaceProvider = class {
   async apply(patch) {
     let captured = null;
     await (0, import_file_backed.withWorkspace)(this.dir, async (state) => {
-      const result = (0, import_core5.applyMutation)(state, patch);
+      const result = (0, import_core7.applyMutation)(state, patch);
       captured = { state: result.next, changedIds: result.changedIds };
       return { next: result.next };
     });
@@ -2849,6 +4486,52 @@ var FileBackedWorkspaceProvider = class {
   }
 };
 
+// src/providers/GitBackedWorkspaceProvider.ts
+var import_core8 = require("@apicircle/core");
+var import_file_backed2 = require("@apicircle/core/workspace/file-backed");
+var GIT_SYNCED_FILENAME = "workspace.json";
+var GitBackedWorkspaceProvider = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  async read() {
+    const out = await (0, import_file_backed2.loadFromFile)(this.dir, {
+      syncedFilename: GIT_SYNCED_FILENAME,
+      allowMissing: true
+    });
+    if (!out) {
+      throw new Error(
+        `No workspace found at ${this.dir}. Expected .apicircle/registry.json and .apicircle/workspace-<id>/workspace.json in the repo.`
+      );
+    }
+    return out;
+  }
+  async apply(patch) {
+    let captured = null;
+    await (0, import_file_backed2.withWorkspace)(
+      this.dir,
+      async (state) => {
+        const result = (0, import_core8.applyMutation)(state, patch);
+        captured = { state: result.next, changedIds: result.changedIds };
+        return { next: result.next };
+      },
+      { syncedFilename: GIT_SYNCED_FILENAME }
+    );
+    if (!captured) throw new Error("apply did not run");
+    return captured;
+  }
+  async write(next) {
+    const current = await this.read();
+    const merged = {
+      synced: next.synced ?? current.synced,
+      local: next.local ?? current.local
+    };
+    await (0, import_file_backed2.saveToFile)(this.dir, merged, { syncedFilename: GIT_SYNCED_FILENAME });
+    return merged;
+  }
+};
+
 // src/providers/MultiWorkspaceProvider.ts
 var import_registry = require("@apicircle/core/workspace/registry");
 var LazyActiveWorkspaceProvider = class {
@@ -2935,13 +4618,14 @@ var MultiWorkspaceProvider = class {
       let counts = null;
       try {
         const state = await (0, import_registry.loadWorkspaceById)(this.registryRoot, entry.id);
-        if (state) {
+        if (state?.synced?.collections) {
+          const s = state.synced;
           counts = {
-            requests: Object.keys(state.synced.collections.requests).length,
-            folders: Object.keys(state.synced.collections.folders).length,
-            environments: Object.keys(state.synced.environments.items).length,
-            mockServers: Object.keys(state.synced.mockServers ?? {}).length,
-            plans: Object.keys(state.synced.executionPlans ?? {}).length
+            requests: Object.keys(s.collections.requests ?? {}).length,
+            folders: Object.keys(s.collections.folders ?? {}).length,
+            environments: Object.keys(s.environments?.items ?? {}).length,
+            mockServers: Object.keys(s.mockServers ?? {}).length,
+            plans: Object.keys(s.executionPlans ?? {}).length
           };
         }
       } catch {
@@ -3021,7 +4705,245 @@ var InProcessMockController = class {
   }
 };
 
+// src/config/snippets.ts
+var path = __toESM(require("path"), 1);
+var AI_CLIENTS = [
+  "claude-desktop",
+  "claude-code",
+  "codex",
+  "cursor",
+  "continue",
+  "cline",
+  "zed",
+  "windsurf",
+  "github-copilot",
+  "chatgpt",
+  "generic"
+];
+function buildSnippetVariants(client, binary, workspace) {
+  const forwardWorkspace = workspace.replace(/\\/g, "/");
+  const render = client === "codex" ? renderTomlSnippet : renderJsonSnippet;
+  const escaped = render(binary, workspace);
+  const forwardSlash = render(binary, forwardWorkspace);
+  return {
+    forwardSlash,
+    escaped,
+    identical: forwardSlash === escaped
+  };
+}
+function renderJsonSnippet(binary, workspace) {
+  const entry = {
+    command: binary,
+    args: ["--workspace", workspace],
+    env: { APICIRCLE_WORKSPACE: workspace }
+  };
+  return JSON.stringify({ mcpServers: { apicircle: entry } }, null, 2);
+}
+function renderTomlSnippet(binary, workspace) {
+  const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return [
+    `[mcp_servers.apicircle]`,
+    `command = "${esc(binary)}"`,
+    `args = ["--workspace", "${esc(workspace)}"]`,
+    ``,
+    `[mcp_servers.apicircle.env]`,
+    `APICIRCLE_WORKSPACE = "${esc(workspace)}"`
+  ].join("\n");
+}
+function resolveAiClientConfigPath(client, env) {
+  const { homedir, platform, appdata } = env;
+  switch (client) {
+    case "claude-desktop":
+      if (platform === "darwin") {
+        return path.join(homedir, "Library/Application Support/Claude/claude_desktop_config.json");
+      }
+      if (platform === "win32") {
+        return path.join(
+          appdata ?? path.join(homedir, "AppData/Roaming"),
+          "Claude/claude_desktop_config.json"
+        );
+      }
+      return path.join(homedir, ".config/Claude/claude_desktop_config.json");
+    case "claude-code":
+      return path.join(homedir, ".claude/mcp.json");
+    case "cursor":
+      return path.join(homedir, ".cursor/mcp.json");
+    case "continue":
+      return path.join(homedir, ".continue/config.yaml");
+    case "zed":
+      return path.join(homedir, ".config/zed/settings.json");
+    case "windsurf":
+      return path.join(homedir, ".codeium/windsurf/mcp_config.json");
+    case "codex":
+      return path.join(homedir, ".codex/config.toml");
+    default:
+      return null;
+  }
+}
+
+// src/prompts/mcpPrompts.ts
+var MCP_PROMPT_CATEGORIES = [
+  { id: "workspaces", label: "Workspaces" },
+  { id: "collections", label: "Collections" },
+  { id: "environments", label: "Environments" },
+  { id: "execution", label: "Execution" },
+  { id: "mocks", label: "Mocks" },
+  { id: "auth", label: "Auth" },
+  { id: "imports", label: "Imports" }
+];
+var MCP_PROMPTS = [
+  // ── Workspaces (multi-workspace discovery) ───────────────────────
+  {
+    id: "list-workspaces",
+    text: "List every API Circle workspace I have and tell me which is active.",
+    description: "Multi-workspace discovery \u2014 call this first when you are not sure which workspace to drive.",
+    category: "workspaces",
+    tools: ["workspace.list"]
+  },
+  {
+    id: "scope-to-workspace",
+    text: 'Read the requests in the "Petstore" workspace.',
+    description: "Drill into a specific workspace by name; the AI passes `workspaceId` to scope reads.",
+    category: "workspaces",
+    tools: ["workspace.list", "workspace.read"]
+  },
+  {
+    id: "multi-workspace-summary",
+    text: "Across every workspace, count requests, folders, environments, and mocks. Give me one row per workspace.",
+    description: "High-level summary across every registered workspace \u2014 pairs well with the multi-workspace envelope.",
+    category: "workspaces",
+    tools: ["workspace.list"]
+  },
+  // ── Collections (requests + folders in the active workspace) ─────
+  {
+    id: "list-requests",
+    text: "List every request in my API Circle workspace grouped by folder.",
+    description: "Quick overview of the request catalog so you know what is already wired up.",
+    category: "collections",
+    tools: ["workspace.read", "request.read", "folder.read"]
+  },
+  {
+    id: "create-request",
+    text: 'Add a new GET request named "Health check" pointing at https://example.com/healthz with an Accept: application/json header.',
+    description: "Have the AI author a request and persist it to the workspace.",
+    category: "collections",
+    tools: ["request.create"]
+  },
+  {
+    id: "update-request",
+    text: 'Find the "Create user" request and change its method to POST and body to {"name": "Ada"}.',
+    description: "Targeted edit by name \u2014 the AI looks it up, then updates.",
+    category: "collections",
+    tools: ["request.read", "request.update"]
+  },
+  {
+    id: "organize-folders",
+    text: 'Move every request whose URL contains /users into a folder named "User API".',
+    description: "Bulk reorganisation via natural language.",
+    category: "collections",
+    tools: ["workspace.read", "folder.create", "request.update"]
+  },
+  // ── Environments ──────────────────────────────────────────────────
+  {
+    id: "env-list",
+    text: "Show me all environments and which one is active.",
+    description: "Inventory of envs + which is layered onto requests right now.",
+    category: "environments",
+    tools: ["environment.read"]
+  },
+  {
+    id: "env-create",
+    text: 'Create a "staging" environment with BASE_URL=https://staging.example.com and API_KEY={{SECRET:staging-key}}.',
+    description: "Spin up a new env with both a plain variable and a secret reference.",
+    category: "environments",
+    tools: ["environment.create"]
+  },
+  {
+    id: "env-switch",
+    text: 'Switch the active environment to "production" and confirm by previewing the effective URL of the "Get user" request.',
+    description: "Activate an env then verify variable interpolation.",
+    category: "environments",
+    tools: ["environment.update", "request.read"]
+  },
+  // ── Execution ─────────────────────────────────────────────────────
+  {
+    id: "run-request",
+    text: 'Run the "Get user" request with userId=42 and show me the JSON response.',
+    description: "One-shot execution with overridden context vars.",
+    category: "execution",
+    tools: ["request.execute"]
+  },
+  {
+    id: "run-plan",
+    text: 'Execute the "Regression smoke" plan and summarise which assertions failed.',
+    description: "Drive a saved execution plan end-to-end.",
+    category: "execution",
+    tools: ["plan.read", "plan.execute"]
+  },
+  {
+    id: "inspect-history",
+    text: "Show me the last 5 requests I ran and their status codes.",
+    description: "Quick triage when something just broke.",
+    category: "execution",
+    tools: ["history.read"]
+  },
+  // ── Mocks ─────────────────────────────────────────────────────────
+  {
+    id: "mock-start",
+    text: 'Start the "Petstore" mock on port 4010 and tell me its base URL.',
+    description: "Spin up a local mock so requests can hit it.",
+    category: "mocks",
+    tools: ["mock.list", "mock.start"]
+  },
+  {
+    id: "mock-list",
+    text: "List every running mock with its port, served spec, and request count.",
+    description: "Status snapshot of every active mock runtime.",
+    category: "mocks",
+    tools: ["mock.list"]
+  },
+  {
+    id: "mock-stop",
+    text: "Stop every running mock.",
+    description: "Clean shutdown of all mock servers in one go.",
+    category: "mocks",
+    tools: ["mock.stopAll"]
+  },
+  // ── Auth ──────────────────────────────────────────────────────────
+  {
+    id: "auth-set-bearer",
+    text: 'Set the "Get user" request to use bearer auth with token={{ACCESS_TOKEN}}.',
+    description: "Wire bearer auth onto a single request via env-var reference.",
+    category: "auth",
+    tools: ["request.update"]
+  },
+  {
+    id: "auth-oauth2",
+    text: 'Configure the "Create order" request to use OAuth2 client-credentials against https://auth.example.com/token with the "orders.write" scope.',
+    description: "Full OAuth2 client-credentials wiring without leaving the chat.",
+    category: "auth",
+    tools: ["request.update"]
+  },
+  // ── Imports ───────────────────────────────────────────────────────
+  {
+    id: "import-openapi",
+    text: "Import the OpenAPI spec at ./openapi.yaml and create one request per operation.",
+    description: "Bulk import of a spec file from the workspace.",
+    category: "imports",
+    tools: ["import.openapi"]
+  },
+  {
+    id: "import-curl",
+    text: 'I am going to paste a cURL command \u2014 turn it into a saved request named "Webhook test".',
+    description: "cURL \u2192 saved request with a name you control.",
+    category: "imports",
+    tools: ["import.curl"]
+  }
+];
+
 // src/index.ts
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var import_stdio2 = require("@modelcontextprotocol/sdk/server/stdio.js");
 function createMcpServer(options) {
   const workspaces = options.workspaces ?? new SingleWorkspaceAdapter(
     options.workspace,
@@ -3040,15 +4962,23 @@ function createMcpServer(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AI_CLIENTS,
   FileBackedWorkspaceProvider,
+  GitBackedWorkspaceProvider,
   InMemoryWorkspaceProvider,
   InProcessMockController,
+  MCP_PROMPTS,
+  MCP_PROMPT_CATEGORIES,
   McpHost,
   MultiWorkspaceProvider,
   SingleWorkspaceAdapter,
+  StdioServerTransport,
+  StreamableHTTPServerTransport,
   TOOL_REGISTRY,
   WorkspaceNotFoundError,
+  buildSnippetVariants,
   createMcpServer,
-  getTool
+  getTool,
+  resolveAiClientConfigPath
 });
 //# sourceMappingURL=index.cjs.map