@apicircle/mcp-server 1.0.9 → 1.1.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,21 +17,37 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AI_CLIENTS: () => AI_CLIENTS,
   FileBackedWorkspaceProvider: () => FileBackedWorkspaceProvider,
+  GitBackedWorkspaceProvider: () => GitBackedWorkspaceProvider,
   InMemoryWorkspaceProvider: () => InMemoryWorkspaceProvider,
   InProcessMockController: () => InProcessMockController,
+  MCP_PROMPTS: () => MCP_PROMPTS,
+  MCP_PROMPT_CATEGORIES: () => MCP_PROMPT_CATEGORIES,
   McpHost: () => McpHost,
   MultiWorkspaceProvider: () => MultiWorkspaceProvider,
   SingleWorkspaceAdapter: () => SingleWorkspaceAdapter,
+  StdioServerTransport: () => import_stdio2.StdioServerTransport,
+  StreamableHTTPServerTransport: () => import_streamableHttp.StreamableHTTPServerTransport,
   TOOL_REGISTRY: () => TOOL_REGISTRY,
   WorkspaceNotFoundError: () => WorkspaceNotFoundError,
+  buildSnippetVariants: () => buildSnippetVariants,
   createMcpServer: () => createMcpServer,
-  getTool: () => getTool
+  getTool: () => getTool,
+  resolveAiClientConfigPath: () => resolveAiClientConfigPath
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -41,9 +59,10 @@ var import_zod = require("zod");
 // package.json
 var package_default = {
   name: "@apicircle/mcp-server",
-  version: "1.0.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",
@@ -86,7 +105,8 @@ var package_default = {
     "apicircle-mcp": "./dist/bin/mcp-server.cjs"
   },
   exports: {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./prompts": "./src/prompts/mcpPrompts.ts"
   },
   files: [
     "dist"
@@ -105,6 +125,16 @@ var package_default = {
           types: "./dist/index.d.cts",
           default: "./dist/index.cjs"
         }
+      },
+      "./prompts": {
+        import: {
+          types: "./dist/prompts/mcpPrompts.d.ts",
+          default: "./dist/prompts/mcpPrompts.js"
+        },
+        require: {
+          types: "./dist/prompts/mcpPrompts.d.cts",
+          default: "./dist/prompts/mcpPrompts.cjs"
+        }
       }
     }
   },
@@ -122,6 +152,7 @@ var package_default = {
     zod: "^3.23.0"
   },
   devDependencies: {
+    "@apicircle/git": "workspace:*",
     "@types/node": "^20.0.0",
     tsup: "^8.3.0",
     typescript: "^5.4.0",
@@ -590,6 +621,7 @@ var workspaceListTool = {
 var import_zod5 = require("zod");
 var import_shared2 = require("@apicircle/shared");
 var import_core2 = require("@apicircle/core");
+var FULL_REQUEST_AUTH = import_zod5.z.object({ type: import_zod5.z.string() }).passthrough();
 var HTTP_METHOD = import_zod5.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 var requestCreateTool = {
   name: "request.create",
@@ -677,16 +709,18 @@ var requestDeleteTool = {
 };
 var folderCreateTool = {
   name: "folder.create",
-  description: "Create a folder under an optional parent folder.",
+  description: "Create a folder under an optional parent folder. Optionally seed folder-level `auth` so descendants with `auth: inherit` resolve to it immediately \u2014 saves a follow-up `folder.update` round-trip.",
   inputSchema: import_zod5.z.object({
     name: import_zod5.z.string().default("New folder"),
-    parentId: import_zod5.z.string().nullable().optional()
+    parentId: import_zod5.z.string().nullable().optional(),
+    auth: FULL_REQUEST_AUTH.optional()
   }),
   async handler(input, ctx) {
     const folder = {
       id: (0, import_shared2.generateId)(),
       name: input.name,
-      parentId: input.parentId ?? null
+      parentId: input.parentId ?? null,
+      ...input.auth ? { auth: input.auth } : {}
     };
     const out = await ctx.workspace.apply({ kind: "folder.create", folder });
     return { id: folder.id, changedIds: out.changedIds };
@@ -710,18 +744,39 @@ var folderReadTool = {
 };
 var folderUpdateTool = {
   name: "folder.update",
-  description: "Move a folder to a new parent (or to root with parentId: null).",
+  description: 'Update a folder. Supply `parentId` to move it (use `null` for root), `name` to rename, and/or `auth` to set the folder-level auth that descendants inherit when their `auth.type === "inherit"`. Set `clearAuth: true` to remove the folder-level auth entirely (descendants then fall through to the next ancestor). The `auth` field accepts any of the 17 RequestAuth types \u2014 same surface as `request.update`. The simple ones (bearer / basic / api-key / custom-header / none / inherit) are easy to author by hand; OAuth2 / AWS SigV4 / Digest / NTLM / Hawk / JWT Bearer require the full canonical shape (see `RequestAuth` in `@apicircle/shared/types.ts`).',
   inputSchema: import_zod5.z.object({
     id: import_zod5.z.string(),
-    parentId: import_zod5.z.string().nullable()
+    parentId: import_zod5.z.string().nullable().optional(),
+    name: import_zod5.z.string().optional(),
+    auth: FULL_REQUEST_AUTH.optional(),
+    clearAuth: import_zod5.z.boolean().optional()
+  }).refine((v) => !(v.auth !== void 0 && v.clearAuth === true), {
+    message: "Pass either `auth` or `clearAuth: true`, not both."
   }),
   async handler(input, ctx) {
-    const out = await ctx.workspace.apply({
-      kind: "folder.move",
-      id: input.id,
-      newParentId: input.parentId
-    });
-    return { changedIds: out.changedIds };
+    const changedIds = [];
+    if (input.parentId !== void 0) {
+      const out = await ctx.workspace.apply({
+        kind: "folder.move",
+        id: input.id,
+        newParentId: input.parentId
+      });
+      changedIds.push(...out.changedIds);
+    }
+    const updatePatch = {};
+    if (input.name !== void 0) updatePatch.name = input.name;
+    if (input.auth !== void 0) updatePatch.auth = input.auth;
+    else if (input.clearAuth === true) updatePatch.auth = void 0;
+    if (input.name !== void 0 || input.auth !== void 0 || input.clearAuth === true) {
+      const out = await ctx.workspace.apply({
+        kind: "folder.update",
+        id: input.id,
+        patch: updatePatch
+      });
+      changedIds.push(...out.changedIds);
+    }
+    return { changedIds: Array.from(new Set(changedIds)) };
   }
 };
 var folderDeleteTool = {
@@ -1695,7 +1750,9 @@ var CONDITION_CLAUSE_NL = import_zod9.z.object({
 var RESPONSE_RULE_NL = import_zod9.z.object({
   name: import_zod9.z.string(),
   enabled: import_zod9.z.boolean().default(true),
-  when: import_zod9.z.array(CONDITION_CLAUSE_NL).default([]),
+  // At least one clause — a no-condition rule is dead (the runtime engine skips
+  // clause-less rules), so it never fires (mirrors the VS Code parser's reject).
+  when: import_zod9.z.array(CONDITION_CLAUSE_NL).min(1),
   response: import_zod9.z.object({
     status: import_zod9.z.number().int().min(100).max(599).default(200),
     jsonBody: import_zod9.z.string().default("{}")
@@ -1745,7 +1802,7 @@ function buildEndpoint(input) {
   };
   const validationRules = input.validationRules ?? [];
   const responseRules = input.responseRules ?? [];
-  const multipliers = input.multipliers ?? [];
+  const multipliers = (input.multipliers ?? []).slice(0, import_shared3.MAX_RESPONSE_MULTIPLIERS);
   if (multipliers.length > 0) {
     defaultResponse.multipliers = multipliers.map((m) => ({
       id: (0, import_shared3.generateId)(),
@@ -1978,10 +2035,13 @@ var promptSetPlanVariablesTool = {
 };
 var promptCreateMockServerTool = {
   name: "prompt.create_mock_server",
-  description: "Create a manual-mode mock server with optional inline endpoints from an LLM-shaped JSON envelope. The model produces `{ name, defaultPort?, endpoints: [{ method, pathPattern, name?, response?, validationRules?, responseRules?, multipliers? }] }`; this tool generates ids for the server and every endpoint / rule, then persists in one shot.",
+  description: "Create a manual-mode mock server with optional inline endpoints from an LLM-shaped JSON envelope. The model produces `{ name, defaultPort?, endpoints: [{ method, pathPattern, name?, response?, validationRules?, responseRules?, multiplier? }] }`; this tool generates ids for the server and every endpoint / rule, then persists in one shot.",
   inputSchema: import_zod9.z.object({
     name: import_zod9.z.string().min(1),
-    defaultPort: import_zod9.z.number().int().positive().nullable().optional(),
+    // Mirrors mock.create_manual / mock.start / mock.set_default_port:
+    // reject out-of-range ports at the tool boundary so a prompt that
+    // returns a stray port (1, 80, 999999) never leaks into the synced doc.
+    defaultPort: import_zod9.z.number().int().min(1024).max(65535).nullable().optional(),
     endpoints: import_zod9.z.array(ENDPOINT_INPUT).default([])
   }),
   async handler(input, ctx) {
@@ -2008,7 +2068,7 @@ var promptCreateMockServerTool = {
 };
 var promptAddMockEndpointTool = {
   name: "prompt.add_mock_endpoint",
-  description: "Append a new endpoint (with optional inline validation rules, response rules, and multipliers) to an existing mock server from an LLM-shaped JSON envelope. All ids are auto-generated; the existing endpoints stay in place.",
+  description: "Append a new endpoint (with optional inline validation rules, response rules, and a single response multiplier) to an existing mock server from an LLM-shaped JSON envelope. All ids are auto-generated; the existing endpoints stay in place.",
   inputSchema: import_zod9.z.object({
     mockId: import_zod9.z.string(),
     method: HTTP_METHOD2,
@@ -2111,7 +2171,7 @@ var promptSetEndpointResponseRulesTool = {
 };
 var promptSetEndpointMultipliersTool = {
   name: "prompt.set_endpoint_multipliers",
-  description: "Replace the response multipliers on an endpoint's defaultResponse with an LLM-shaped list. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Every multiplier gets a fresh id. Empty array clears all multipliers.",
+  description: "Replace the response multipliers on an endpoint's defaultResponse with an LLM-shaped list. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Every multiplier gets a fresh id. Empty array clears all. Capped at MAX_RESPONSE_MULTIPLIERS (1) \u2014 extra entries are rejected.",
   inputSchema: import_zod9.z.object({
     mockId: import_zod9.z.string(),
     endpointId: import_zod9.z.string(),
@@ -2122,6 +2182,9 @@ var promptSetEndpointMultipliersTool = {
     const mock = state.synced.mockServers[input.mockId];
     if (!mock) return { ok: false, error: "mock not found" };
     const multipliers = input.multipliers;
+    if (multipliers.length > import_shared3.MAX_RESPONSE_MULTIPLIERS) {
+      return { ok: false, error: "too many multipliers" };
+    }
     const next = patchEndpoint(mock, input.endpointId, (e) => ({
       ...e,
       defaultResponse: {
@@ -2142,6 +2205,53 @@ var promptSetEndpointMultipliersTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
+var PARAM_NL = import_zod9.z.object({
+  name: import_zod9.z.string(),
+  typeHint: import_zod9.z.string().optional(),
+  required: import_zod9.z.boolean().optional(),
+  description: import_zod9.z.string().optional(),
+  example: import_zod9.z.string().optional()
+});
+var promptSetEndpointRequestSchemaTool = {
+  name: "prompt.set_endpoint_request_schema",
+  description: "Declare an endpoint's expected inputs with an LLM-shaped list: path / query / header / cookie params (name + optional typeHint / required / description / example) plus an optional body-shape doc. Every param gets a fresh id; omitted lists are cleared. Documentation-only \u2014 it drives the editor UI + OpenAPI export, not runtime gating (use validation rules for that).",
+  inputSchema: import_zod9.z.object({
+    mockId: import_zod9.z.string(),
+    endpointId: import_zod9.z.string(),
+    pathParams: import_zod9.z.array(PARAM_NL).default([]),
+    queryParams: import_zod9.z.array(PARAM_NL).default([]),
+    headers: import_zod9.z.array(PARAM_NL).default([]),
+    cookies: import_zod9.z.array(PARAM_NL).default([]),
+    body: import_zod9.z.object({ description: import_zod9.z.string().optional(), example: import_zod9.z.string().optional() }).optional()
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.mockId];
+    if (!mock) return { ok: false, error: "mock not found" };
+    const toParams = (list) => list.map((p) => ({
+      id: (0, import_shared3.generateId)(),
+      name: p.name,
+      typeHint: p.typeHint,
+      required: p.required,
+      description: p.description,
+      example: p.example
+    }));
+    const body = input.body && (input.body.description || input.body.example) ? input.body : void 0;
+    const next = patchEndpoint(mock, input.endpointId, (e) => ({
+      ...e,
+      requestSchema: {
+        pathParams: toParams(input.pathParams),
+        queryParams: toParams(input.queryParams),
+        headers: toParams(input.headers),
+        cookies: toParams(input.cookies),
+        body
+      }
+    }));
+    if (!next) return { ok: false, error: "endpoint not found" };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
 
 // src/tools/globalAssets.ts
 var import_zod10 = require("zod");
@@ -2392,10 +2502,14 @@ var mockListTool = {
 };
 var mockStartTool = {
   name: "mock.start",
-  description: "Start a mock server by id. Returns the bound port. Errors if the mock is already running or the requested port is in use.",
+  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();
@@ -2435,13 +2549,44 @@ var mockDeleteTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
+var mockSetDefaultPortTool = {
+  name: "mock.set_default_port",
+  description: "Persist a new `defaultPort` on an existing mock server. Pass an integer 1024-65535 to pin the port, or `null` for 'pick a free port at next start'. Does NOT restart a running mock \u2014 the change takes effect on the next mock.start.",
+  inputSchema: import_zod11.z.object({
+    id: import_zod11.z.string(),
+    defaultPort: import_zod11.z.number().int().min(1024).max(65535).nullable()
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.id];
+    if (!mock) return { ok: false, error: "mock not found" };
+    if (mock.defaultPort === input.defaultPort) {
+      return { ok: true, defaultPort: mock.defaultPort, changed: false };
+    }
+    const next = {
+      ...mock,
+      defaultPort: input.defaultPort,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return {
+      ok: true,
+      defaultPort: input.defaultPort,
+      changed: true,
+      changedIds: out.changedIds
+    };
+  }
+};
 var HTTP_METHOD3 = import_zod11.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 var mockCreateManualTool = {
   name: "mock.create_manual",
   description: "Create an empty manual-mode mock server. Use `mock.add_endpoint` afterward to populate it. CORS defaults to off (same-origin only); enable + list explicit origins via `mock.update_cors` if cross-origin access is needed.",
   inputSchema: import_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();
@@ -2643,7 +2788,10 @@ var RESPONSE_RULE = import_zod11.z.object({
   id: import_zod11.z.string().optional(),
   name: import_zod11.z.string(),
   enabled: import_zod11.z.boolean().default(true),
-  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("{}")
@@ -2745,9 +2893,61 @@ var mockSetResponseRulesTool = {
     return { ok: true, changedIds: out.changedIds };
   }
 };
+var PARAM = import_zod11.z.object({
+  id: import_zod11.z.string().optional(),
+  name: import_zod11.z.string(),
+  typeHint: import_zod11.z.string().optional(),
+  required: import_zod11.z.boolean().optional(),
+  description: import_zod11.z.string().optional(),
+  example: import_zod11.z.string().optional()
+});
+var REQUEST_SCHEMA_BODY = import_zod11.z.object({ description: import_zod11.z.string().optional(), example: import_zod11.z.string().optional() }).optional();
+function normalizeSchemaBody(body) {
+  if (!body || !body.description && !body.example) return void 0;
+  return body;
+}
+var mockSetRequestSchemaTool = {
+  name: "mock.set_request_schema",
+  description: "Replace an endpoint's requestSchema \u2014 the declared path / query / header / cookie params plus an optional body-shape doc. Params without an `id` get a fresh one; omitted lists are cleared. Documentation-only (drives the editor UI + OpenAPI export); runtime gating lives in the validation rules.",
+  inputSchema: import_zod11.z.object({
+    mockId: import_zod11.z.string(),
+    endpointId: import_zod11.z.string(),
+    pathParams: import_zod11.z.array(PARAM).default([]),
+    queryParams: import_zod11.z.array(PARAM).default([]),
+    headers: import_zod11.z.array(PARAM).default([]),
+    cookies: import_zod11.z.array(PARAM).default([]),
+    body: REQUEST_SCHEMA_BODY
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const mock = state.synced.mockServers[input.mockId];
+    if (!mock) return { ok: false, error: "mock not found" };
+    const toParams = (list) => list.map((p) => ({
+      id: p.id ?? (0, import_shared5.generateId)(),
+      name: p.name,
+      typeHint: p.typeHint,
+      required: p.required,
+      description: p.description,
+      example: p.example
+    }));
+    const next = patchEndpoint2(mock, input.endpointId, (e) => ({
+      ...e,
+      requestSchema: {
+        pathParams: toParams(input.pathParams),
+        queryParams: toParams(input.queryParams),
+        headers: toParams(input.headers),
+        cookies: toParams(input.cookies),
+        body: normalizeSchemaBody(input.body)
+      }
+    }));
+    if (!next) return { ok: false, error: "endpoint not found" };
+    const out = await ctx.workspace.apply({ kind: "mock.upsert", mock: next });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
 var mockSetMultipliersTool = {
   name: "mock.set_multipliers",
-  description: "Replace the response multipliers on an endpoint's defaultResponse. Multipliers expand an array at `targetJsonPath` to a count derived from a request value. Empty array clears all multipliers.",
+  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(),
@@ -2758,6 +2958,9 @@ var mockSetMultipliersTool = {
     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: {
@@ -2779,6 +2982,1290 @@ var mockSetMultipliersTool = {
   }
 };
 
+// src/tools/releases.ts
+var import_zod12 = require("zod");
+var import_core4 = require("@apicircle/core");
+var releaseListTool = {
+  name: "release.list",
+  description: "List this workspace's published releases (newest first) with their notes, snapshot fingerprint, and deprecated / withdrawn flags. Returns the current version too.",
+  inputSchema: import_zod12.z.object({}),
+  async handler(_input, ctx) {
+    const state = await ctx.workspace.read();
+    const ledger = state.synced.releases.self;
+    if (!ledger) {
+      return { currentVersion: null, count: 0, versions: [] };
+    }
+    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 };
+  }
+};
+var releasePublishTool = {
+  name: "release.publish",
+  description: "Publish a new release of this workspace. Appends a semver version + markdown notes to the ledger and bumps currentVersion. The release is fingerprinted with a SHA-256 of the workspace at publish time. Rejects invalid semver or a duplicate version. Does NOT create a Git tag or GitHub Release.",
+  inputSchema: import_zod12.z.object({
+    version: import_zod12.z.string().min(1).describe('Semantic version, e.g. "1.2.0".'),
+    notes: import_zod12.z.string().default("").describe("Markdown release notes."),
+    sha: import_zod12.z.string().optional().describe("Optional source commit SHA for bookkeeping."),
+    tagName: import_zod12.z.string().optional().describe("Optional git tag name for bookkeeping.")
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    let entry;
+    try {
+      entry = await (0, import_core4.buildReleaseEntry)(state.synced, {
+        version: input.version,
+        notes: input.notes,
+        sha: input.sha,
+        tagName: input.tagName
+      });
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.publish failed" };
+    }
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.publish", entry });
+      const after = (await ctx.workspace.read()).synced.releases.self;
+      return {
+        ok: true,
+        version: entry.version,
+        currentVersion: after?.currentVersion ?? entry.version,
+        workspaceSnapshot: entry.workspaceSnapshot,
+        changedIds: out.changedIds
+      };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.publish failed" };
+    }
+  }
+};
+var releaseDeprecateTool = {
+  name: "release.deprecate",
+  description: "Mark a published version as deprecated (soft signal). Consumers see a warning but the version stays installable. Errors if the version is unknown or no ledger exists.",
+  inputSchema: import_zod12.z.object({ version: import_zod12.z.string().min(1) }),
+  async handler(input, ctx) {
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.deprecate", version: input.version });
+      return { ok: true, version: input.version, changedIds: out.changedIds };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.deprecate failed" };
+    }
+  }
+};
+var releaseYankTool = {
+  name: "release.yank",
+  description: "Withdraw (yank) a published version (hard signal). Consumers are warned the version is broken / unsafe and told to move to a different one. The entry stays in the ledger. Errors if the version is unknown or no ledger exists.",
+  inputSchema: import_zod12.z.object({ version: import_zod12.z.string().min(1) }),
+  async handler(input, ctx) {
+    try {
+      const out = await ctx.workspace.apply({ kind: "release.yank", version: input.version });
+      return { ok: true, version: input.version, changedIds: out.changedIds };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : "release.yank failed" };
+    }
+  }
+};
+
+// src/tools/linkedWorkspaces.ts
+var import_zod13 = require("zod");
+function summarize(link, currentVersion) {
+  return {
+    id: link.id,
+    name: link.name,
+    kind: link.kind,
+    description: link.description,
+    source: link.source,
+    scope: link.scope,
+    pinnedVersion: link.pinnedVersion,
+    requiredSecretKeyIds: link.requiredSecretKeyIds,
+    marketplace: link.marketplace,
+    cachedCurrentVersion: currentVersion
+  };
+}
+var linkedListTool = {
+  name: "linked.list",
+  description: "List the workspaces this workspace links to (consumes). Each entry includes its source repo/branch, scope, pinned version, required secret-key ids, and the current version of its cached release ledger.",
+  inputSchema: import_zod13.z.object({}),
+  async handler(_input, ctx) {
+    const state = await ctx.workspace.read();
+    const links = Object.values(state.synced.linkedWorkspaces);
+    return {
+      count: links.length,
+      links: links.map(
+        (l) => summarize(l, state.synced.releases.perLink[l.id]?.currentVersion ?? null)
+      )
+    };
+  }
+};
+var linkedGetTool = {
+  name: "linked.get",
+  description: "Read one linked workspace by id, including its cached release ledger (the versions available to pin to).",
+  inputSchema: import_zod13.z.object({ id: import_zod13.z.string() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    const ledger = state.synced.releases.perLink[input.id] ?? null;
+    return {
+      ok: true,
+      link: summarize(link, ledger?.currentVersion ?? null),
+      ledger
+    };
+  }
+};
+var linkedSetConfigTool = {
+  name: "linked.set_config",
+  description: "Update an existing linked workspace's config: rename, pin/unpin a version (must exist in the cached ledger), set scope, session mode, required secret-key ids, or marketplace metadata. Only supplied fields change. Does NOT fetch from the network.",
+  inputSchema: import_zod13.z.object({
+    id: import_zod13.z.string(),
+    name: import_zod13.z.string().optional(),
+    description: import_zod13.z.string().optional(),
+    pinnedVersion: import_zod13.z.string().nullable().optional().describe("null = unpin (track source HEAD)."),
+    scope: import_zod13.z.array(import_zod13.z.enum(["collections", "environments"])).optional(),
+    sessionMode: import_zod13.z.enum(["workspace", "dedicated"]).optional(),
+    requiredSecretKeyIds: import_zod13.z.array(import_zod13.z.string()).optional(),
+    marketplace: import_zod13.z.object({
+      listedAs: import_zod13.z.string(),
+      tags: import_zod13.z.array(import_zod13.z.string()),
+      summary: import_zod13.z.string()
+    }).nullable().optional().describe("null = clear marketplace metadata.")
+  }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    if (input.pinnedVersion !== void 0 && input.pinnedVersion !== null) {
+      const cached = state.synced.releases.perLink[input.id]?.versions ?? [];
+      if (!cached.some((v) => v.version === input.pinnedVersion)) {
+        return {
+          ok: false,
+          error: `Version ${input.pinnedVersion} is not in the cached ledger \u2014 refresh the link first`
+        };
+      }
+    }
+    const next = {
+      ...link,
+      ...input.name !== void 0 ? { name: input.name } : {},
+      ...input.description !== void 0 ? { description: input.description } : {},
+      ...input.pinnedVersion !== void 0 ? { pinnedVersion: input.pinnedVersion } : {},
+      ...input.scope !== void 0 ? { scope: input.scope } : {},
+      ...input.requiredSecretKeyIds !== void 0 ? { requiredSecretKeyIds: input.requiredSecretKeyIds } : {},
+      ...input.sessionMode !== void 0 ? { source: { ...link.source, sessionMode: input.sessionMode } } : {}
+    };
+    if (input.marketplace !== void 0) {
+      if (input.marketplace === null) {
+        delete next.marketplace;
+      } else {
+        next.marketplace = input.marketplace;
+      }
+    }
+    const out = await ctx.workspace.apply({ kind: "linkedWorkspace.upsert", link: next });
+    return {
+      ok: true,
+      changedIds: out.changedIds,
+      link: summarize(next, state.synced.releases.perLink[input.id]?.currentVersion ?? null)
+    };
+  }
+};
+var linkedUnlinkTool = {
+  name: "linked.unlink",
+  description: "Unlink a workspace by id. Removes the link, its cached release ledger, every local override for it, the cached collections/environments snapshot, and any per-link session entry. The source repo is untouched.",
+  inputSchema: import_zod13.z.object({ id: import_zod13.z.string() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    if (!state.synced.linkedWorkspaces[input.id]) {
+      return { ok: false, error: `Linked workspace ${input.id} not found` };
+    }
+    const out = await ctx.workspace.apply({ kind: "linkedWorkspace.remove", id: input.id });
+    return { ok: true, changedIds: out.changedIds };
+  }
+};
+
+// src/tools/githubOps.ts
+var import_zod14 = require("zod");
+var import_core5 = require("@apicircle/core");
+var import_shared6 = require("@apicircle/shared");
+
+// ../git/src/github/errors.ts
+var GitHubError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "GitHubError";
+  }
+  status;
+  body;
+};
+var MissingScopeError = class extends GitHubError {
+  /** Scope strings the API said are missing, e.g. ['pull_request']. */
+  missingScopes;
+  /** Scope strings the token currently grants, parsed from x-oauth-scopes. */
+  grantedScopes;
+  constructor(message, status, missingScopes, grantedScopes) {
+    super(message, status);
+    this.name = "MissingScopeError";
+    this.missingScopes = missingScopes;
+    this.grantedScopes = grantedScopes;
+  }
+};
+var RateLimitedError = class extends GitHubError {
+  /** Unix timestamp (ms) when the rate-limit window resets. */
+  resetAtMs;
+  constructor(message, status, resetAtMs) {
+    super(message, status);
+    this.name = "RateLimitedError";
+    this.resetAtMs = resetAtMs;
+  }
+};
+var UnauthorizedError = class extends GitHubError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "UnauthorizedError";
+  }
+};
+var TimeoutError = class extends GitHubError {
+  /** Timeout that fired, in ms. Useful for the UI message. */
+  timeoutMs;
+  constructor(message, timeoutMs) {
+    super(message, 0);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// ../git/src/github/api.ts
+var API_BASE = "https://api.github.com";
+var LOGIN_BASE = "https://github.com";
+var DEFAULT_TIMEOUT_MS = 15e3;
+var GitHubClient = class {
+  baseUrl;
+  loginBaseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts = {}) {
+    this.baseUrl = opts.baseUrl ?? API_BASE;
+    this.loginBaseUrl = (opts.loginBaseUrl ?? LOGIN_BASE).replace(/\/$/, "");
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Fetch the authenticated user. Doubles as a "verify token" probe — used
+   * by the Secret Vault Sessions tab to refresh the granted-scopes list.
+   */
+  async getViewer(token, opts = {}) {
+    const { json, response } = await this.call(token, "/user", opts);
+    return {
+      viewer: {
+        login: json.login,
+        id: json.id,
+        name: json.name ?? null,
+        avatarUrl: json.avatar_url ?? null
+      },
+      scopes: parseScopes(response.headers)
+    };
+  }
+  /**
+   * List repositories the authenticated user can access. Used by the repo
+   * picker. Capped at 100 sorted by recent push; users with thousands of
+   * repos can paginate later.
+   */
+  async listAccessibleRepos(token, opts = {}) {
+    const { json } = await this.call(
+      token,
+      "/user/repos?per_page=100&sort=pushed&affiliation=owner,collaborator,organization_member",
+      opts
+    );
+    return json.map(normalizeRepo);
+  }
+  /**
+   * Fetch a specific repo. Validates the user-supplied owner/name pair
+   * exists + is accessible, and exposes the default branch.
+   */
+  async getRepo(token, owner, name, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`,
+      opts
+    );
+    return normalizeRepo(json);
+  }
+  /**
+   * Read the head SHA of a branch. Used to seed a new working branch from
+   * main before any edits land.
+   */
+  async getBranchHead(token, owner, name, branch, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches/${encodeURIComponent(branch)}`,
+      opts
+    );
+    return { name: json.name, commitSha: json.commit.sha };
+  }
+  /**
+   * List branches on a repo. Used by the Link Workspace repo-browser to
+   * populate the branch dropdown after the user picks a repo. Capped at
+   * 100 (GitHub's max page size); repos with more branches paginate.
+   */
+  async listBranches(token, owner, name, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/branches?per_page=100`,
+      opts
+    );
+    return json.map((b) => ({ name: b.name, commitSha: b.commit.sha }));
+  }
+  /**
+   * Create a new branch ref pointing at `sha`. The auto-branch flow calls
+   * this with the head SHA from `getBranchHead(main)`.
+   *
+   * GitHub returns 422 with "Reference already exists" when the branch
+   * already exists; that surfaces as a GitHubError(422) so the UI can
+   * prompt for a different name.
+   */
+  async createBranch(token, owner, name, branchName, sha, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs`,
+      {
+        ...opts,
+        method: "POST",
+        body: { ref: `refs/heads/${branchName}`, sha },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { name: branchName, commitSha: json.object.sha };
+  }
+  /**
+   * Read a branch ref's current commit SHA. Used at the start of push-to-
+   * save to find the parent commit before building the new tree.
+   */
+  async getRef(token, owner, name, branch, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(branch)}`,
+      opts
+    );
+    return { ref: json.ref, sha: json.object.sha };
+  }
+  /**
+   * Read a commit's tree SHA. Used so the new tree can be built `base_tree`
+   * — every path we don't override is inherited from the parent.
+   */
+  async getCommit(token, owner, name, sha, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits/${encodeURIComponent(sha)}`,
+      opts
+    );
+    return {
+      sha: json.sha,
+      treeSha: json.tree.sha,
+      message: json.message
+    };
+  }
+  /**
+   * Upload a blob to the repo and return its SHA. Used by push-to-save
+   * (P4.3b) for binary attachments — text files go straight into a tree
+   * entry's `content`, but binary bytes have to go through a blob first.
+   *
+   * `content` is base64 when `encoding === 'base64'`. GitHub stores blobs
+   * deduplicated by their git-sha1 (not our sha256), so re-uploading the
+   * same bytes is cheap on their side; we save a roundtrip locally by
+   * tracking lastPushedBlobSha per slot in a future revision.
+   */
+  async createBlob(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/blobs`,
+      {
+        ...opts,
+        method: "POST",
+        body: { content: args.content, encoding: args.encoding },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { sha: json.sha, size: json.size ?? 0 };
+  }
+  /**
+   * Build a new tree from `entries`, layered over `baseTreeSha`. Entries
+   * with `content` are inlined (text path); entries with a pre-uploaded
+   * `sha` reference an existing blob (binary path — used by attachments).
+   */
+  async createTree(token, owner, name, args, opts = {}) {
+    const tree = args.entries.map((e) => ({
+      path: e.path,
+      mode: e.mode ?? "100644",
+      type: e.type ?? "blob",
+      ...e.content !== void 0 ? { content: e.content } : {},
+      ...e.sha !== void 0 ? { sha: e.sha } : {}
+    }));
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/trees`,
+      {
+        ...opts,
+        method: "POST",
+        body: { base_tree: args.baseTreeSha, tree },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { sha: json.sha };
+  }
+  /**
+   * Create a new commit object pointing at the given tree, with the given
+   * parents. Returns the new commit's SHA + the tree it points at.
+   */
+  async createCommit(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/commits`,
+      {
+        ...opts,
+        method: "POST",
+        body: {
+          message: args.message,
+          tree: args.treeSha,
+          parents: args.parents
+        },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { sha: json.sha, treeSha: json.tree.sha };
+  }
+  /**
+   * Fast-forward a branch ref to a new commit SHA. Pass `force: true` to
+   * skip the FF check (we don't — push-to-save is always FF over the ref
+   * we just read with getRef()).
+   */
+  async updateRef(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/heads/${encodeURIComponent(args.branch)}`,
+      {
+        ...opts,
+        method: "PATCH",
+        body: { sha: args.sha, force: args.force ?? false },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { ref: json.ref, sha: json.object.sha };
+  }
+  /**
+   * Search GitHub for public API Circle workspaces. Appends
+   * `topic:apicircle` to the user-supplied query so only repos carrying
+   * the `apicircle` topic — the topic the Releases & Topics dialog
+   * locks onto every workspace repo — surface in results. GitHub
+   * matches the bare query against repository name, description, and
+   * topics, so category words like `payments` narrow the marketplace by
+   * topic. An empty query lists every public API Circle workspace. Top
+   * 30 results. Token is optional — anonymous browsing is supported
+   * (lower GitHub rate limits apply); pass a PAT when one is available
+   * to lift them. `sort` controls ordering: omit for GitHub's
+   * best-match relevance, or pass `'stars'` / `'updated'`.
+   */
+  async searchMarketplaceRepos(token, query, opts = {}) {
+    const { sort, ...callOpts } = opts;
+    const fullQuery = `${query.trim()} topic:apicircle`.trim();
+    const sortParam = sort ? `&sort=${sort}&order=desc` : "";
+    const path2 = `/search/repositories?q=${encodeURIComponent(fullQuery)}&per_page=30${sortParam}`;
+    const { json } = await this.call(token, path2, callOpts);
+    const items = json.items ?? [];
+    return items.map(normalizeMarketplaceRepo);
+  }
+  /**
+   * Start GitHub's OAuth Device Flow. Returns a user-facing code the
+   * user types into github.com/login/device + a device_code the app
+   * polls with. Pure browser-safe: no client_secret involved (device
+   * flow is the only OAuth path GitHub supports for public clients).
+   *
+   * Requires the OAuth App to have "Enable Device Flow" turned on in
+   * its GitHub settings — surface 400 with `not_supported` to the user
+   * if the App owner hasn't done that yet.
+   */
+  async startDeviceFlow(clientId, scope, opts = {}) {
+    const url = `${this.loginBaseUrl}/login/device/code`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      body: JSON.stringify({ client_id: clientId, scope }),
+      signal: opts.signal
+    });
+    if (!response.ok) {
+      throw new GitHubError(
+        `Device-flow start failed: HTTP ${response.status}`,
+        response.status,
+        {}
+      );
+    }
+    const json = await response.json();
+    if (json.error) {
+      throw new GitHubError(json.error_description ?? json.error, 400, json);
+    }
+    return {
+      deviceCode: json.device_code,
+      userCode: json.user_code,
+      verificationUri: json.verification_uri,
+      expiresIn: json.expires_in,
+      interval: json.interval
+    };
+  }
+  /**
+   * Poll for the access token after the user has authorized the device
+   * code. GitHub returns `authorization_pending` until the user
+   * completes the flow, `slow_down` if we polled too fast, then a real
+   * token. Caller wraps this in a polling loop bounded by `expiresIn`.
+   */
+  async pollDeviceToken(clientId, deviceCode, opts = {}) {
+    const url = `${this.loginBaseUrl}/login/oauth/access_token`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id: clientId,
+        device_code: deviceCode,
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+      }),
+      signal: opts.signal
+    });
+    const json = await response.json();
+    if (json.access_token) {
+      return {
+        kind: "granted",
+        accessToken: json.access_token,
+        tokenType: json.token_type ?? "bearer",
+        scope: json.scope ?? ""
+      };
+    }
+    if (json.error === "authorization_pending") return { kind: "pending", slowDown: false };
+    if (json.error === "slow_down") return { kind: "pending", slowDown: true };
+    if (json.error === "expired_token") return { kind: "expired" };
+    if (json.error === "access_denied")
+      return { kind: "denied", reason: json.error_description ?? "User denied authorization" };
+    throw new GitHubError(
+      json.error_description ?? json.error ?? "Device-token poll failed",
+      response.status,
+      json
+    );
+  }
+  /**
+   * Create a lightweight Git tag (a ref under `refs/tags/<name>`) on the
+   * given commit SHA. Used by the publish-release flow when the user
+   * opts in to "Create Git tag v<x.y.z>". Returns the resolved ref.
+   *
+   * GitHub returns 422 with "Reference already exists" when the tag is
+   * a duplicate; that surfaces as a GitHubError(422) so the UI can warn
+   * the user without ever overwriting an existing tag.
+   */
+  async createTag(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs`,
+      {
+        ...opts,
+        method: "POST",
+        body: { ref: `refs/tags/${args.tagName}`, sha: args.sha },
+        requiredScopes: ["repo"]
+      }
+    );
+    return { ref: json.ref, sha: json.object.sha };
+  }
+  /**
+   * Compare two commits. Returns the relationship classification GitHub
+   * gives us: `ahead` (head is descendant of base), `behind` (base is
+   * descendant of head), `identical`, or `diverged` (the two histories
+   * share a base but neither contains the other — typical of a force-push
+   * that rewrote history under us).
+   *
+   * Used by the refresh path so we never silently 3-way-merge across a
+   * history rewrite — divergence steers the user through an explicit
+   * "history rewritten" modal instead of corrupting local state.
+   */
+  async compareCommits(token, owner, name, base, head, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/compare/${encodeURIComponent(
+        base
+      )}...${encodeURIComponent(head)}`,
+      { ...opts, requiredScopes: ["repo"] }
+    );
+    return {
+      status: json.status,
+      aheadBy: json.ahead_by,
+      behindBy: json.behind_by
+    };
+  }
+  /**
+   * Is `ancestor` reachable from `descendant`? Thin wrapper around
+   * `compareCommits` — "ahead" or "identical" means yes; "behind" or
+   * "diverged" means the histories don't fit, so the answer is no.
+   */
+  async isAncestor(token, owner, name, ancestor, descendant, opts = {}) {
+    if (ancestor === descendant) return true;
+    const cmp = await this.compareCommits(token, owner, name, ancestor, descendant, opts);
+    return cmp.status === "ahead" || cmp.status === "identical";
+  }
+  /**
+   * Create a GitHub Release pointing at an existing tag. Used by the
+   * publish-release flow when the user opts in to "Create GitHub
+   * Release". Returns the release's HTML URL so the UI can show a
+   * "Released — view on GitHub" link.
+   *
+   * Pass `prerelease: true` for semver pre-release identifiers (e.g.
+   * `1.0.0-rc.1`); GitHub's Releases UI flags those distinctly.
+   */
+  async createRelease(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(token, `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/releases`, {
+      ...opts,
+      method: "POST",
+      body: {
+        tag_name: args.tagName,
+        name: args.releaseName ?? args.tagName,
+        body: args.body ?? "",
+        draft: args.draft ?? false,
+        prerelease: args.prerelease ?? false
+      },
+      requiredScopes: ["repo"]
+    });
+    return { id: json.id, htmlUrl: json.html_url, tagName: json.tag_name };
+  }
+  /**
+   * Read a tag ref's current commit SHA. Used by the Release & topics
+   * modal to detect whether a tag with the chosen name already exists
+   * (so the UI can surface an "Override existing tag" toggle instead of
+   * silently 422'ing through createTag).
+   *
+   * Returns `null` when the tag doesn't exist (404). Other failures
+   * surface as typed errors.
+   */
+  async getTagSha(token, owner, name, tagName, opts = {}) {
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/tags/${encodeURIComponent(tagName)}`,
+        opts
+      );
+      return json.object.sha;
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * Delete a ref. Used to support the "Override existing tag" path on
+   * the Release & topics modal — we delete the existing tag ref, then
+   * createTag against the new SHA. (GitHub doesn't have a single
+   * "force-update tag" endpoint via the simple refs API.)
+   *
+   * `ref` is the bare suffix, e.g. `tags/v1.0.0` or `heads/feature-x`.
+   */
+  async deleteRef(token, owner, name, ref, opts = {}) {
+    await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/git/refs/${ref.split("/").map(encodeURIComponent).join("/")}`,
+      {
+        ...opts,
+        method: "DELETE",
+        requiredScopes: ["repo"]
+      }
+    );
+  }
+  /**
+   * Read the repo's current topic list. Topics drive marketplace
+   * discoverability — public API Circle workspaces include `apicircle`
+   * plus user-chosen category topics.
+   *
+   * Note: GitHub's topics API uses a custom Accept header, but we treat
+   * that as transport detail; the `application/vnd.github.mercy-preview+json`
+   * preview is now stable so the default Accept works.
+   */
+  async listRepoTopics(token, owner, name, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/topics`,
+      opts
+    );
+    return Array.isArray(json.names) ? json.names : [];
+  }
+  /**
+   * Replace the repo's full topic list. GitHub's `PUT /topics` endpoint
+   * is a full replace (not a merge), so the caller must pass the
+   * complete desired list. Caps at 20 topics; each must match
+   * `^[a-z0-9][a-z0-9-]*$` and be ≤ 50 chars (GitHub enforces this with
+   * a 422). Returns the persisted list.
+   */
+  async setRepoTopics(token, owner, name, topics, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/topics`,
+      {
+        ...opts,
+        method: "PUT",
+        body: { names: topics },
+        requiredScopes: ["repo"]
+      }
+    );
+    return Array.isArray(json.names) ? json.names : [];
+  }
+  /**
+   * Fetch a single file's contents from a branch / commit. Returns
+   * `null` when GitHub answers 404 (file simply doesn't exist on that
+   * ref — the common case for the very first pull). Other failures
+   * surface as the usual typed errors.
+   *
+   * Used by the refresh flow to read remote `workspace.json` so the
+   * 3-way diff can compare it against the local doc.
+   */
+  async getContents(token, owner, name, path2, ref, opts = {}) {
+    const query = `?ref=${encodeURIComponent(ref)}`;
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path2.split("/").map(encodeURIComponent).join("/")}${query}`,
+        opts
+      );
+      if (Array.isArray(json) || json.type !== "file") {
+        throw new GitHubError(`Path ${path2} is not a file`, 422, json);
+      }
+      const cleaned = json.content.replace(/\n/g, "");
+      const decoded = decodeBase64Utf8(cleaned);
+      return { content: decoded, sha: json.sha, path: json.path, size: json.size };
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * Create or update a file via the Contents API. The killer feature here
+   * vs. the git-data flow (createBlob → createTree → createCommit →
+   * updateRef) is that this works on **truly empty repos**: GitHub's git
+   * database isn't initialized until the first commit lands, so all the
+   * `/git/*` endpoints reject with 409 "Git Repository is empty" — but
+   * `PUT /contents/{path}` atomically initializes the database with a
+   * single-file commit on the supplied branch (defaulting to the repo's
+   * default branch).
+   *
+   * Used by the seed-initial-commit flow to bootstrap a freshly-created
+   * empty repo with a scaffold `workspace.json`.
+   *
+   * `contentBase64` must already be base64-encoded — caller chooses the
+   * encoder (TextEncoder for UTF-8 strings, raw bytes for binaries).
+   */
+  async putContents(token, owner, name, path2, args, opts = {}) {
+    const body = {
+      message: args.message,
+      content: args.contentBase64
+    };
+    if (args.branch) body.branch = args.branch;
+    if (args.sha) body.sha = args.sha;
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path2.split("/").map(encodeURIComponent).join("/")}`,
+      {
+        ...opts,
+        method: "PUT",
+        body,
+        requiredScopes: ["repo"]
+      }
+    );
+    return { commitSha: json.commit.sha, contentSha: json.content.sha };
+  }
+  /**
+   * Same as `getContents` but returns the raw bytes instead of UTF-8
+   * decoding the file. Used by the refresh flow to pull
+   * `.apicircle/workspace-<id>/attachments/<slotId>` blobs into local IDB without
+   * mangling binary data through TextDecoder.
+   */
+  async getBinaryContents(token, owner, name, path2, ref, opts = {}) {
+    const query = `?ref=${encodeURIComponent(ref)}`;
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path2.split("/").map(encodeURIComponent).join("/")}${query}`,
+        opts
+      );
+      if (Array.isArray(json) || json.type !== "file") {
+        throw new GitHubError(`Path ${path2} is not a file`, 422, json);
+      }
+      const cleaned = json.content.replace(/\n/g, "");
+      const bytes = decodeBase64Bytes(cleaned);
+      return { bytes, sha: json.sha, path: json.path, size: json.size };
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * Open a pull request from `head` (the working branch) into `base` (the
+   * repo's default branch). PR creation needs the `pull_request` scope on
+   * top of `repo`; missing-scope errors flow through MissingScopeError so
+   * the UI can prompt the user to update the token without losing branch
+   * state (Plan §3.7).
+   *
+   * GitHub returns 422 when:
+   *   - head/base are equal (nothing to merge)
+   *   - a PR already exists between this head and base
+   *   - the head branch doesn't exist
+   * All three surface as a plain GitHubError(422); the UI message is
+   * picked up from response.body.message.
+   */
+  /**
+   * Fetch a single pull request by number. Used by the refresh flow to
+   * detect whether a previously-opened PR has been merged on GitHub —
+   * `merged: true` is what triggers the working-branch retirement path.
+   *
+   * Returns `null` on 404 (PR was deleted or never existed at this number);
+   * other failures surface as the usual typed errors.
+   */
+  async getPullRequest(token, owner, name, number, opts = {}) {
+    try {
+      const { json } = await this.call(
+        token,
+        `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls/${number}`,
+        opts
+      );
+      return {
+        number: json.number,
+        htmlUrl: json.html_url,
+        state: json.state,
+        merged: json.merged === true
+      };
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /**
+   * List pull requests on a repo. The capability-probe path uses this with
+   * `perPage: 1` to determine whether the token can read PRs (and, by
+   * extension on classic PATs, whether it can also create them).
+   *
+   * Caller declares `requiredScopes` to surface a `MissingScopeError` on
+   * 403, so the capability probe can recognise the missing-scope case
+   * cleanly vs. transient 5xx/network failures.
+   */
+  async listPullRequests(token, owner, name, args = {}, opts = {}) {
+    const params = new URLSearchParams();
+    params.set("per_page", String(args.perPage ?? 30));
+    if (args.state) params.set("state", args.state);
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls?${params.toString()}`,
+      {
+        ...opts,
+        requiredScopes: ["repo", "pull_request"]
+      }
+    );
+    return json.map((pr) => ({
+      number: pr.number,
+      htmlUrl: pr.html_url,
+      state: pr.state,
+      title: pr.title
+    }));
+  }
+  async createPullRequest(token, owner, name, args, opts = {}) {
+    const { json } = await this.call(
+      token,
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`,
+      {
+        ...opts,
+        method: "POST",
+        body: {
+          title: args.title,
+          body: args.body,
+          head: args.head,
+          base: args.base,
+          draft: args.draft ?? false
+        },
+        requiredScopes: ["repo", "pull_request"]
+      }
+    );
+    return {
+      number: json.number,
+      htmlUrl: json.html_url,
+      state: json.state,
+      title: json.title
+    };
+  }
+  // --- low-level call ----------------------------------------------------
+  async call(token, path2, opts = {}) {
+    const url = path2.startsWith("http") ? path2 : `${this.baseUrl}${path2}`;
+    const controller = new AbortController();
+    const onExternalAbort = () => controller.abort(opts.signal.reason);
+    if (opts.signal) {
+      if (opts.signal.aborted) controller.abort(opts.signal.reason);
+      else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+    const timeoutHandle = setTimeout(
+      () => controller.abort(new Error(`GitHub request timed out after ${this.timeoutMs}ms`)),
+      this.timeoutMs
+    );
+    let response;
+    let timedOut = false;
+    try {
+      response = await this.fetchImpl(url, {
+        method: opts.method ?? "GET",
+        headers: {
+          Accept: "application/vnd.github+json",
+          "X-GitHub-Api-Version": "2022-11-28",
+          ...token ? { Authorization: `Bearer ${token}` } : {},
+          ...opts.body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        cache: "no-store",
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      const isAbort = err instanceof DOMException && err.name === "AbortError";
+      const callerAborted = opts.signal?.aborted ?? false;
+      if (isAbort && !callerAborted) {
+        timedOut = true;
+        throw new TimeoutError(
+          `GitHub request timed out after ${this.timeoutMs}ms. The write may have partially landed \u2014 refresh before retrying.`,
+          this.timeoutMs
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutHandle);
+      if (opts.signal) opts.signal.removeEventListener("abort", onExternalAbort);
+      void timedOut;
+    }
+    if (response.ok) {
+      if (response.status === 204 || response.status === 205) {
+        return { json: {}, response };
+      }
+      const json = await response.json();
+      return { json, response };
+    }
+    const errBody = await safeReadJson(response);
+    throw classifyError(response, errBody, opts.requiredScopes ?? []);
+  }
+};
+function normalizeMarketplaceRepo(raw) {
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    description: raw.description ?? "",
+    topics: raw.topics ?? [],
+    stargazers: raw.stargazers_count ?? 0,
+    defaultBranch: raw.default_branch ?? "main"
+  };
+}
+function decodeBase64Utf8(b64) {
+  return new TextDecoder("utf-8").decode(decodeBase64Bytes(b64));
+}
+function decodeBase64Bytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function normalizeRepo(raw) {
+  const visibility = raw.visibility ?? (raw.private === true ? "private" : "public");
+  const isPrivate = raw.private ?? visibility !== "public";
+  const pushable = raw.permissions?.push === true || raw.permissions?.admin === true;
+  return {
+    fullName: raw.full_name,
+    owner: raw.owner.login,
+    name: raw.name,
+    defaultBranch: raw.default_branch,
+    visibility,
+    isPrivate,
+    pushable
+  };
+}
+function parseScopes(headers) {
+  const raw = headers.get("x-oauth-scopes") ?? "";
+  const granted = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  const acceptedHeader = headers.get("x-accepted-oauth-scopes") ?? "";
+  const acceptedRequired = acceptedHeader.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return acceptedRequired.length > 0 ? { granted, acceptedRequired } : { granted };
+}
+function classifyError(response, body, callerRequiredScopes) {
+  const message = extractMessage(body) ?? response.statusText;
+  const status = response.status;
+  if (status === 401) {
+    return new UnauthorizedError(message || "Unauthorized \u2014 token rejected", status);
+  }
+  if (status === 403) {
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const reset = response.headers.get("x-ratelimit-reset");
+    if (remaining === "0" && reset) {
+      const resetAtMs = Number(reset) * 1e3;
+      const deltaMs = Math.max(0, resetAtMs - Date.now());
+      const totalSeconds = Math.ceil(deltaMs / 1e3);
+      const human = totalSeconds < 60 ? `${totalSeconds}s` : totalSeconds < 3600 ? `${Math.ceil(totalSeconds / 60)} min` : `${Math.ceil(totalSeconds / 3600)} h`;
+      return new RateLimitedError(
+        `GitHub rate limit reached. Resets in ${human} (at ${new Date(resetAtMs).toISOString()}).`,
+        status,
+        resetAtMs
+      );
+    }
+    const accepted = (response.headers.get("x-accepted-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const granted = (response.headers.get("x-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const missing = accepted.length > 0 ? accepted.filter((s) => !granted.includes(s)) : callerRequiredScopes.filter((s) => !granted.includes(s));
+    if (missing.length > 0) {
+      return new MissingScopeError(
+        `GitHub denied this action: missing scopes ${missing.join(", ")}.`,
+        status,
+        missing,
+        granted
+      );
+    }
+  }
+  return new GitHubError(message || "GitHub API call failed", status, body);
+}
+function extractMessage(body) {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string") return m;
+  }
+  return null;
+}
+async function safeReadJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+// src/tools/githubOps.ts
+function resolveToken(input) {
+  const t = (input ?? process.env.GITHUB_TOKEN ?? "").trim();
+  return t;
+}
+var TOKEN_HELP = "Pass `token`, or set the GITHUB_TOKEN env var on the MCP process.";
+var linkedLinkTool = {
+  name: "linked.link",
+  description: "Link a workspace by fetching its `.apicircle/` workspace from GitHub (registry.json \u2192 workspace-<id>/workspace.json). Caches the release ledger + a collections/environments snapshot. Needs a token for private repos. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    repoFullName: import_zod14.z.string().describe("owner/name of the source workspace repo."),
+    branch: import_zod14.z.string().default("main"),
+    pinnedVersion: import_zod14.z.string().nullable().optional().describe("null/omitted = source current version."),
+    kind: import_zod14.z.enum(["private", "public"]).default("private"),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, ctx) {
+    const token = resolveToken(input.token);
+    const repoFullName = input.repoFullName.trim();
+    if (!repoFullName.includes("/")) return { ok: false, error: "repoFullName must be owner/name" };
+    if (input.kind === "private" && !token)
+      return { ok: false, error: `A token is required for private repos. ${TOKEN_HELP}` };
+    const [owner, name] = repoFullName.split("/", 2);
+    const state = await ctx.workspace.read();
+    const dup = Object.values(state.synced.linkedWorkspaces).find(
+      (l) => l.source.repoFullName === repoFullName && l.source.branch === input.branch
+    );
+    if (dup)
+      return { ok: false, error: `Already linked to ${repoFullName}@${input.branch} (${dup.id})` };
+    const client = new GitHubClient();
+    let result;
+    try {
+      result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+        const f = await client.getContents(token, owner, name, p, input.branch);
+        return f?.content ?? null;
+      });
+    } catch (e) {
+      return {
+        ok: false,
+        error: e instanceof GitHubError ? e.message : e instanceof Error ? e.message : "fetch failed"
+      };
+    }
+    if ("error" in result)
+      return { ok: false, error: `${repoFullName}@${input.branch}: ${result.error}` };
+    const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+    const ledger = (0, import_core5.ledgerFromProbe)(probe);
+    const link = {
+      id: (0, import_shared6.generateId)(),
+      kind: input.kind,
+      name: repoFullName,
+      sourceWorkspaceId: result.workspaceId,
+      source: { provider: "github", repoFullName, branch: input.branch, sessionMode: "workspace" },
+      scope: ["collections", "environments"],
+      pinnedVersion: input.pinnedVersion ?? ledger.currentVersion,
+      updatePolicy: "manual",
+      linkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      requiredSecretKeyIds: probe.secretKeys ? Object.keys(probe.secretKeys) : []
+    };
+    const snapshot = (0, import_core5.buildLinkedSnapshot)(probe, link) ?? void 0;
+    const out = await ctx.workspace.apply({
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    return { ok: true, id: link.id, pinnedVersion: link.pinnedVersion, changedIds: out.changedIds };
+  }
+};
+var linkedRefreshTool = {
+  name: "linked.refresh",
+  description: "Re-pull a linked workspace's cached release ledger (+ bootstrap snapshot if missing) from GitHub. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({ id: import_zod14.z.string(), token: import_zod14.z.string().optional() }),
+  async handler(input, ctx) {
+    const state = await ctx.workspace.read();
+    const link = state.synced.linkedWorkspaces[input.id];
+    if (!link) return { ok: false, error: `Linked workspace ${input.id} not found` };
+    const token = resolveToken(input.token);
+    if (link.kind === "private" && !token)
+      return { ok: false, error: `A token is required for private links. ${TOKEN_HELP}` };
+    const [owner, name] = link.source.repoFullName.split("/", 2);
+    const client = new GitHubClient();
+    let result;
+    try {
+      result = await (0, import_core5.fetchRemoteWorkspaceJson)(async (p) => {
+        const f = await client.getContents(token, owner, name, p, link.source.branch);
+        return f?.content ?? null;
+      });
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "fetch failed" };
+    }
+    if ("error" in result)
+      return {
+        ok: false,
+        error: `${link.source.repoFullName}@${link.source.branch}: ${result.error}`
+      };
+    const probe = (0, import_core5.parseLinkedWorkspaceJson)(result.content);
+    const ledger = (0, import_core5.ledgerFromProbe)(probe);
+    const needsSnapshot = !state.local.linkedCollections[input.id];
+    const snapshot = needsSnapshot ? (0, import_core5.buildLinkedSnapshot)(probe, link) ?? void 0 : void 0;
+    await ctx.workspace.apply({
+      kind: "linkedWorkspace.upsert",
+      link,
+      ledger,
+      ...snapshot ? { snapshot } : {}
+    });
+    return {
+      ok: true,
+      currentVersion: ledger.currentVersion,
+      versionCount: ledger.versions.length
+    };
+  }
+};
+var releaseTagTool = {
+  name: "release.tag",
+  description: "Create a `v<version>` Git tag (optionally a GitHub Release) on the workspace's own repo. The version should already exist in the release ledger. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    owner: import_zod14.z.string(),
+    name: import_zod14.z.string(),
+    version: import_zod14.z.string(),
+    createGitHubRelease: import_zod14.z.boolean().default(false),
+    notes: import_zod14.z.string().optional(),
+    overrideExisting: import_zod14.z.boolean().default(false),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token);
+    if (!token) return { ok: false, error: `A token is required to tag. ${TOKEN_HELP}` };
+    const client = new GitHubClient();
+    const tagName = `v${input.version.replace(/^v/, "")}`;
+    try {
+      const repo = await client.getRepo(token, input.owner, input.name);
+      const ref = await client.getRef(token, input.owner, input.name, repo.defaultBranch);
+      const existing = await client.getTagSha(token, input.owner, input.name, tagName);
+      if (existing !== null) {
+        if (!input.overrideExisting) {
+          return {
+            ok: false,
+            error: `Tag ${tagName} already exists at ${existing.slice(0, 7)}. Pass overrideExisting:true to replace.`
+          };
+        }
+        await client.deleteRef(token, input.owner, input.name, `tags/${tagName}`);
+      }
+      await client.createTag(token, input.owner, input.name, { tagName, sha: ref.sha });
+      let releaseUrl;
+      if (input.createGitHubRelease) {
+        const release = await client.createRelease(token, input.owner, input.name, {
+          tagName,
+          releaseName: tagName,
+          body: input.notes ?? ""
+        });
+        releaseUrl = release.htmlUrl;
+      }
+      return {
+        ok: true,
+        tagName,
+        sha: ref.sha,
+        branch: repo.defaultBranch,
+        ...releaseUrl ? { releaseUrl } : {}
+      };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "tag failed" };
+    }
+  }
+};
+var marketplaceSearchTool = {
+  name: "marketplace.search",
+  description: "Search the API Circle marketplace for public workspaces tagged with `apicircle` on GitHub. Returns up to 30 results sorted by relevance (default), stars, or recent updates. Token is optional \u2014 anonymous browsing is supported (lower rate limits); pass a token to lift them. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    query: import_zod14.z.string().default("").describe("Search query \u2014 matches repo name, description, and topics. Empty = browse all."),
+    sort: import_zod14.z.enum(["best-match", "stars", "updated"]).default("best-match").describe(
+      "Sort order: best-match (default relevance), stars (most starred first), updated (recently pushed first)."
+    ),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token) || null;
+    const client = new GitHubClient();
+    try {
+      const repos = await client.searchMarketplaceRepos(token, input.query, {
+        sort: input.sort === "best-match" ? void 0 : input.sort
+      });
+      return { ok: true, count: repos.length, results: repos };
+    } catch (e) {
+      return {
+        ok: false,
+        error: e instanceof GitHubError ? e.message : e instanceof Error ? e.message : "search failed"
+      };
+    }
+  }
+};
+var TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+var repoSetTopicsTool = {
+  name: "repo.set_topics",
+  description: "Replace a repo's topics (the `apicircle` topic is always kept \u2014 it drives marketplace discovery). Topics must be lowercase, start with a letter/digit, \u226450 chars, \u226420 total. " + TOKEN_HELP,
+  inputSchema: import_zod14.z.object({
+    owner: import_zod14.z.string(),
+    name: import_zod14.z.string(),
+    topics: import_zod14.z.array(import_zod14.z.string()),
+    token: import_zod14.z.string().optional()
+  }),
+  async handler(input, _ctx) {
+    const token = resolveToken(input.token);
+    if (!token) return { ok: false, error: `A token is required to set topics. ${TOKEN_HELP}` };
+    const requested = input.topics;
+    const normalized = Array.from(
+      /* @__PURE__ */ new Set(["apicircle", ...requested.map((t) => t.trim().toLowerCase()).filter(Boolean)])
+    );
+    for (const t of normalized) {
+      if (!TOPIC_RE.test(t))
+        return {
+          ok: false,
+          error: `Invalid topic "${t}" \u2014 lowercase letters/digits/"-", starting with a letter or digit.`
+        };
+      if (t.length > 50) return { ok: false, error: `Topic "${t}" exceeds 50 characters.` };
+    }
+    if (normalized.length > 20) return { ok: false, error: "GitHub allows at most 20 topics." };
+    const client = new GitHubClient();
+    try {
+      const saved = await client.setRepoTopics(token, input.owner, input.name, normalized);
+      return { ok: true, topics: saved };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "set topics failed" };
+    }
+  }
+};
+
 // src/tools/registry.ts
 var TOOL_REGISTRY = [
   importCurlTool,
@@ -2839,6 +4326,7 @@ var TOOL_REGISTRY = [
   promptSetEndpointValidationRulesTool,
   promptSetEndpointResponseRulesTool,
   promptSetEndpointMultipliersTool,
+  promptSetEndpointRequestSchemaTool,
   globalAssetsFilesListTool,
   globalAssetsFilesCreateTool,
   globalAssetsFilesUpdateTool,
@@ -2858,7 +4346,22 @@ var TOOL_REGISTRY = [
   mockSetValidationRulesTool,
   mockSetResponseRulesTool,
   mockSetMultipliersTool,
-  mockImportPostmanMockCollectionTool
+  mockSetRequestSchemaTool,
+  mockSetDefaultPortTool,
+  mockImportPostmanMockCollectionTool,
+  releaseListTool,
+  releasePublishTool,
+  releaseDeprecateTool,
+  releaseYankTool,
+  linkedListTool,
+  linkedGetTool,
+  linkedSetConfigTool,
+  linkedUnlinkTool,
+  linkedLinkTool,
+  linkedRefreshTool,
+  releaseTagTool,
+  repoSetTopicsTool,
+  marketplaceSearchTool
 ];
 function getTool(name) {
   return TOOL_REGISTRY.find((t) => t.name === name);
@@ -2876,22 +4379,24 @@ var SingleWorkspaceAdapter = class {
   displayName;
   async list() {
     const state = await this.provider.read();
-    const id = state.synced.workspaceId;
+    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: 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
-        }
+        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
       }
     ];
   }
@@ -2922,7 +4427,7 @@ var WorkspaceNotFoundError = class extends Error {
 };
 
 // src/providers/InMemoryWorkspaceProvider.ts
-var import_core4 = require("@apicircle/core");
+var import_core6 = require("@apicircle/core");
 var InMemoryWorkspaceProvider = class {
   state;
   constructor(initial) {
@@ -2932,7 +4437,7 @@ var InMemoryWorkspaceProvider = class {
     return this.state;
   }
   async apply(patch) {
-    const out = (0, import_core4.applyMutation)(this.state, patch);
+    const out = (0, import_core6.applyMutation)(this.state, patch);
     this.state = out.next;
     return { state: this.state, changedIds: out.changedIds };
   }
@@ -2946,7 +4451,7 @@ var InMemoryWorkspaceProvider = class {
 };
 
 // src/providers/FileBackedWorkspaceProvider.ts
-var import_core5 = require("@apicircle/core");
+var import_core7 = require("@apicircle/core");
 var import_file_backed = require("@apicircle/core/workspace/file-backed");
 var FileBackedWorkspaceProvider = class {
   constructor(dir) {
@@ -2963,7 +4468,7 @@ var FileBackedWorkspaceProvider = class {
   async apply(patch) {
     let captured = null;
     await (0, import_file_backed.withWorkspace)(this.dir, async (state) => {
-      const result = (0, import_core5.applyMutation)(state, patch);
+      const result = (0, import_core7.applyMutation)(state, patch);
       captured = { state: result.next, changedIds: result.changedIds };
       return { next: result.next };
     });
@@ -2981,6 +4486,52 @@ var FileBackedWorkspaceProvider = class {
   }
 };
 
+// src/providers/GitBackedWorkspaceProvider.ts
+var import_core8 = require("@apicircle/core");
+var import_file_backed2 = require("@apicircle/core/workspace/file-backed");
+var GIT_SYNCED_FILENAME = "workspace.json";
+var GitBackedWorkspaceProvider = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  async read() {
+    const out = await (0, import_file_backed2.loadFromFile)(this.dir, {
+      syncedFilename: GIT_SYNCED_FILENAME,
+      allowMissing: true
+    });
+    if (!out) {
+      throw new Error(
+        `No workspace found at ${this.dir}. Expected .apicircle/registry.json and .apicircle/workspace-<id>/workspace.json in the repo.`
+      );
+    }
+    return out;
+  }
+  async apply(patch) {
+    let captured = null;
+    await (0, import_file_backed2.withWorkspace)(
+      this.dir,
+      async (state) => {
+        const result = (0, import_core8.applyMutation)(state, patch);
+        captured = { state: result.next, changedIds: result.changedIds };
+        return { next: result.next };
+      },
+      { syncedFilename: GIT_SYNCED_FILENAME }
+    );
+    if (!captured) throw new Error("apply did not run");
+    return captured;
+  }
+  async write(next) {
+    const current = await this.read();
+    const merged = {
+      synced: next.synced ?? current.synced,
+      local: next.local ?? current.local
+    };
+    await (0, import_file_backed2.saveToFile)(this.dir, merged, { syncedFilename: GIT_SYNCED_FILENAME });
+    return merged;
+  }
+};
+
 // src/providers/MultiWorkspaceProvider.ts
 var import_registry = require("@apicircle/core/workspace/registry");
 var LazyActiveWorkspaceProvider = class {
@@ -3067,13 +4618,14 @@ var MultiWorkspaceProvider = class {
       let counts = null;
       try {
         const state = await (0, import_registry.loadWorkspaceById)(this.registryRoot, entry.id);
-        if (state) {
+        if (state?.synced?.collections) {
+          const s = state.synced;
           counts = {
-            requests: Object.keys(state.synced.collections.requests).length,
-            folders: Object.keys(state.synced.collections.folders).length,
-            environments: Object.keys(state.synced.environments.items).length,
-            mockServers: Object.keys(state.synced.mockServers ?? {}).length,
-            plans: Object.keys(state.synced.executionPlans ?? {}).length
+            requests: Object.keys(s.collections.requests ?? {}).length,
+            folders: Object.keys(s.collections.folders ?? {}).length,
+            environments: Object.keys(s.environments?.items ?? {}).length,
+            mockServers: Object.keys(s.mockServers ?? {}).length,
+            plans: Object.keys(s.executionPlans ?? {}).length
           };
         }
       } catch {
@@ -3153,7 +4705,245 @@ var InProcessMockController = class {
   }
 };
 
+// src/config/snippets.ts
+var path = __toESM(require("path"), 1);
+var AI_CLIENTS = [
+  "claude-desktop",
+  "claude-code",
+  "codex",
+  "cursor",
+  "continue",
+  "cline",
+  "zed",
+  "windsurf",
+  "github-copilot",
+  "chatgpt",
+  "generic"
+];
+function buildSnippetVariants(client, binary, workspace) {
+  const forwardWorkspace = workspace.replace(/\\/g, "/");
+  const render = client === "codex" ? renderTomlSnippet : renderJsonSnippet;
+  const escaped = render(binary, workspace);
+  const forwardSlash = render(binary, forwardWorkspace);
+  return {
+    forwardSlash,
+    escaped,
+    identical: forwardSlash === escaped
+  };
+}
+function renderJsonSnippet(binary, workspace) {
+  const entry = {
+    command: binary,
+    args: ["--workspace", workspace],
+    env: { APICIRCLE_WORKSPACE: workspace }
+  };
+  return JSON.stringify({ mcpServers: { apicircle: entry } }, null, 2);
+}
+function renderTomlSnippet(binary, workspace) {
+  const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return [
+    `[mcp_servers.apicircle]`,
+    `command = "${esc(binary)}"`,
+    `args = ["--workspace", "${esc(workspace)}"]`,
+    ``,
+    `[mcp_servers.apicircle.env]`,
+    `APICIRCLE_WORKSPACE = "${esc(workspace)}"`
+  ].join("\n");
+}
+function resolveAiClientConfigPath(client, env) {
+  const { homedir, platform, appdata } = env;
+  switch (client) {
+    case "claude-desktop":
+      if (platform === "darwin") {
+        return path.join(homedir, "Library/Application Support/Claude/claude_desktop_config.json");
+      }
+      if (platform === "win32") {
+        return path.join(
+          appdata ?? path.join(homedir, "AppData/Roaming"),
+          "Claude/claude_desktop_config.json"
+        );
+      }
+      return path.join(homedir, ".config/Claude/claude_desktop_config.json");
+    case "claude-code":
+      return path.join(homedir, ".claude/mcp.json");
+    case "cursor":
+      return path.join(homedir, ".cursor/mcp.json");
+    case "continue":
+      return path.join(homedir, ".continue/config.yaml");
+    case "zed":
+      return path.join(homedir, ".config/zed/settings.json");
+    case "windsurf":
+      return path.join(homedir, ".codeium/windsurf/mcp_config.json");
+    case "codex":
+      return path.join(homedir, ".codex/config.toml");
+    default:
+      return null;
+  }
+}
+
+// src/prompts/mcpPrompts.ts
+var MCP_PROMPT_CATEGORIES = [
+  { id: "workspaces", label: "Workspaces" },
+  { id: "collections", label: "Collections" },
+  { id: "environments", label: "Environments" },
+  { id: "execution", label: "Execution" },
+  { id: "mocks", label: "Mocks" },
+  { id: "auth", label: "Auth" },
+  { id: "imports", label: "Imports" }
+];
+var MCP_PROMPTS = [
+  // ── Workspaces (multi-workspace discovery) ───────────────────────
+  {
+    id: "list-workspaces",
+    text: "List every API Circle workspace I have and tell me which is active.",
+    description: "Multi-workspace discovery \u2014 call this first when you are not sure which workspace to drive.",
+    category: "workspaces",
+    tools: ["workspace.list"]
+  },
+  {
+    id: "scope-to-workspace",
+    text: 'Read the requests in the "Petstore" workspace.',
+    description: "Drill into a specific workspace by name; the AI passes `workspaceId` to scope reads.",
+    category: "workspaces",
+    tools: ["workspace.list", "workspace.read"]
+  },
+  {
+    id: "multi-workspace-summary",
+    text: "Across every workspace, count requests, folders, environments, and mocks. Give me one row per workspace.",
+    description: "High-level summary across every registered workspace \u2014 pairs well with the multi-workspace envelope.",
+    category: "workspaces",
+    tools: ["workspace.list"]
+  },
+  // ── Collections (requests + folders in the active workspace) ─────
+  {
+    id: "list-requests",
+    text: "List every request in my API Circle workspace grouped by folder.",
+    description: "Quick overview of the request catalog so you know what is already wired up.",
+    category: "collections",
+    tools: ["workspace.read", "request.read", "folder.read"]
+  },
+  {
+    id: "create-request",
+    text: 'Add a new GET request named "Health check" pointing at https://example.com/healthz with an Accept: application/json header.',
+    description: "Have the AI author a request and persist it to the workspace.",
+    category: "collections",
+    tools: ["request.create"]
+  },
+  {
+    id: "update-request",
+    text: 'Find the "Create user" request and change its method to POST and body to {"name": "Ada"}.',
+    description: "Targeted edit by name \u2014 the AI looks it up, then updates.",
+    category: "collections",
+    tools: ["request.read", "request.update"]
+  },
+  {
+    id: "organize-folders",
+    text: 'Move every request whose URL contains /users into a folder named "User API".',
+    description: "Bulk reorganisation via natural language.",
+    category: "collections",
+    tools: ["workspace.read", "folder.create", "request.update"]
+  },
+  // ── Environments ──────────────────────────────────────────────────
+  {
+    id: "env-list",
+    text: "Show me all environments and which one is active.",
+    description: "Inventory of envs + which is layered onto requests right now.",
+    category: "environments",
+    tools: ["environment.read"]
+  },
+  {
+    id: "env-create",
+    text: 'Create a "staging" environment with BASE_URL=https://staging.example.com and API_KEY={{SECRET:staging-key}}.',
+    description: "Spin up a new env with both a plain variable and a secret reference.",
+    category: "environments",
+    tools: ["environment.create"]
+  },
+  {
+    id: "env-switch",
+    text: 'Switch the active environment to "production" and confirm by previewing the effective URL of the "Get user" request.',
+    description: "Activate an env then verify variable interpolation.",
+    category: "environments",
+    tools: ["environment.update", "request.read"]
+  },
+  // ── Execution ─────────────────────────────────────────────────────
+  {
+    id: "run-request",
+    text: 'Run the "Get user" request with userId=42 and show me the JSON response.',
+    description: "One-shot execution with overridden context vars.",
+    category: "execution",
+    tools: ["request.execute"]
+  },
+  {
+    id: "run-plan",
+    text: 'Execute the "Regression smoke" plan and summarise which assertions failed.',
+    description: "Drive a saved execution plan end-to-end.",
+    category: "execution",
+    tools: ["plan.read", "plan.execute"]
+  },
+  {
+    id: "inspect-history",
+    text: "Show me the last 5 requests I ran and their status codes.",
+    description: "Quick triage when something just broke.",
+    category: "execution",
+    tools: ["history.read"]
+  },
+  // ── Mocks ─────────────────────────────────────────────────────────
+  {
+    id: "mock-start",
+    text: 'Start the "Petstore" mock on port 4010 and tell me its base URL.',
+    description: "Spin up a local mock so requests can hit it.",
+    category: "mocks",
+    tools: ["mock.list", "mock.start"]
+  },
+  {
+    id: "mock-list",
+    text: "List every running mock with its port, served spec, and request count.",
+    description: "Status snapshot of every active mock runtime.",
+    category: "mocks",
+    tools: ["mock.list"]
+  },
+  {
+    id: "mock-stop",
+    text: "Stop every running mock.",
+    description: "Clean shutdown of all mock servers in one go.",
+    category: "mocks",
+    tools: ["mock.stopAll"]
+  },
+  // ── Auth ──────────────────────────────────────────────────────────
+  {
+    id: "auth-set-bearer",
+    text: 'Set the "Get user" request to use bearer auth with token={{ACCESS_TOKEN}}.',
+    description: "Wire bearer auth onto a single request via env-var reference.",
+    category: "auth",
+    tools: ["request.update"]
+  },
+  {
+    id: "auth-oauth2",
+    text: 'Configure the "Create order" request to use OAuth2 client-credentials against https://auth.example.com/token with the "orders.write" scope.',
+    description: "Full OAuth2 client-credentials wiring without leaving the chat.",
+    category: "auth",
+    tools: ["request.update"]
+  },
+  // ── Imports ───────────────────────────────────────────────────────
+  {
+    id: "import-openapi",
+    text: "Import the OpenAPI spec at ./openapi.yaml and create one request per operation.",
+    description: "Bulk import of a spec file from the workspace.",
+    category: "imports",
+    tools: ["import.openapi"]
+  },
+  {
+    id: "import-curl",
+    text: 'I am going to paste a cURL command \u2014 turn it into a saved request named "Webhook test".',
+    description: "cURL \u2192 saved request with a name you control.",
+    category: "imports",
+    tools: ["import.curl"]
+  }
+];
+
 // src/index.ts
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var import_stdio2 = require("@modelcontextprotocol/sdk/server/stdio.js");
 function createMcpServer(options) {
   const workspaces = options.workspaces ?? new SingleWorkspaceAdapter(
     options.workspace,
@@ -3172,15 +4962,23 @@ function createMcpServer(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AI_CLIENTS,
   FileBackedWorkspaceProvider,
+  GitBackedWorkspaceProvider,
   InMemoryWorkspaceProvider,
   InProcessMockController,
+  MCP_PROMPTS,
+  MCP_PROMPT_CATEGORIES,
   McpHost,
   MultiWorkspaceProvider,
   SingleWorkspaceAdapter,
+  StdioServerTransport,
+  StreamableHTTPServerTransport,
   TOOL_REGISTRY,
   WorkspaceNotFoundError,
+  buildSnippetVariants,
   createMcpServer,
-  getTool
+  getTool,
+  resolveAiClientConfigPath
 });
 //# sourceMappingURL=index.cjs.map