@apicircle/mcp-server 1.0.9 → 1.1.0

package/dist/bin/mcp-server.cjs

@@ -36,9 +36,10 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@apicircle/mcp-server",
-      version: "1.0.9",
+      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",
@@ -81,7 +82,8 @@ var init_package = __esm({
         "apicircle-mcp": "./dist/bin/mcp-server.cjs"
       },
       exports: {
-        ".": "./src/index.ts"
+        ".": "./src/index.ts",
+        "./prompts": "./src/prompts/mcpPrompts.ts"
       },
       files: [
         "dist"
@@ -100,6 +102,16 @@ var init_package = __esm({
               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"
+            }
           }
         }
       },
@@ -117,6 +129,7 @@ var init_package = __esm({
         zod: "^3.23.0"
       },
       devDependencies: {
+        "@apicircle/git": "workspace:*",
         "@types/node": "^20.0.0",
         tsup: "^8.3.0",
         typescript: "^5.4.0",
@@ -619,13 +632,14 @@ var init_workspaceList = __esm({
 });
 
 // src/tools/crud.ts
-var import_zod5, import_shared2, import_core2, HTTP_METHOD, requestCreateTool, requestReadTool, requestUpdateTool, requestDeleteTool, folderCreateTool, folderReadTool, folderUpdateTool, folderDeleteTool, VARIABLE, environmentCreateTool, environmentReadTool, environmentUpdateTool, environmentDeleteTool, environmentSetActiveTool, environmentSetPriorityTool, environmentExportTool, environmentImportTool, PLAN_STEP, planCreateTool, planReadTool, planUpdateTool, planDeleteTool, planAddStepTool, planRemoveStepTool, planReorderStepsTool, PLAN_VARIABLE, planSetVariablesTool, planRunTool, ASSERTION, assertionCreateTool, assertionReadTool, assertionUpdateTool, assertionDeleteTool, workspaceReadTool, workspaceWriteTool;
+var import_zod5, import_shared2, import_core2, FULL_REQUEST_AUTH, HTTP_METHOD, requestCreateTool, requestReadTool, requestUpdateTool, requestDeleteTool, folderCreateTool, folderReadTool, folderUpdateTool, folderDeleteTool, VARIABLE, environmentCreateTool, environmentReadTool, environmentUpdateTool, environmentDeleteTool, environmentSetActiveTool, environmentSetPriorityTool, environmentExportTool, environmentImportTool, PLAN_STEP, planCreateTool, planReadTool, planUpdateTool, planDeleteTool, planAddStepTool, planRemoveStepTool, planReorderStepsTool, PLAN_VARIABLE, planSetVariablesTool, planRunTool, ASSERTION, assertionCreateTool, assertionReadTool, assertionUpdateTool, assertionDeleteTool, workspaceReadTool, workspaceWriteTool;
 var init_crud = __esm({
   "src/tools/crud.ts"() {
     "use strict";
     import_zod5 = require("zod");
     import_shared2 = require("@apicircle/shared");
     import_core2 = require("@apicircle/core");
+    FULL_REQUEST_AUTH = import_zod5.z.object({ type: import_zod5.z.string() }).passthrough();
     HTTP_METHOD = import_zod5.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
     requestCreateTool = {
       name: "request.create",
@@ -713,16 +727,18 @@ var init_crud = __esm({
     };
     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 };
@@ -746,18 +762,39 @@ var init_crud = __esm({
     };
     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)) };
       }
     };
     folderDeleteTool = {
@@ -1620,7 +1657,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)(),
@@ -1685,7 +1722,7 @@ function patchEndpoint(mock, endpointId, patcher) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-var import_zod9, import_shared3, promptCreateEnvironmentTool, promptCreateAssertionTool, promptCreatePlanTool, HTTP_METHOD2, HEADER_OR_QUERY, REQUEST_BODY, PROMPT_AUTH, PROMPT_ASSERTION, ENDPOINT_RESPONSE, VALIDATION_RULE_NL, CONDITION_CLAUSE_NL, RESPONSE_RULE_NL, MULTIPLIER_NL, ENDPOINT_INPUT, promptCreateRequestTool, promptUpdateRequestTool, FOLDER_TREE_NODE, promptCreateFolderTreeTool, promptAddPlanStepsTool, promptSetPlanVariablesTool, promptCreateMockServerTool, promptAddMockEndpointTool, promptSetEndpointValidationRulesTool, promptSetEndpointResponseRulesTool, promptSetEndpointMultipliersTool;
+var import_zod9, import_shared3, promptCreateEnvironmentTool, promptCreateAssertionTool, promptCreatePlanTool, HTTP_METHOD2, HEADER_OR_QUERY, REQUEST_BODY, PROMPT_AUTH, PROMPT_ASSERTION, ENDPOINT_RESPONSE, VALIDATION_RULE_NL, CONDITION_CLAUSE_NL, RESPONSE_RULE_NL, MULTIPLIER_NL, ENDPOINT_INPUT, promptCreateRequestTool, promptUpdateRequestTool, FOLDER_TREE_NODE, promptCreateFolderTreeTool, promptAddPlanStepsTool, promptSetPlanVariablesTool, promptCreateMockServerTool, promptAddMockEndpointTool, promptSetEndpointValidationRulesTool, promptSetEndpointResponseRulesTool, promptSetEndpointMultipliersTool, PARAM_NL, promptSetEndpointRequestSchemaTool;
 var init_prompt = __esm({
   "src/tools/prompt.ts"() {
     "use strict";
@@ -1843,7 +1880,9 @@ var init_prompt = __esm({
     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("{}")
@@ -2038,10 +2077,13 @@ var init_prompt = __esm({
     };
     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) {
@@ -2068,7 +2110,7 @@ var init_prompt = __esm({
     };
     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,
@@ -2171,7 +2213,7 @@ var init_prompt = __esm({
     };
     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(),
@@ -2182,6 +2224,9 @@ var init_prompt = __esm({
         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: {
@@ -2202,6 +2247,53 @@ var init_prompt = __esm({
         return { ok: true, changedIds: out.changedIds };
       }
     };
+    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()
+    });
+    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 };
+      }
+    };
   }
 });
 
@@ -2401,7 +2493,11 @@ function patchEndpoint2(mock, endpointId, patcher) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-var import_zod11, import_shared5, import_mock_server_core2, mockCreateFromOpenApiTool, mockCreateFromPostmanTool, mockCreateFromInsomniaTool, mockImportPostmanMockCollectionTool, mockListTool, mockStartTool, mockStopTool, mockDeleteTool, HTTP_METHOD3, mockCreateManualTool, mockListEndpointsTool, ENDPOINT_RESPONSE2, mockAddEndpointTool, mockUpdateEndpointTool, mockDeleteEndpointTool, VALIDATION_RULE, CONDITION_CLAUSE, RESPONSE_RULE, MULTIPLIER, mockSetValidationRulesTool, mockSetResponseRulesTool, mockSetMultipliersTool;
+function normalizeSchemaBody(body) {
+  if (!body || !body.description && !body.example) return void 0;
+  return body;
+}
+var import_zod11, import_shared5, import_mock_server_core2, mockCreateFromOpenApiTool, mockCreateFromPostmanTool, mockCreateFromInsomniaTool, mockImportPostmanMockCollectionTool, mockListTool, mockStartTool, mockStopTool, mockDeleteTool, mockSetDefaultPortTool, HTTP_METHOD3, mockCreateManualTool, mockListEndpointsTool, ENDPOINT_RESPONSE2, mockAddEndpointTool, mockUpdateEndpointTool, mockDeleteEndpointTool, VALIDATION_RULE, CONDITION_CLAUSE, RESPONSE_RULE, MULTIPLIER, mockSetValidationRulesTool, mockSetResponseRulesTool, PARAM, REQUEST_SCHEMA_BODY, mockSetRequestSchemaTool, mockSetMultipliersTool;
 var init_mocks = __esm({
   "src/tools/mocks.ts"() {
     "use strict";
@@ -2508,10 +2604,14 @@ var init_mocks = __esm({
     };
     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.",
+      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(),
-        port: import_zod11.z.number().int().positive().optional()
+        // 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();
@@ -2551,13 +2651,44 @@ var init_mocks = __esm({
         return { ok: true, changedIds: out.changedIds };
       }
     };
+    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
+        };
+      }
+    };
     HTTP_METHOD3 = import_zod11.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
     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_zod11.z.object({
         name: import_zod11.z.string().min(1),
-        defaultPort: import_zod11.z.number().int().positive().nullable().optional()
+        // 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();
@@ -2735,7 +2866,10 @@ var init_mocks = __esm({
       id: import_zod11.z.string().optional(),
       name: import_zod11.z.string(),
       enabled: import_zod11.z.boolean().default(true),
-      when: import_zod11.z.array(CONDITION_CLAUSE).default([]),
+      // 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("{}")
@@ -2817,9 +2951,57 @@ var init_mocks = __esm({
         return { ok: true, changedIds: out.changedIds };
       }
     };
+    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()
+    });
+    REQUEST_SCHEMA_BODY = import_zod11.z.object({ description: import_zod11.z.string().optional(), example: import_zod11.z.string().optional() }).optional();
+    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 };
+      }
+    };
     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.",
+      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(),
@@ -2830,6 +3012,9 @@ var init_mocks = __esm({
         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: {
@@ -2853,181 +3038,1525 @@ var init_mocks = __esm({
   }
 });
 
-// src/tools/registry.ts
-function getTool(name) {
-  return TOOL_REGISTRY.find((t) => t.name === name);
-}
-var TOOL_REGISTRY;
-var init_registry = __esm({
-  "src/tools/registry.ts"() {
-    "use strict";
-    init_imports();
-    init_codegen();
-    init_workspaceList();
-    init_crud();
-    init_folderExchange();
-    init_history();
-    init_codebase();
-    init_prompt();
-    init_globalAssets();
-    init_mocks();
-    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,
-      globalAssetsFilesListTool,
-      globalAssetsFilesCreateTool,
-      globalAssetsFilesUpdateTool,
-      globalAssetsFilesDeleteTool,
-      mockCreateFromOpenApiTool,
-      mockCreateFromPostmanTool,
-      mockCreateFromInsomniaTool,
-      mockCreateManualTool,
-      mockListTool,
-      mockListEndpointsTool,
-      mockStartTool,
-      mockStopTool,
-      mockDeleteTool,
-      mockAddEndpointTool,
-      mockUpdateEndpointTool,
-      mockDeleteEndpointTool,
-      mockSetValidationRulesTool,
-      mockSetResponseRulesTool,
-      mockSetMultipliersTool,
-      mockImportPostmanMockCollectionTool
-    ];
-  }
-});
-
-// src/providers/Workspaces.ts
-var Workspaces_exports = {};
-__export(Workspaces_exports, {
-  SingleWorkspaceAdapter: () => SingleWorkspaceAdapter,
-  WorkspaceNotFoundError: () => WorkspaceNotFoundError
-});
-var SingleWorkspaceAdapter, WorkspaceNotFoundError;
-var init_Workspaces = __esm({
-  "src/providers/Workspaces.ts"() {
+// src/tools/releases.ts
+var import_zod12, import_core4, releaseListTool, releasePublishTool, releaseDeprecateTool, releaseYankTool;
+var init_releases = __esm({
+  "src/tools/releases.ts"() {
     "use strict";
-    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);
+    import_zod12 = require("zod");
+    import_core4 = require("@apicircle/core");
+    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;
+        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 };
       }
-      activeId() {
-        return this.workspaceId;
+    };
+    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" };
+        }
       }
-      setActive(workspaceId) {
-        if (this.workspaceId && workspaceId !== this.workspaceId) {
-          throw new WorkspaceNotFoundError(workspaceId);
+    };
+    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" };
         }
-        return Promise.resolve();
       }
     };
-    WorkspaceNotFoundError = class extends Error {
-      code = "workspace-not-found";
-      workspaceId;
-      constructor(workspaceId) {
-        super(`No workspace with id "${workspaceId}" is available on this server.`);
-        this.name = "WorkspaceNotFoundError";
-        this.workspaceId = workspaceId;
+    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/providers/InMemoryWorkspaceProvider.ts
-var import_core4, InMemoryWorkspaceProvider;
-var init_InMemoryWorkspaceProvider = __esm({
-  "src/providers/InMemoryWorkspaceProvider.ts"() {
-    "use strict";
-    import_core4 = require("@apicircle/core");
+// src/tools/linkedWorkspaces.ts
+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 import_zod13, linkedListTool, linkedGetTool, linkedSetConfigTool, linkedUnlinkTool;
+var init_linkedWorkspaces = __esm({
+  "src/tools/linkedWorkspaces.ts"() {
+    "use strict";
+    import_zod13 = require("zod");
+    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)
+          )
+        };
+      }
+    };
+    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
+        };
+      }
+    };
+    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)
+        };
+      }
+    };
+    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 };
+      }
+    };
+  }
+});
+
+// ../git/src/github/errors.ts
+var GitHubError, MissingScopeError, RateLimitedError, UnauthorizedError, TimeoutError;
+var init_errors = __esm({
+  "../git/src/github/errors.ts"() {
+    "use strict";
+    GitHubError = class extends Error {
+      constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "GitHubError";
+      }
+      status;
+      body;
+    };
+    MissingScopeError = class extends GitHubError {
+      /** Scope strings the API said are missing, e.g. ['pull_request']. */
+      missingScopes;
+      /** Scope strings the token currently grants, parsed from x-oauth-scopes. */
+      grantedScopes;
+      constructor(message, status, missingScopes, grantedScopes) {
+        super(message, status);
+        this.name = "MissingScopeError";
+        this.missingScopes = missingScopes;
+        this.grantedScopes = grantedScopes;
+      }
+    };
+    RateLimitedError = class extends GitHubError {
+      /** Unix timestamp (ms) when the rate-limit window resets. */
+      resetAtMs;
+      constructor(message, status, resetAtMs) {
+        super(message, status);
+        this.name = "RateLimitedError";
+        this.resetAtMs = resetAtMs;
+      }
+    };
+    UnauthorizedError = class extends GitHubError {
+      constructor(message, status) {
+        super(message, status);
+        this.name = "UnauthorizedError";
+      }
+    };
+    TimeoutError = class extends GitHubError {
+      /** Timeout that fired, in ms. Useful for the UI message. */
+      timeoutMs;
+      constructor(message, timeoutMs) {
+        super(message, 0);
+        this.name = "TimeoutError";
+        this.timeoutMs = timeoutMs;
+      }
+    };
+  }
+});
+
+// ../git/src/github/api.ts
+function normalizeMarketplaceRepo(raw) {
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    description: raw.description ?? "",
+    topics: raw.topics ?? [],
+    stargazers: raw.stargazers_count ?? 0,
+    defaultBranch: raw.default_branch ?? "main"
+  };
+}
+function decodeBase64Utf8(b64) {
+  return new TextDecoder("utf-8").decode(decodeBase64Bytes(b64));
+}
+function decodeBase64Bytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function normalizeRepo(raw) {
+  const visibility = raw.visibility ?? (raw.private === true ? "private" : "public");
+  const isPrivate = raw.private ?? visibility !== "public";
+  const pushable = raw.permissions?.push === true || raw.permissions?.admin === true;
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    defaultBranch: raw.default_branch,
+    visibility,
+    isPrivate,
+    pushable
+  };
+}
+function parseScopes(headers) {
+  const raw = headers.get("x-oauth-scopes") ?? "";
+  const granted = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  const acceptedHeader = headers.get("x-accepted-oauth-scopes") ?? "";
+  const acceptedRequired = acceptedHeader.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return acceptedRequired.length > 0 ? { granted, acceptedRequired } : { granted };
+}
+function classifyError(response, body, callerRequiredScopes) {
+  const message = extractMessage(body) ?? response.statusText;
+  const status = response.status;
+  if (status === 401) {
+    return new UnauthorizedError(message || "Unauthorized \u2014 token rejected", status);
+  }
+  if (status === 403) {
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const reset = response.headers.get("x-ratelimit-reset");
+    if (remaining === "0" && reset) {
+      const resetAtMs = Number(reset) * 1e3;
+      const deltaMs = Math.max(0, resetAtMs - Date.now());
+      const totalSeconds = Math.ceil(deltaMs / 1e3);
+      const human = totalSeconds < 60 ? `${totalSeconds}s` : totalSeconds < 3600 ? `${Math.ceil(totalSeconds / 60)} min` : `${Math.ceil(totalSeconds / 3600)} h`;
+      return new RateLimitedError(
+        `GitHub rate limit reached. Resets in ${human} (at ${new Date(resetAtMs).toISOString()}).`,
+        status,
+        resetAtMs
+      );
+    }
+    const accepted = (response.headers.get("x-accepted-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const granted = (response.headers.get("x-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const missing = accepted.length > 0 ? accepted.filter((s) => !granted.includes(s)) : callerRequiredScopes.filter((s) => !granted.includes(s));
+    if (missing.length > 0) {
+      return new MissingScopeError(
+        `GitHub denied this action: missing scopes ${missing.join(", ")}.`,
+        status,
+        missing,
+        granted
+      );
+    }
+  }
+  return new GitHubError(message || "GitHub API call failed", status, body);
+}
+function extractMessage(body) {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string") return m;
+  }
+  return null;
+}
+async function safeReadJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+var API_BASE, LOGIN_BASE, DEFAULT_TIMEOUT_MS, GitHubClient;
+var init_api = __esm({
+  "../git/src/github/api.ts"() {
+    "use strict";
+    init_errors();
+    API_BASE = "https://api.github.com";
+    LOGIN_BASE = "https://github.com";
+    DEFAULT_TIMEOUT_MS = 15e3;
+    GitHubClient = class {
+      baseUrl;
+      loginBaseUrl;
+      fetchImpl;
+      timeoutMs;
+      constructor(opts = {}) {
+        this.baseUrl = opts.baseUrl ?? API_BASE;
+        this.loginBaseUrl = (opts.loginBaseUrl ?? LOGIN_BASE).replace(/\/$/, "");
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      }
+      /**
+       * Fetch the authenticated user. Doubles as a "verify token" probe — used
+       * by the Secret Vault Sessions tab to refresh the granted-scopes list.
+       */
+      async getViewer(token, opts = {}) {
+        const { json, response } = await this.call(token, "/user", opts);
+        return {
+          viewer: {
+            login: json.login,
+            id: json.id,
+            name: json.name ?? null,
+            avatarUrl: json.avatar_url ?? null
+          },
+          scopes: parseScopes(response.headers)
+        };
+      }
+      /**
+       * List repositories the authenticated user can access. Used by the repo
+       * picker. Capped at 100 sorted by recent push; users with thousands of
+       * repos can paginate later.
+       */
+      async listAccessibleRepos(token, opts = {}) {
+        const { json } = await this.call(
+          token,
+          "/user/repos?per_page=100&sort=pushed&affiliation=owner,collaborator,organization_member",
+          opts
+        );
+        return json.map(normalizeRepo);
+      }
+      /**
+       * Fetch a specific repo. Validates the user-supplied owner/name pair
+       * exists + is accessible, and exposes the default branch.
+       */
+      async getRepo(token, owner, name, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+          opts
+        );
+        return normalizeRepo(json);
+      }
+      /**
+       * Read the head SHA of a branch. Used to seed a new working branch from
+       * main before any edits land.
+       */
+      async getBranchHead(token, owner, name, branch, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches/${encodeURIComponent(branch)}`,
+          opts
+        );
+        return { name: json.name, commitSha: json.commit.sha };
+      }
+      /**
+       * List branches on a repo. Used by the Link Workspace repo-browser to
+       * populate the branch dropdown after the user picks a repo. Capped at
+       * 100 (GitHub's max page size); repos with more branches paginate.
+       */
+      async listBranches(token, owner, name, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches?per_page=100`,
+          opts
+        );
+        return json.map((b) => ({ name: b.name, commitSha: b.commit.sha }));
+      }
+      /**
+       * Create a new branch ref pointing at `sha`. The auto-branch flow calls
+       * this with the head SHA from `getBranchHead(main)`.
+       *
+       * GitHub returns 422 with "Reference already exists" when the branch
+       * already exists; that surfaces as a GitHubError(422) so the UI can
+       * prompt for a different name.
+       */
+      async createBranch(token, owner, name, branchName, sha, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs`,
+          {
+            ...opts,
+            method: "POST",
+            body: { ref: `refs/heads/${branchName}`, sha },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { name: branchName, commitSha: json.object.sha };
+      }
+      /**
+       * Read a branch ref's current commit SHA. Used at the start of push-to-
+       * save to find the parent commit before building the new tree.
+       */
+      async getRef(token, owner, name, branch, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(branch)}`,
+          opts
+        );
+        return { ref: json.ref, sha: json.object.sha };
+      }
+      /**
+       * Read a commit's tree SHA. Used so the new tree can be built `base_tree`
+       * — every path we don't override is inherited from the parent.
+       */
+      async getCommit(token, owner, name, sha, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits/${encodeURIComponent(sha)}`,
+          opts
+        );
+        return {
+          sha: json.sha,
+          treeSha: json.tree.sha,
+          message: json.message
+        };
+      }
+      /**
+       * Upload a blob to the repo and return its SHA. Used by push-to-save
+       * (P4.3b) for binary attachments — text files go straight into a tree
+       * entry's `content`, but binary bytes have to go through a blob first.
+       *
+       * `content` is base64 when `encoding === 'base64'`. GitHub stores blobs
+       * deduplicated by their git-sha1 (not our sha256), so re-uploading the
+       * same bytes is cheap on their side; we save a roundtrip locally by
+       * tracking lastPushedBlobSha per slot in a future revision.
+       */
+      async createBlob(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/blobs`,
+          {
+            ...opts,
+            method: "POST",
+            body: { content: args.content, encoding: args.encoding },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha, size: json.size ?? 0 };
+      }
+      /**
+       * Build a new tree from `entries`, layered over `baseTreeSha`. Entries
+       * with `content` are inlined (text path); entries with a pre-uploaded
+       * `sha` reference an existing blob (binary path — used by attachments).
+       */
+      async createTree(token, owner, name, args, opts = {}) {
+        const tree = args.entries.map((e) => ({
+          path: e.path,
+          mode: e.mode ?? "100644",
+          type: e.type ?? "blob",
+          ...e.content !== void 0 ? { content: e.content } : {},
+          ...e.sha !== void 0 ? { sha: e.sha } : {}
+        }));
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/trees`,
+          {
+            ...opts,
+            method: "POST",
+            body: { base_tree: args.baseTreeSha, tree },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha };
+      }
+      /**
+       * Create a new commit object pointing at the given tree, with the given
+       * parents. Returns the new commit's SHA + the tree it points at.
+       */
+      async createCommit(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits`,
+          {
+            ...opts,
+            method: "POST",
+            body: {
+              message: args.message,
+              tree: args.treeSha,
+              parents: args.parents
+            },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { sha: json.sha, treeSha: json.tree.sha };
+      }
+      /**
+       * Fast-forward a branch ref to a new commit SHA. Pass `force: true` to
+       * skip the FF check (we don't — push-to-save is always FF over the ref
+       * we just read with getRef()).
+       */
+      async updateRef(token, owner, name, args, opts = {}) {
+        const { json } = await this.call(
+          token,
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(args.branch)}`,
+          {
+            ...opts,
+            method: "PATCH",
+            body: { sha: args.sha, force: args.force ?? false },
+            requiredScopes: ["repo"]
+          }
+        );
+        return { ref: json.ref, sha: json.object.sha };
+      }
+      /**
+       * Search GitHub for public API Circle workspaces. Appends
+       * `topic:apicircle` to the user-supplied query so only repos carrying
+       * the `apicircle` topic — the topic the Releases & Topics dialog
+       * locks onto every workspace repo — surface in results. GitHub
+       * matches the bare query against repository name, description, and
+       * topics, so category words like `payments` narrow the marketplace by
+       * topic. An empty query lists every public API Circle workspace. Top
+       * 30 results. Token is optional — anonymous browsing is supported
+       * (lower GitHub rate limits apply); pass a PAT when one is available
+       * to lift them. `sort` controls ordering: omit for GitHub's
+       * best-match relevance, or pass `'stars'` / `'updated'`.
+       */
+      async searchMarketplaceRepos(token, query, opts = {}) {
+        const { sort, ...callOpts } = opts;
+        const fullQuery = `${query.trim()} topic:apicircle`.trim();
+        const sortParam = sort ? `&sort=${sort}&order=desc` : "";
+        const path3 = `/search/repositories?q=${encodeURIComponent(fullQuery)}&per_page=30${sortParam}`;
+        const { json } = await this.call(token, path3, 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, path3, ref, opts = {}) {
+        const query = `?ref=${encodeURIComponent(ref)}`;
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path3.split("/").map(encodeURIComponent).join("/")}${query}`,
+            opts
+          );
+          if (Array.isArray(json) || json.type !== "file") {
+            throw new GitHubError(`Path ${path3} 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, path3, 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/${path3.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, path3, ref, opts = {}) {
+        const query = `?ref=${encodeURIComponent(ref)}`;
+        try {
+          const { json } = await this.call(
+            token,
+            `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path3.split("/").map(encodeURIComponent).join("/")}${query}`,
+            opts
+          );
+          if (Array.isArray(json) || json.type !== "file") {
+            throw new GitHubError(`Path ${path3} 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, path3, opts = {}) {
+        const url = path3.startsWith("http") ? path3 : `${this.baseUrl}${path3}`;
+        const controller = new AbortController();
+        const onExternalAbort = () => controller.abort(opts.signal.reason);
+        if (opts.signal) {
+          if (opts.signal.aborted) controller.abort(opts.signal.reason);
+          else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        const timeoutHandle = setTimeout(
+          () => controller.abort(new Error(`GitHub request timed out after ${this.timeoutMs}ms`)),
+          this.timeoutMs
+        );
+        let response;
+        let timedOut = false;
+        try {
+          response = await this.fetchImpl(url, {
+            method: opts.method ?? "GET",
+            headers: {
+              Accept: "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+              ...token ? { Authorization: `Bearer ${token}` } : {},
+              ...opts.body !== void 0 ? { "Content-Type": "application/json" } : {}
+            },
+            cache: "no-store",
+            body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+            signal: controller.signal
+          });
+        } catch (err) {
+          const isAbort = err instanceof DOMException && err.name === "AbortError";
+          const callerAborted = opts.signal?.aborted ?? false;
+          if (isAbort && !callerAborted) {
+            timedOut = true;
+            throw new TimeoutError(
+              `GitHub request timed out after ${this.timeoutMs}ms. The write may have partially landed \u2014 refresh before retrying.`,
+              this.timeoutMs
+            );
+          }
+          throw err;
+        } finally {
+          clearTimeout(timeoutHandle);
+          if (opts.signal) opts.signal.removeEventListener("abort", onExternalAbort);
+          void timedOut;
+        }
+        if (response.ok) {
+          if (response.status === 204 || response.status === 205) {
+            return { json: {}, response };
+          }
+          const json = await response.json();
+          return { json, response };
+        }
+        const errBody = await safeReadJson(response);
+        throw classifyError(response, errBody, opts.requiredScopes ?? []);
+      }
+    };
+  }
+});
+
+// ../git/src/index.ts
+var init_src = __esm({
+  "../git/src/index.ts"() {
+    "use strict";
+    init_api();
+    init_errors();
+  }
+});
+
+// src/tools/githubOps.ts
+function resolveToken(input) {
+  const t = (input ?? process.env.GITHUB_TOKEN ?? "").trim();
+  return t;
+}
+var import_zod14, import_core5, import_shared6, TOKEN_HELP, linkedLinkTool, linkedRefreshTool, releaseTagTool, marketplaceSearchTool, TOPIC_RE, repoSetTopicsTool;
+var init_githubOps = __esm({
+  "src/tools/githubOps.ts"() {
+    "use strict";
+    import_zod14 = require("zod");
+    import_core5 = require("@apicircle/core");
+    import_shared6 = require("@apicircle/shared");
+    init_src();
+    TOKEN_HELP = "Pass `token`, or set the GITHUB_TOKEN env var on the MCP process.";
+    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 };
+      }
+    };
+    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
+        };
+      }
+    };
+    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" };
+        }
+      }
+    };
+    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"
+          };
+        }
+      }
+    };
+    TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+    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
+function getTool(name) {
+  return TOOL_REGISTRY.find((t) => t.name === name);
+}
+var TOOL_REGISTRY;
+var init_registry = __esm({
+  "src/tools/registry.ts"() {
+    "use strict";
+    init_imports();
+    init_codegen();
+    init_workspaceList();
+    init_crud();
+    init_folderExchange();
+    init_history();
+    init_codebase();
+    init_prompt();
+    init_globalAssets();
+    init_mocks();
+    init_releases();
+    init_linkedWorkspaces();
+    init_githubOps();
+    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
+    ];
+  }
+});
+
+// src/providers/Workspaces.ts
+var Workspaces_exports = {};
+__export(Workspaces_exports, {
+  SingleWorkspaceAdapter: () => SingleWorkspaceAdapter,
+  WorkspaceNotFoundError: () => WorkspaceNotFoundError
+});
+var SingleWorkspaceAdapter, WorkspaceNotFoundError;
+var init_Workspaces = __esm({
+  "src/providers/Workspaces.ts"() {
+    "use strict";
+    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();
+      }
+    };
+    WorkspaceNotFoundError = class extends Error {
+      code = "workspace-not-found";
+      workspaceId;
+      constructor(workspaceId) {
+        super(`No workspace with id "${workspaceId}" is available on this server.`);
+        this.name = "WorkspaceNotFoundError";
+        this.workspaceId = workspaceId;
+      }
+    };
+  }
+});
+
+// src/providers/InMemoryWorkspaceProvider.ts
+var import_core6, InMemoryWorkspaceProvider;
+var init_InMemoryWorkspaceProvider = __esm({
+  "src/providers/InMemoryWorkspaceProvider.ts"() {
+    "use strict";
+    import_core6 = require("@apicircle/core");
     InMemoryWorkspaceProvider = class {
       state;
       constructor(initial) {
@@ -3037,7 +4566,7 @@ var init_InMemoryWorkspaceProvider = __esm({
         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 };
       }
@@ -3057,11 +4586,11 @@ var FileBackedWorkspaceProvider_exports = {};
 __export(FileBackedWorkspaceProvider_exports, {
   FileBackedWorkspaceProvider: () => FileBackedWorkspaceProvider
 });
-var import_core5, import_file_backed, FileBackedWorkspaceProvider;
+var import_core7, import_file_backed, FileBackedWorkspaceProvider;
 var init_FileBackedWorkspaceProvider = __esm({
   "src/providers/FileBackedWorkspaceProvider.ts"() {
     "use strict";
-    import_core5 = require("@apicircle/core");
+    import_core7 = require("@apicircle/core");
     import_file_backed = require("@apicircle/core/workspace/file-backed");
     FileBackedWorkspaceProvider = class {
       constructor(dir) {
@@ -3078,7 +4607,7 @@ var init_FileBackedWorkspaceProvider = __esm({
       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 };
         });
@@ -3098,6 +4627,58 @@ var init_FileBackedWorkspaceProvider = __esm({
   }
 });
 
+// src/providers/GitBackedWorkspaceProvider.ts
+var import_core8, import_file_backed2, GIT_SYNCED_FILENAME, GitBackedWorkspaceProvider;
+var init_GitBackedWorkspaceProvider = __esm({
+  "src/providers/GitBackedWorkspaceProvider.ts"() {
+    "use strict";
+    import_core8 = require("@apicircle/core");
+    import_file_backed2 = require("@apicircle/core/workspace/file-backed");
+    GIT_SYNCED_FILENAME = "workspace.json";
+    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 MultiWorkspaceProvider_exports = {};
 __export(MultiWorkspaceProvider_exports, {
@@ -3194,13 +4775,14 @@ var init_MultiWorkspaceProvider = __esm({
           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 {
@@ -3292,19 +4874,275 @@ var init_InProcessMockController = __esm({
   }
 });
 
+// src/config/snippets.ts
+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;
+  }
+}
+var path, AI_CLIENTS;
+var init_snippets = __esm({
+  "src/config/snippets.ts"() {
+    "use strict";
+    path = __toESM(require("path"), 1);
+    AI_CLIENTS = [
+      "claude-desktop",
+      "claude-code",
+      "codex",
+      "cursor",
+      "continue",
+      "cline",
+      "zed",
+      "windsurf",
+      "github-copilot",
+      "chatgpt",
+      "generic"
+    ];
+  }
+});
+
+// src/prompts/mcpPrompts.ts
+var MCP_PROMPT_CATEGORIES, MCP_PROMPTS;
+var init_mcpPrompts = __esm({
+  "src/prompts/mcpPrompts.ts"() {
+    "use strict";
+    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" }
+    ];
+    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 src_exports = {};
 __export(src_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
 });
 function createMcpServer(options) {
   const workspaces = options.workspaces ?? new SingleWorkspaceAdapter(
@@ -3322,7 +5160,8 @@ function createMcpServer(options) {
     }
   });
 }
-var init_src = __esm({
+var import_streamableHttp, import_stdio2;
+var init_src2 = __esm({
   "src/index.ts"() {
     "use strict";
     init_McpHost();
@@ -3333,13 +5172,18 @@ var init_src = __esm({
     init_Workspaces();
     init_InMemoryWorkspaceProvider();
     init_FileBackedWorkspaceProvider();
+    init_GitBackedWorkspaceProvider();
     init_MultiWorkspaceProvider();
     init_InProcessMockController();
+    init_snippets();
+    init_mcpPrompts();
+    import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+    import_stdio2 = require("@modelcontextprotocol/sdk/server/stdio.js");
   }
 });
 
 // src/bin/mcp-server.ts
-var path = __toESM(require("path"), 1);
+var path2 = __toESM(require("path"), 1);
 var import_node_fs = require("fs");
 
 // src/bin/args.ts
@@ -3355,14 +5199,17 @@ function formatHelp() {
 Starts the API Circle MCP stdio server for AI clients.
 
 Options:
-  --workspace <dir>  Registry root or single-workspace directory.
-                     Defaults to APICIRCLE_WORKSPACE, then the current directory.
+  --workspace <dir>  Workspace directory. Auto-detected layout:
+                       \u2022 registry.json   \u2192 multi-workspace registry root
+                       \u2022 workspace.json  \u2192 single workspace / Git-backed dir
+                     Defaults to APICIRCLE_WORKSPACE env var, then cwd.
   -v, -V, --version  Print the version number.
   -h, --help         Show help.
 
 Examples:
   apicircle-mcp
-  apicircle-mcp --workspace ./api-circle-workspaces
+  apicircle-mcp --workspace ~/.apicircle
+  apicircle-mcp --workspace ./my-repo/.apicircle
 `;
 }
 
@@ -3371,11 +5218,11 @@ init_packageVersion();
 function getWorkspaceDir() {
   const argIdx = process.argv.indexOf("--workspace");
   if (argIdx !== -1 && process.argv[argIdx + 1]) {
-    return path.resolve(process.argv[argIdx + 1]);
+    return path2.resolve(process.argv[argIdx + 1]);
   }
   const env = process.env.APICIRCLE_WORKSPACE;
-  if (env) return path.resolve(env);
-  return path.resolve(process.cwd());
+  if (env) return path2.resolve(env);
+  return path2.resolve(process.cwd());
 }
 async function fileExists(p) {
   try {
@@ -3403,19 +5250,21 @@ async function main() {
     { InProcessMockController: InProcessMockController2 },
     { SingleWorkspaceAdapter: SingleWorkspaceAdapter2 }
   ] = await Promise.all([
-    Promise.resolve().then(() => (init_src(), src_exports)),
+    Promise.resolve().then(() => (init_src2(), src_exports)),
     Promise.resolve().then(() => (init_FileBackedWorkspaceProvider(), FileBackedWorkspaceProvider_exports)),
     Promise.resolve().then(() => (init_MultiWorkspaceProvider(), MultiWorkspaceProvider_exports)),
     Promise.resolve().then(() => (init_InProcessMockController(), InProcessMockController_exports)),
     Promise.resolve().then(() => (init_Workspaces(), Workspaces_exports))
   ]);
   const dir = getWorkspaceDir();
-  const registryPath = path.join(dir, "registry.json");
-  const isRegistryRoot = await fileExists(registryPath);
+  const [hasRegistry, hasWorkspaceJson] = await Promise.all([
+    fileExists(path2.join(dir, "registry.json")),
+    fileExists(path2.join(dir, "workspace.json"))
+  ]);
   const mock = new InProcessMockController2();
-  if (isRegistryRoot) {
-    const workspaces2 = new MultiWorkspaceProvider2(dir);
-    const registry = await workspaces2.init();
+  if (hasRegistry) {
+    const workspaces = new MultiWorkspaceProvider2(dir);
+    const registry = await workspaces.init();
     if (!registry.activeWorkspaceId) {
       process.stderr.write(
         `apicircle-mcp: registry at ${dir} has no active workspace. Open the desktop app once, or run \`apicircle workspaces create <name>\`.
@@ -3423,21 +5272,33 @@ async function main() {
       );
       process.exit(1);
     }
-    const workspace2 = workspaces2.activeProvider();
-    const host2 = createMcpServer2({ workspace: workspace2, workspaces: workspaces2, mock });
+    const workspace = workspaces.activeProvider();
+    const host = createMcpServer2({ workspace, workspaces, mock });
     process.stderr.write(
       `apicircle-mcp: multi-workspace mode \xB7 ${registry.workspaces.length} workspace(s) \xB7 active=${registry.activeWorkspaceId}
 `
     );
-    await host2.connect();
+    await host.connect();
     return;
   }
-  const workspace = new FileBackedWorkspaceProvider2(dir);
-  const workspaces = new SingleWorkspaceAdapter2(workspace, null);
-  const host = createMcpServer2({ workspace, workspaces, mock });
-  process.stderr.write(`apicircle-mcp: single-workspace mode \xB7 ${dir}
+  if (hasWorkspaceJson) {
+    const workspace = new FileBackedWorkspaceProvider2(dir);
+    const workspaces = new SingleWorkspaceAdapter2(workspace, null);
+    const host = createMcpServer2({ workspace, workspaces, mock });
+    process.stderr.write(`apicircle-mcp: single-workspace mode \xB7 ${dir}
 `);
-  await host.connect();
+    await host.connect();
+    return;
+  }
+  process.stderr.write(
+    `apicircle-mcp: no workspace found at ${dir}.
+Expected one of:
+  \u2022 registry.json   (multi-workspace registry root, e.g. ~/.apicircle/)
+  \u2022 workspace.json  (single workspace or Git-backed .apicircle/ directory)
+Point --workspace at the correct directory, or set APICIRCLE_WORKSPACE.
+`
+  );
+  process.exit(1);
 }
 main().catch((err) => {
   process.stderr.write(