From 8e1f84062bb22ed666f88f38fb5ee0eb8d75b7c8 Mon Sep 17 00:00:00 2001
From: Rhys Sullivan <39114868+RhysSullivan@users.noreply.github.com>
Date: Thu, 16 Jul 2026 17:19:05 -0700
Subject: [PATCH 1/2] Support persisted OpenAPI spec overrides

---
 .changeset/persist-openapi-spec-overrides.md  |   5 +
 packages/plugins/openapi/src/api/group.ts     |  14 +-
 packages/plugins/openapi/src/api/handlers.ts  |   6 +
 packages/plugins/openapi/src/promise.ts       |   1 +
 .../src/react/AddOpenApiIntegration.tsx       |  36 +-
 .../openapi/src/react/SpecOverridesEditor.tsx |  50 +++
 .../openapi/src/react/UpdateSpecSection.tsx   |  25 +-
 packages/plugins/openapi/src/sdk/config.ts    |   9 +-
 packages/plugins/openapi/src/sdk/errors.ts    |  11 +
 packages/plugins/openapi/src/sdk/index.ts     |   8 +
 packages/plugins/openapi/src/sdk/parse.ts     |   5 +-
 packages/plugins/openapi/src/sdk/plugin.ts    | 120 +++++-
 .../src/sdk/spec-overrides-lifecycle.test.ts  | 164 ++++++++
 .../openapi/src/sdk/spec-overrides.test.ts    | 125 ++++++
 .../plugins/openapi/src/sdk/spec-overrides.ts | 361 ++++++++++++++++++
 15 files changed, 920 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/persist-openapi-spec-overrides.md
 create mode 100644 packages/plugins/openapi/src/react/SpecOverridesEditor.tsx
 create mode 100644 packages/plugins/openapi/src/sdk/spec-overrides-lifecycle.test.ts
 create mode 100644 packages/plugins/openapi/src/sdk/spec-overrides.test.ts
 create mode 100644 packages/plugins/openapi/src/sdk/spec-overrides.ts

diff --git a/.changeset/persist-openapi-spec-overrides.md b/.changeset/persist-openapi-spec-overrides.md
new file mode 100644
index 000000000..09dab81ea
--- /dev/null
+++ b/.changeset/persist-openapi-spec-overrides.md
@@ -0,0 +1,5 @@
+---
+"@executor-js/plugin-openapi": patch
+---
+
+Apply persisted RFC 6902 overrides to OpenAPI specifications during preview, import, and refresh so upstream documents can be corrected without maintaining a fork.
diff --git a/packages/plugins/openapi/src/api/group.ts b/packages/plugins/openapi/src/api/group.ts
index 91f19cc9d..d1ab56254 100644
--- a/packages/plugins/openapi/src/api/group.ts
+++ b/packages/plugins/openapi/src/api/group.ts
@@ -9,8 +9,14 @@ import {
   IntegrationSlug,
 } from "@executor-js/sdk/shared";
 
-import { OpenApiParseError, OpenApiExtractionError, OpenApiOAuthError } from "../sdk/errors";
+import {
+  OpenApiParseError,
+  OpenApiExtractionError,
+  OpenApiOAuthError,
+  OpenApiSpecOverrideError,
+} from "../sdk/errors";
 import { SpecPreviewSummary } from "../sdk/preview";
+import { SpecOverridesSchema } from "../sdk/spec-overrides";
 
 // ---------------------------------------------------------------------------
 // Errors — the plugin-domain tagged errors flow directly to clients
@@ -25,6 +31,7 @@ const DomainErrors = [
   OpenApiParseError,
   OpenApiExtractionError,
   OpenApiOAuthError,
+  OpenApiSpecOverrideError,
   IntegrationAlreadyExistsError,
 ] as const;
 
@@ -35,6 +42,7 @@ const UpdateSpecErrors = [
   OpenApiParseError,
   OpenApiExtractionError,
   OpenApiOAuthError,
+  OpenApiSpecOverrideError,
   IntegrationNotFound,
 ] as const;
 
@@ -79,11 +87,13 @@ const AddSpecPayload = Schema.Struct({
   family: Schema.optional(Schema.String),
   healthCheck: Schema.optional(HealthCheckSpec),
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationPayload)),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 const PreviewSpecPayload = Schema.Struct({
   spec: Schema.String,
   specFormat: Schema.optional(Schema.String),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 // The `configure` payload — the new/updated auth methods to merge onto the
@@ -109,6 +119,7 @@ const AddSpecResponse = Schema.Struct({
 // "re-fetch from the stored source URL".
 const UpdateSpecPayload = Schema.Struct({
   spec: Schema.optional(OpenApiSpecInputPayload),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 const UpdateSpecResponse = Schema.Struct({
@@ -138,6 +149,7 @@ const OpenApiConfigView = Schema.Struct({
   baseUrl: Schema.optional(Schema.String),
   headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  specOverrides: Schema.optional(SpecOverridesSchema),
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationResponse)),
 });
 
diff --git a/packages/plugins/openapi/src/api/handlers.ts b/packages/plugins/openapi/src/api/handlers.ts
index 422604d7e..b4e892d42 100644
--- a/packages/plugins/openapi/src/api/handlers.ts
+++ b/packages/plugins/openapi/src/api/handlers.ts
@@ -47,6 +47,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
           const preview = yield* ext.previewSpec({
             spec: payload.spec,
             specFormat: payload.specFormat,
+            specOverrides: payload.specOverrides,
           });
           return specPreviewSummary(preview);
         }),
@@ -68,6 +69,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
             family: payload.family,
             healthCheck: payload.healthCheck,
             authenticationTemplate: payload.authenticationTemplate,
+            specOverrides: payload.specOverrides,
           });
         }),
       ),
@@ -100,6 +102,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
                 baseUrl: config.baseUrl,
                 headers: config.headers ? { ...config.headers } : undefined,
                 queryParams: config.queryParams ? { ...config.queryParams } : undefined,
+                specOverrides: config.specOverrides ? [...config.specOverrides] : undefined,
                 authenticationTemplate: config.authenticationTemplate
                   ? [...config.authenticationTemplate]
                   : undefined,
@@ -127,6 +130,9 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
           const ext = yield* OpenApiExtensionService;
           const result = yield* ext.updateSpec(params.slug, {
             ...(payload.spec !== undefined ? { spec: payload.spec } : {}),
+            ...(payload.specOverrides !== undefined
+              ? { specOverrides: payload.specOverrides }
+              : {}),
           });
           return {
             slug: result.slug,
diff --git a/packages/plugins/openapi/src/promise.ts b/packages/plugins/openapi/src/promise.ts
index eec67f9e8..15fc9a72c 100644
--- a/packages/plugins/openapi/src/promise.ts
+++ b/packages/plugins/openapi/src/promise.ts
@@ -6,6 +6,7 @@ export type {
   OpenApiSpecInput,
   OpenApiPreviewInput,
 } from "./sdk/plugin";
+export type { JsonPatchOperation, SpecOverrides } from "./sdk/spec-overrides";
 
 // Auth-template authoring helpers. Author apikey methods as canonical
 // placements, or request-shaped: `headers: { Authorization: ["Bearer ",
diff --git a/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx b/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
index 730f4b8a7..7e3ce5e60 100644
--- a/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
+++ b/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
@@ -49,6 +49,8 @@ import type { SpecPreviewSummary } from "../sdk/preview";
 import { type Authentication } from "../sdk/types";
 import { resolveServerUrl } from "../sdk/openapi-utils";
 import { detectedAuthenticationTemplates } from "../sdk/derive-auth";
+import { parseSpecOverridesText } from "../sdk/spec-overrides";
+import { SpecOverridesEditor } from "./SpecOverridesEditor";
 
 const normalizePresetUrl = (url: string): string => {
   const trimmed = url.trim();
@@ -154,6 +156,7 @@ export default function AddOpenApiIntegration(props: {
   const openApiPresets = openApiPlugin?.presets;
   const initialPreset = openApiPresets?.find((preset) => preset.id === props.initialPreset) ?? null;
   const [specUrl, setSpecUrl] = useState(props.initialUrl ?? "");
+  const [specOverridesText, setSpecOverridesText] = useState("");
   const [analyzing, setAnalyzing] = useState(false);
   const [analyzeError, setAnalyzeError] = useState<string | null>(null);
 
@@ -233,6 +236,10 @@ export default function AddOpenApiIntegration(props: {
       : resolvedIntegrationId);
   const resolvedDescription =
     descriptionDraft ?? (preview ? Option.getOrElse(preview.description, () => "") : "");
+  const parsedSpecOverrides = useMemo(
+    () => parseSpecOverridesText(specOverridesText),
+    [specOverridesText],
+  );
 
   // Register EVERY spec-detected auth method, not just a single selected one.
   // Keyed off `preview` (stable per analysis) so the memo doesn't re-run on the
@@ -333,6 +340,7 @@ export default function AddOpenApiIntegration(props: {
   // args filled (an empty draft, `hcOperation === ""`, imposes no constraint).
   const canAdd =
     preview !== null &&
+    parsedSpecOverrides.ok &&
     !slugAlreadyExists &&
     (!previewHasNoServers || resolvedBaseUrl.length > 0) &&
     !(hcOperation.length > 0 && hcMissingRequired);
@@ -343,8 +351,19 @@ export default function AddOpenApiIntegration(props: {
     setAnalyzing(true);
     setAnalyzeError(null);
     setAddError(null);
+    if (!parsedSpecOverrides.ok) {
+      setAnalyzeError(parsedSpecOverrides.message);
+      setAnalyzing(false);
+      return;
+    }
     const exit = await doPreview({
-      payload: { spec: specUrl, specFormat: initialPreset?.specFormat },
+      payload: {
+        spec: specUrl,
+        specFormat: initialPreset?.specFormat,
+        ...(parsedSpecOverrides.value.length > 0
+          ? { specOverrides: parsedSpecOverrides.value }
+          : {}),
+      },
     });
     if (Exit.isFailure(exit)) {
       setAnalyzeError(errorMessageFromExit(exit, "Failed to parse spec"));
@@ -375,6 +394,9 @@ export default function AddOpenApiIntegration(props: {
         specFormat: initialPreset?.specFormat,
         family: initialPreset?.family,
         healthCheck: initialPreset?.healthCheck,
+        ...(parsedSpecOverrides.ok && parsedSpecOverrides.value.length > 0
+          ? { specOverrides: parsedSpecOverrides.value }
+          : {}),
         // Always send the edited method list (even empty) when the user has
         // inspected a preview: an explicit [] means "no auth methods", while
         // OMITTING the field tells the server to derive defaults from the
@@ -399,6 +421,7 @@ export default function AddOpenApiIntegration(props: {
     resolvedDescription,
     resolvedBaseUrl,
     editedAuthenticationTemplate,
+    parsedSpecOverrides,
     initialPreset?.family,
     initialPreset?.healthCheck,
     initialPreset?.specFormat,
@@ -539,6 +562,17 @@ export default function AddOpenApiIntegration(props: {
         />
       ) : null}
 
+      <SpecOverridesEditor
+        value={specOverridesText}
+        onChange={(value) => {
+          setSpecOverridesText(value);
+          setAnalyzeError(null);
+          setPreview(null);
+          setBaseUrl("");
+        }}
+        disabled={analyzing || adding}
+      />
+
       {preview && (
         <AuthMethodListEditor
           list={authMethodList}
diff --git a/packages/plugins/openapi/src/react/SpecOverridesEditor.tsx b/packages/plugins/openapi/src/react/SpecOverridesEditor.tsx
new file mode 100644
index 000000000..591d2f1b5
--- /dev/null
+++ b/packages/plugins/openapi/src/react/SpecOverridesEditor.tsx
@@ -0,0 +1,50 @@
+import { useState } from "react";
+import { ChevronDown } from "lucide-react";
+
+import { cn } from "@executor-js/react/lib/utils";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@executor-js/react/components/collapsible";
+import { FieldLabel } from "@executor-js/react/components/field";
+import { Textarea } from "@executor-js/react/components/textarea";
+
+import { parseSpecOverridesText } from "../sdk/spec-overrides";
+
+export function SpecOverridesEditor(props: {
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly disabled?: boolean;
+}) {
+  const [open, setOpen] = useState(props.value.trim().length > 0);
+  const parsed = parseSpecOverridesText(props.value);
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen}>
+      <CollapsibleTrigger className="flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground">
+        Spec overrides
+        <ChevronDown
+          className={cn("size-3.5 transition-transform", open && "rotate-180")}
+          aria-hidden="true"
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="mt-3 space-y-2">
+          <FieldLabel>JSON Patch (RFC 6902)</FieldLabel>
+          <Textarea
+            value={props.value}
+            onChange={(event) => props.onChange((event.target as HTMLTextAreaElement).value)}
+            placeholder={'[{"op":"replace","path":"/info/title","value":"My API"}]'}
+            rows={5}
+            maxRows={14}
+            className="font-mono text-xs"
+            disabled={props.disabled}
+            aria-invalid={!parsed.ok}
+          />
+          {!parsed.ok && <p className="text-xs text-destructive">{parsed.message}</p>}
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
diff --git a/packages/plugins/openapi/src/react/UpdateSpecSection.tsx b/packages/plugins/openapi/src/react/UpdateSpecSection.tsx
index 5a8a277fd..b63351e8c 100644
--- a/packages/plugins/openapi/src/react/UpdateSpecSection.tsx
+++ b/packages/plugins/openapi/src/react/UpdateSpecSection.tsx
@@ -13,6 +13,8 @@ import { Label } from "@executor-js/react/components/label";
 import { Textarea } from "@executor-js/react/components/textarea";
 
 import { openApiConfigAtom, updateOpenApiSpec } from "./atoms";
+import { SpecOverridesEditor } from "./SpecOverridesEditor";
+import { formatSpecOverridesText, parseSpecOverridesText } from "../sdk/spec-overrides";
 
 // ---------------------------------------------------------------------------
 // Update spec — the openapi plugin's section of the integration Edit sheet.
@@ -47,22 +49,34 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
   const doUpdate = useAtomSet(updateOpenApiSpec, { mode: "promiseExit" });
   const [refetchStaged, setRefetchStaged] = useState(false);
   const [pasted, setPasted] = useState("");
+  const [specOverridesDraft, setSpecOverridesDraft] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   const config =
     AsyncResult.isSuccess(configResult) && configResult.value ? configResult.value : null;
 
   const specUrl = config?.specUrl;
+  const specOverridesText = specOverridesDraft ?? formatSpecOverridesText(config?.specOverrides);
 
   // The staged apply, rebuilt whenever the staged inputs change. Reported to
   // the sheet through a ref-stable callback so Save can run it.
   const applyStaged = useCallback(async (): Promise<EditSheetApplyResult> => {
     const spec = pasted.trim().length > 0 ? { kind: "blob" as const, value: pasted } : undefined;
-    if (!spec && !refetchStaged) return { ok: true, summary: null };
+    const parsedOverrides = parseSpecOverridesText(specOverridesText);
+    if (!parsedOverrides.ok) {
+      setError(parsedOverrides.message);
+      return { ok: false };
+    }
+    if (!spec && !refetchStaged && specOverridesDraft === null) {
+      return { ok: true, summary: null };
+    }
     setError(null);
     const exit = await doUpdate({
       params: { slug },
-      payload: spec ? { spec } : {},
+      payload: {
+        ...(spec ? { spec } : {}),
+        ...(specOverridesDraft !== null ? { specOverrides: parsedOverrides.value } : {}),
+      },
       reactivityKeys: integrationWriteKeys,
     });
     if (Exit.isFailure(exit)) {
@@ -71,12 +85,13 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
     }
     setRefetchStaged(false);
     setPasted("");
+    setSpecOverridesDraft(null);
     return { ok: true, summary: outcomeSummary(exit.value) };
-  }, [doUpdate, pasted, refetchStaged, slug]);
+  }, [doUpdate, pasted, refetchStaged, slug, specOverridesDraft, specOverridesText]);
 
   const onPendingChangeRef = useRef(props.onPendingChange);
   onPendingChangeRef.current = props.onPendingChange;
-  const hasStagedChange = refetchStaged || pasted.trim().length > 0;
+  const hasStagedChange = refetchStaged || pasted.trim().length > 0 || specOverridesDraft !== null;
   useEffect(() => {
     onPendingChangeRef.current?.(hasStagedChange ? applyStaged : null);
     // Clear the staged apply if this section unmounts mid-edit.
@@ -129,6 +144,8 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
         </div>
       )}
 
+      <SpecOverridesEditor value={specOverridesText} onChange={setSpecOverridesDraft} />
+
       {error && <FormErrorAlert message={error} />}
     </div>
   );
diff --git a/packages/plugins/openapi/src/sdk/config.ts b/packages/plugins/openapi/src/sdk/config.ts
index f07608a7c..78c639f4a 100644
--- a/packages/plugins/openapi/src/sdk/config.ts
+++ b/packages/plugins/openapi/src/sdk/config.ts
@@ -7,6 +7,7 @@ import {
 } from "@executor-js/sdk/http-auth";
 
 import type { Authentication } from "./types";
+import { SpecOverridesSchema, type SpecOverrides } from "./spec-overrides";
 
 // ---------------------------------------------------------------------------
 // OpenAPI integration config — the opaque blob stored on the catalog
@@ -17,6 +18,7 @@ import type { Authentication } from "./types";
 // StoredSource credential config. The config carries only:
 //   - the content hash of the spec blob and/or the source URL to (re)fetch
 //     from,
+//   - optional RFC 6902 overrides and the raw source hash they apply to,
 //   - the optional base URL override,
 //   - the auth templates a connection's value is rendered through.
 // The resolved spec text itself lives in the plugin blob store, keyed
@@ -43,6 +45,8 @@ export const OpenApiIntegrationConfigSchema = Schema.Struct({
   /** Hex SHA-256 of the resolved spec text — the content address of the spec
    *  blob (`spec/<hash>` in the plugin blob store). */
   specHash: Schema.optional(Schema.String),
+  /** Hex SHA-256 of the unmodified source text when spec overrides are active. */
+  sourceSpecHash: Schema.optional(Schema.String),
   /** Origin URL the spec was fetched from, when known. Enables refresh. */
   specUrl: Schema.optional(Schema.String),
   /** Optional base URL override. */
@@ -55,17 +59,20 @@ export const OpenApiIntegrationConfigSchema = Schema.Struct({
   specFormat: Schema.optional(Schema.String),
   /** Catalog family for grouped integration display. */
   family: Schema.optional(Schema.String),
+  /** Ordered RFC 6902 operations reapplied whenever the source spec is refreshed. */
+  specOverrides: Schema.optional(SpecOverridesSchema),
   /** The auth methods a connection's value can be applied through. */
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationSchema)),
 });
 
 export type OpenApiIntegrationConfig = Omit<
   typeof OpenApiIntegrationConfigSchema.Type,
-  "authenticationTemplate"
+  "authenticationTemplate" | "specOverrides"
 > & {
   /** Branded over the schema's structural form so the template renderer can
    *  treat `slug` as an `AuthTemplateSlug`. */
   readonly authenticationTemplate?: readonly Authentication[];
+  readonly specOverrides?: SpecOverrides;
 };
 
 const decodeConfig = Schema.decodeUnknownOption(OpenApiIntegrationConfigSchema);
diff --git a/packages/plugins/openapi/src/sdk/errors.ts b/packages/plugins/openapi/src/sdk/errors.ts
index 076cb2921..64d440e72 100644
--- a/packages/plugins/openapi/src/sdk/errors.ts
+++ b/packages/plugins/openapi/src/sdk/errors.ts
@@ -25,6 +25,17 @@ export class OpenApiExtractionError extends Schema.TaggedErrorClass<OpenApiExtra
   { httpApiStatus: 400 },
 ) {}
 
+export class OpenApiSpecOverrideError extends Schema.TaggedErrorClass<OpenApiSpecOverrideError>()(
+  "OpenApiSpecOverrideError",
+  {
+    operationIndex: Schema.Number,
+    operation: Schema.String,
+    path: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 400 },
+) {}
+
 export class OpenApiInvocationError extends Data.TaggedError("OpenApiInvocationError")<{
   readonly message: string;
   readonly statusCode: Option.Option<number>;
diff --git a/packages/plugins/openapi/src/sdk/index.ts b/packages/plugins/openapi/src/sdk/index.ts
index a4864fe6e..d9c1a4c7d 100644
--- a/packages/plugins/openapi/src/sdk/index.ts
+++ b/packages/plugins/openapi/src/sdk/index.ts
@@ -1,4 +1,11 @@
 export { parse, resolveSpecText, fetchSpecText } from "./parse";
+export {
+  applySpecOverrides,
+  JsonPatchOperationSchema,
+  SpecOverridesSchema,
+  type JsonPatchOperation,
+  type SpecOverrides,
+} from "./spec-overrides";
 export { extract, streamOperationBindingsFromStructure } from "./extract";
 export {
   structuralSplit,
@@ -92,6 +99,7 @@ export {
   OpenApiExtractionError,
   OpenApiInvocationError,
   OpenApiOAuthError,
+  OpenApiSpecOverrideError,
   OpenApiAuthRequiredError,
 } from "./errors";
 
diff --git a/packages/plugins/openapi/src/sdk/parse.ts b/packages/plugins/openapi/src/sdk/parse.ts
index 556e38dff..77b788dae 100644
--- a/packages/plugins/openapi/src/sdk/parse.ts
+++ b/packages/plugins/openapi/src/sdk/parse.ts
@@ -79,7 +79,7 @@ export const resolveSpecText = (input: string, credentials?: SpecFetchCredential
  * the 128MB Cloudflare Workers memory cap.
  */
 export const parse = Effect.fn("OpenApi.parse")(function* (text: string) {
-  const api = yield* parseTextToObject(text);
+  const api = yield* parseSpecObject(text);
 
   if (!isOpenApi3(api)) {
     return yield* new OpenApiExtractionErrorFromParse({
@@ -98,7 +98,8 @@ export const parse = Effect.fn("OpenApi.parse")(function* (text: string) {
 const isOpenApi3 = (doc: OpenAPI.Document): doc is OpenAPIV3.Document | OpenAPIV3_1.Document =>
   "openapi" in doc && typeof doc.openapi === "string" && doc.openapi.startsWith("3.");
 
-const parseTextToObject = (text: string): Effect.Effect<OpenAPI.Document, OpenApiParseError> =>
+/** Parse JSON or YAML text into an object without applying OpenAPI version validation. */
+export const parseSpecObject = (text: string): Effect.Effect<OpenAPI.Document, OpenApiParseError> =>
   Effect.gen(function* () {
     const trimmed = text.trim();
     if (trimmed.length === 0) {
diff --git a/packages/plugins/openapi/src/sdk/plugin.ts b/packages/plugins/openapi/src/sdk/plugin.ts
index da4cd2f4f..46b17b12b 100644
--- a/packages/plugins/openapi/src/sdk/plugin.ts
+++ b/packages/plugins/openapi/src/sdk/plugin.ts
@@ -22,8 +22,13 @@ import {
 } from "@executor-js/sdk/core";
 
 import { decodeOpenApiIntegrationConfig, type OpenApiIntegrationConfig } from "./config";
-import { OpenApiExtractionError, OpenApiOAuthError, OpenApiParseError } from "./errors";
-import { parse, resolveSpecText } from "./parse";
+import {
+  OpenApiExtractionError,
+  OpenApiOAuthError,
+  OpenApiParseError,
+  OpenApiSpecOverrideError,
+} from "./errors";
+import { parse, parseSpecObject, resolveSpecText } from "./parse";
 import { extract } from "./extract";
 import {
   OAuth2AuthorizationCodeFlow,
@@ -57,6 +62,9 @@ import {
 } from "./backing";
 import type { InvokeOptions } from "./invoke";
 import { resolveServerUrl } from "./openapi-utils";
+import { applySpecOverrides, SpecOverridesSchema, type SpecOverrides } from "./spec-overrides";
+
+const encodeJsonText = Schema.encodeUnknownSync(Schema.UnknownFromJsonString);
 
 // ---------------------------------------------------------------------------
 // Extension input shapes
@@ -67,6 +75,7 @@ export type OpenApiSpecInput = typeof OpenApiSpecInputSchema.Type;
 export interface OpenApiPreviewInput {
   readonly spec: string;
   readonly specFormat?: string;
+  readonly specOverrides?: SpecOverrides;
 }
 
 /** Add an OpenAPI integration to the catalog. The integration is the API
@@ -87,6 +96,8 @@ export interface OpenApiSpecConfig {
   /** Static query params applied to every request. */
   readonly queryParams?: Record<string, string>;
   readonly specFormat?: string;
+  /** Ordered RFC 6902 operations applied after fetching/conversion and before parsing. */
+  readonly specOverrides?: SpecOverrides;
   readonly family?: string;
   readonly healthCheck?: HealthCheckSpec;
   /** Auth methods a connection's value renders through - canonical
@@ -124,6 +135,8 @@ export interface OpenApiUpdateSpecInput {
   /** New spec source. Omit to re-fetch from the integration's stored
    *  `specUrl`. */
   readonly spec?: OpenApiSpecInput;
+  /** Replacement override list. Omit to keep existing overrides; pass [] to clear them. */
+  readonly specOverrides?: SpecOverrides;
 }
 
 export interface OpenApiPluginExtension {
@@ -131,7 +144,11 @@ export interface OpenApiPluginExtension {
     input: string | OpenApiPreviewInput,
   ) => Effect.Effect<
     SpecPreview,
-    OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | StorageFailure
+    | OpenApiParseError
+    | OpenApiExtractionError
+    | OpenApiOAuthError
+    | OpenApiSpecOverrideError
+    | StorageFailure
   >;
   readonly addSpec: (
     config: OpenApiSpecConfig,
@@ -140,6 +157,7 @@ export interface OpenApiPluginExtension {
     | OpenApiParseError
     | OpenApiExtractionError
     | OpenApiOAuthError
+    | OpenApiSpecOverrideError
     | IntegrationAlreadyExistsError
     | StorageFailure
   >;
@@ -154,6 +172,7 @@ export interface OpenApiPluginExtension {
     | OpenApiParseError
     | OpenApiExtractionError
     | OpenApiOAuthError
+    | OpenApiSpecOverrideError
     | IntegrationNotFoundError
     | StorageFailure
   >;
@@ -179,6 +198,7 @@ export interface OpenApiPluginExtension {
 const PreviewSpecInputSchema = Schema.Struct({
   spec: Schema.String,
   specFormat: Schema.optional(Schema.String),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 const StaticPreviewServerVariableSchema = Schema.Struct({
@@ -282,6 +302,7 @@ const AddIntegrationInputSchema = Schema.Struct({
   headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   specFormat: Schema.optional(Schema.String),
+  specOverrides: Schema.optional(SpecOverridesSchema),
   family: Schema.optional(Schema.String),
   healthCheck: Schema.optional(HealthCheckSpec),
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationSchema)),
@@ -596,10 +617,36 @@ export const openApiPlugin = definePlugin<
   OpenapiStore,
   OpenApiPluginOptions
 >((options?: OpenApiPluginOptions) => {
+  interface ResolvedSpec extends ConvertedSpec {
+    readonly sourceSpecText: string;
+  }
+
+  const applyOverridesToResolvedSpec = Effect.fn("OpenApi.applyOverridesToResolvedSpec")(function* (
+    resolved: ConvertedSpec,
+    overrides: SpecOverrides | undefined,
+  ) {
+    if (!overrides || overrides.length === 0) {
+      return { ...resolved, sourceSpecText: resolved.specText } satisfies ResolvedSpec;
+    }
+    const document = yield* parseSpecObject(resolved.specText);
+    const patched = yield* applySpecOverrides(document, overrides);
+    return {
+      ...resolved,
+      sourceSpecText: resolved.specText,
+      specText: encodeJsonText(patched),
+    } satisfies ResolvedSpec;
+  });
+
   const resolveSpecForInput = (
-    config: Pick<OpenApiSpecConfig, "spec" | "specFormat" | "headers" | "queryParams" | "baseUrl">,
+    config: Pick<
+      OpenApiSpecConfig,
+      "spec" | "specFormat" | "specOverrides" | "headers" | "queryParams" | "baseUrl"
+    >,
     httpClientLayer: Layer.Layer<HttpClient.HttpClient, never, never>,
-  ): Effect.Effect<ConvertedSpec, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError> =>
+  ): Effect.Effect<
+    ResolvedSpec,
+    OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | OpenApiSpecOverrideError
+  > =>
     Effect.gen(function* () {
       const adapter = yield* resolveSpecFormatAdapter(
         options?.specFormats ?? [],
@@ -611,7 +658,7 @@ export const openApiPlugin = definePlugin<
             message: "Spec format adapters require a URL spec input",
           });
         }
-        return yield* adapter.fetch({
+        const resolved = yield* adapter.fetch({
           urls: [config.spec.url],
           credentials: {
             ...(config.headers ? { headers: config.headers } : {}),
@@ -619,14 +666,21 @@ export const openApiPlugin = definePlugin<
           },
           httpClientLayer,
         });
+        return yield* applyOverridesToResolvedSpec(resolved, config.specOverrides);
       }
       if (config.spec.kind === "url") {
         const specText = yield* resolveSpecText(config.spec.url).pipe(
           Effect.provide(httpClientLayer),
         );
-        return { specText, specUrl: config.spec.url };
+        return yield* applyOverridesToResolvedSpec(
+          { specText, specUrl: config.spec.url },
+          config.specOverrides,
+        );
       }
-      return { specText: config.spec.value };
+      return yield* applyOverridesToResolvedSpec(
+        { specText: config.spec.value },
+        config.specOverrides,
+      );
     });
 
   return {
@@ -768,6 +822,10 @@ export const openApiPlugin = definePlugin<
           }
 
           const specHash = yield* sha256Hex(resolved.specText);
+          const sourceSpecHash =
+            config.specOverrides && config.specOverrides.length > 0
+              ? yield* sha256Hex(resolved.sourceSpecText)
+              : undefined;
 
           const integrationConfig: OpenApiIntegrationConfig = {
             ...(resolved.config ?? {}),
@@ -783,6 +841,9 @@ export const openApiPlugin = definePlugin<
             ...(config.queryParams ? { queryParams: config.queryParams } : {}),
             ...(config.specFormat ? { specFormat: config.specFormat } : {}),
             ...(config.family ? { family: config.family } : {}),
+            ...(config.specOverrides && config.specOverrides.length > 0
+              ? { specOverrides: config.specOverrides, sourceSpecHash }
+              : {}),
             // Prefer the caller's explicit template; otherwise derive from the
             // spec's declared security schemes.
             ...(config.authenticationTemplate
@@ -801,6 +862,9 @@ export const openApiPlugin = definePlugin<
           // leaves only an unreferenced blob behind - while blob backends like
           // R2 couldn't roll back with the transaction anyway.
           yield* ctx.storage.putSpec(specHash, resolved.specText);
+          if (sourceSpecHash) {
+            yield* ctx.storage.putSpec(sourceSpecHash, resolved.sourceSpecText);
+          }
           // The content-addressed defs blob lets the serve path resolve the
           // shared `definitions` without re-parsing the spec. Same idempotent,
           // outside-the-transaction rationale as the spec blob.
@@ -870,8 +934,21 @@ export const openApiPlugin = definePlugin<
           // The new spec source: explicit input wins; otherwise re-fetch from
           // where the spec originally came from. A pasted-blob integration has
           // no origin, so updating it requires a new input.
+          const nextOverrides = input?.specOverrides ?? current.specOverrides ?? [];
+          const storedSourceHash = current.sourceSpecHash ?? current.specHash;
+          const storedSourceText =
+            input?.spec === undefined && !current.specUrl && input?.specOverrides !== undefined
+              ? storedSourceHash
+                ? yield* ctx.storage.getSpec(storedSourceHash)
+                : null
+              : null;
           const specInput: OpenApiSpecInput | null =
-            input?.spec ?? (current.specUrl ? { kind: "url", url: current.specUrl } : null);
+            input?.spec ??
+            (current.specUrl
+              ? { kind: "url", url: current.specUrl }
+              : storedSourceText
+                ? { kind: "blob", value: storedSourceText }
+                : null);
           if (specInput === null) {
             return yield* new OpenApiParseError({
               message:
@@ -885,6 +962,7 @@ export const openApiPlugin = definePlugin<
             {
               spec: specInput,
               specFormat: current.specFormat,
+              specOverrides: nextOverrides,
               headers: current.headers,
               queryParams: current.queryParams,
               baseUrl: current.baseUrl,
@@ -903,17 +981,28 @@ export const openApiPlugin = definePlugin<
           // the blob outside the transaction - re-puts are idempotent and an
           // aborted config update just leaves an unreferenced blob.
           const specHash = yield* sha256Hex(resolved.specText);
+          const sourceSpecHash =
+            nextOverrides.length > 0 ? yield* sha256Hex(resolved.sourceSpecText) : undefined;
           yield* ctx.storage.putSpec(specHash, resolved.specText);
+          if (sourceSpecHash) {
+            yield* ctx.storage.putSpec(sourceSpecHash, resolved.sourceSpecText);
+          }
           if (compiled) {
             yield* ctx.storage.putDefs(specHash, JSON.stringify(compiled.hoistedDefs));
           }
 
+          const {
+            sourceSpecHash: _currentSourceSpecHash,
+            specOverrides: _currentSpecOverrides,
+            ...currentWithoutOverrides
+          } = current;
           const nextConfig: OpenApiIntegrationConfig = {
-            ...current,
+            ...currentWithoutOverrides,
             specHash,
             ...((resolved.specUrl ?? specInputToSpecUrl(specInput)) !== undefined
               ? { specUrl: resolved.specUrl ?? specInputToSpecUrl(specInput) }
               : {}),
+            ...(nextOverrides.length > 0 ? { specOverrides: nextOverrides, sourceSpecHash } : {}),
           };
 
           yield* ctx.transaction(
@@ -985,7 +1074,11 @@ export const openApiPlugin = definePlugin<
               ? { kind: "url" as const, url: previewInput.spec.trim() }
               : { kind: "blob" as const, value: previewInput.spec };
             const resolved = yield* resolveSpecForInput(
-              { spec, specFormat: previewInput.specFormat },
+              {
+                spec,
+                specFormat: previewInput.specFormat,
+                specOverrides: previewInput.specOverrides,
+              },
               httpClientLayer,
             );
             const preview = yield* previewSpecText(resolved.specText);
@@ -1093,6 +1186,8 @@ export const openApiPlugin = definePlugin<
                     Effect.succeed(openApiToolFailure("openapi_extraction_failed", message)),
                   OpenApiOAuthError: ({ message }: OpenApiOAuthError) =>
                     Effect.succeed(openApiToolFailure("openapi_oauth_failed", message)),
+                  OpenApiSpecOverrideError: ({ message }) =>
+                    Effect.succeed(openApiToolFailure("openapi_spec_override_failed", message)),
                 }),
               ),
           }),
@@ -1117,6 +1212,7 @@ export const openApiPlugin = definePlugin<
                   headers: input.headers,
                   queryParams: input.queryParams,
                   specFormat: input.specFormat,
+                  specOverrides: input.specOverrides,
                   family: input.family,
                   healthCheck: input.healthCheck,
                   authenticationTemplate: input.authenticationTemplate as
@@ -1137,6 +1233,8 @@ export const openApiPlugin = definePlugin<
                       Effect.succeed(openApiToolFailure("openapi_extraction_failed", message)),
                     OpenApiOAuthError: ({ message }: OpenApiOAuthError) =>
                       Effect.succeed(openApiToolFailure("openapi_oauth_failed", message)),
+                    OpenApiSpecOverrideError: ({ message }) =>
+                      Effect.succeed(openApiToolFailure("openapi_spec_override_failed", message)),
                     IntegrationAlreadyExistsError: ({ slug }: IntegrationAlreadyExistsError) =>
                       Effect.succeed(
                         openApiToolFailure(
diff --git a/packages/plugins/openapi/src/sdk/spec-overrides-lifecycle.test.ts b/packages/plugins/openapi/src/sdk/spec-overrides-lifecycle.test.ts
new file mode 100644
index 000000000..7a0d28575
--- /dev/null
+++ b/packages/plugins/openapi/src/sdk/spec-overrides-lifecycle.test.ts
@@ -0,0 +1,164 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Option, Schema } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+
+import { createExecutor, sha256Hex } from "@executor-js/sdk";
+import { makeTestConfig, memoryCredentialsPlugin } from "@executor-js/sdk/testing";
+
+import { openApiPlugin } from "./plugin";
+import { applySpecOverrides, type SpecOverrides } from "./spec-overrides";
+import { serveMutableOpenApiSpecTestServer } from "../testing";
+
+const testPlugins = () =>
+  [openApiPlugin({ httpClientLayer: FetchHttpClient.layer }), memoryCredentialsPlugin()] as const;
+
+const oauthSpec = {
+  openapi: "3.1.0",
+  info: { title: "Scoped API", version: "1.0.0" },
+  paths: {
+    "/me": {
+      get: {
+        operationId: "getMe",
+        security: [{ OAuth2: ["current_user:read"] }],
+        responses: { "200": { description: "ok" } },
+      },
+    },
+  },
+  components: {
+    securitySchemes: {
+      OAuth2: {
+        type: "oauth2",
+        flows: {
+          authorizationCode: {
+            authorizationUrl: "https://example.com/oauth/authorize",
+            tokenUrl: "https://example.com/oauth/token",
+            scopes: {
+              "current_user:read": "Read the current user",
+              "files:read": "Read files",
+              "file_variables:read": "Read variables",
+            },
+          },
+        },
+      },
+    },
+  },
+  security: [{ OAuth2: ["current_user:read"] }],
+};
+
+const scopeOverrides: SpecOverrides = [
+  {
+    op: "replace",
+    path: "/components/securitySchemes/OAuth2/flows/authorizationCode/scopes",
+    value: { "current_user:read": "Read the current user" },
+  },
+];
+
+const encodeJsonText = Schema.encodeUnknownSync(Schema.UnknownFromJsonString);
+
+describe("OpenAPI spec override lifecycle", () => {
+  it.effect("applies scope overrides to preview and persists raw and patched hashes", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+        const sourceText = encodeJsonText(oauthSpec);
+
+        const preview = yield* executor.openapi.previewSpec({
+          spec: sourceText,
+          specOverrides: scopeOverrides,
+        });
+        expect(preview.oauth2Presets).toHaveLength(1);
+        expect(preview.oauth2Presets[0]?.scopes).toEqual({
+          "current_user:read": "Read the current user",
+        });
+
+        yield* executor.openapi.addSpec({
+          spec: { kind: "blob", value: sourceText },
+          slug: "scoped_api",
+          specOverrides: scopeOverrides,
+        });
+
+        const config = yield* executor.openapi.getConfig("scoped_api");
+        const patchedDocument = yield* applySpecOverrides(oauthSpec, scopeOverrides);
+        const patchedText = encodeJsonText(patchedDocument);
+        expect(config?.specOverrides).toEqual(scopeOverrides);
+        expect(config?.sourceSpecHash).toBe(yield* sha256Hex(sourceText));
+        expect(config?.specHash).toBe(yield* sha256Hex(patchedText));
+        const oauth = config?.authenticationTemplate?.find((method) => method.kind === "oauth2");
+        expect(oauth).toMatchObject({ kind: "oauth2", scopes: ["current_user:read"] });
+      }),
+    ),
+  );
+
+  it.effect("changes and clears overrides for an inline spec without repasting the source", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+        const sourceText = encodeJsonText(oauthSpec);
+        yield* executor.openapi.addSpec({
+          spec: { kind: "blob", value: sourceText },
+          slug: "inline_overrides",
+          specOverrides: scopeOverrides,
+        });
+
+        const titleOverrides: SpecOverrides = [
+          { op: "replace", path: "/info/title", value: "Renamed API" },
+        ];
+        yield* executor.openapi.updateSpec("inline_overrides", {
+          specOverrides: titleOverrides,
+        });
+        const renamed = yield* executor.openapi.getConfig("inline_overrides");
+        const renamedDocument = yield* applySpecOverrides(oauthSpec, titleOverrides);
+        expect(renamed?.specOverrides).toEqual(titleOverrides);
+        expect(renamed?.specHash).toBe(yield* sha256Hex(encodeJsonText(renamedDocument)));
+        expect(renamed?.sourceSpecHash).toBe(yield* sha256Hex(sourceText));
+
+        yield* executor.openapi.updateSpec("inline_overrides", { specOverrides: [] });
+        const cleared = yield* executor.openapi.getConfig("inline_overrides");
+        expect(cleared?.specOverrides).toBeUndefined();
+        expect(cleared?.sourceSpecHash).toBeUndefined();
+        expect(cleared?.specHash).toBe(yield* sha256Hex(sourceText));
+      }),
+    ),
+  );
+
+  it.effect("reapplies overrides when a URL-hosted spec changes upstream", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const Items = HttpApiGroup.make("items")
+          .add(HttpApiEndpoint.get("list", "/items", { success: Schema.Array(Schema.String) }))
+          .add(HttpApiEndpoint.post("create", "/items", { success: Schema.String }));
+        const InitialApi = HttpApi.make("initial").add(Items);
+        const server = yield* serveMutableOpenApiSpecTestServer({ initialApi: InitialApi });
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+        const removeList: SpecOverrides = [{ op: "remove", path: "/paths/~1items/get" }];
+
+        yield* executor.openapi.addSpec({
+          spec: { kind: "url", url: server.specUrl },
+          slug: "refresh_overrides",
+          specOverrides: removeList,
+        });
+        const initialPreview = yield* executor.openapi.previewSpec({
+          spec: server.specUrl,
+          specOverrides: removeList,
+        });
+        expect(initialPreview.operations.map((operation) => operation.operationId)).not.toContain(
+          "items.list",
+        );
+
+        const Widgets = HttpApiGroup.make("widgets").add(
+          HttpApiEndpoint.get("list", "/widgets", { success: Schema.Array(Schema.String) }),
+        );
+        const EvolvedApi = HttpApi.make("evolved").add(Items).add(Widgets);
+        yield* server.setApi(EvolvedApi);
+
+        const updated = yield* executor.openapi.updateSpec("refresh_overrides");
+        expect(updated.addedTools).toEqual(["widgets.list"]);
+        expect(updated.removedTools).toEqual([]);
+        const config = yield* executor.openapi.getConfig("refresh_overrides");
+        expect(config?.specOverrides).toEqual(removeList);
+        expect(Option.isSome(initialPreview.title)).toBe(true);
+      }),
+    ),
+  );
+});
diff --git a/packages/plugins/openapi/src/sdk/spec-overrides.test.ts b/packages/plugins/openapi/src/sdk/spec-overrides.test.ts
new file mode 100644
index 000000000..e6ac56ac3
--- /dev/null
+++ b/packages/plugins/openapi/src/sdk/spec-overrides.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import {
+  applySpecOverrides,
+  formatSpecOverridesText,
+  parseSpecOverridesText,
+  type SpecOverrides,
+} from "./spec-overrides";
+
+const apply = (document: unknown, overrides: SpecOverrides) =>
+  Effect.runPromise(applySpecOverrides(document, overrides));
+
+describe("OpenAPI spec overrides", () => {
+  it("parses and formats the JSON Patch editor contract", () => {
+    expect(parseSpecOverridesText("")).toEqual({ ok: true, value: [] });
+    expect(parseSpecOverridesText('[{"op":"remove","path":"/paths/~1legacy"}]')).toEqual({
+      ok: true,
+      value: [{ op: "remove", path: "/paths/~1legacy" }],
+    });
+    expect(parseSpecOverridesText('{"op":"remove"}')).toMatchObject({ ok: false });
+    expect(formatSpecOverridesText([{ op: "remove", path: "/paths/~1legacy" }])).toContain(
+      '"path": "/paths/~1legacy"',
+    );
+  });
+
+  it("applies ordered RFC 6902 operations without mutating the source", async () => {
+    const source = {
+      components: {
+        securitySchemes: {
+          OAuth2: {
+            flows: {
+              authorizationCode: {
+                scopes: { read: "Read", write: "Write" },
+              },
+            },
+          },
+        },
+      },
+      tags: ["one", "two"],
+    };
+
+    const result = await apply(source, [
+      {
+        op: "test",
+        path: "/components/securitySchemes/OAuth2/flows/authorizationCode/scopes/read",
+        value: "Read",
+      },
+      {
+        op: "replace",
+        path: "/components/securitySchemes/OAuth2/flows/authorizationCode/scopes",
+        value: { read: "Read" },
+      },
+      { op: "add", path: "/tags/-", value: "three" },
+      { op: "copy", from: "/tags/0", path: "/primaryTag" },
+      { op: "move", from: "/tags/1", path: "/tags/0" },
+      { op: "remove", path: "/tags/2" },
+    ]);
+
+    expect(result).toEqual({
+      components: {
+        securitySchemes: {
+          OAuth2: {
+            flows: {
+              authorizationCode: {
+                scopes: { read: "Read" },
+              },
+            },
+          },
+        },
+      },
+      tags: ["two", "one"],
+      primaryTag: "one",
+    });
+    expect(source.components.securitySchemes.OAuth2.flows.authorizationCode.scopes).toEqual({
+      read: "Read",
+      write: "Write",
+    });
+    expect(source.tags).toEqual(["one", "two"]);
+  });
+
+  it("reports the exact stale operation and path", async () => {
+    const error = await Effect.runPromise(
+      applySpecOverrides({ openapi: "3.1.0" }, [
+        { op: "replace", path: "/components/securitySchemes/OAuth2", value: {} },
+      ]).pipe(Effect.flip),
+    );
+
+    expect(error).toMatchObject({
+      _tag: "OpenApiSpecOverrideError",
+      operationIndex: 0,
+      operation: "replace",
+      path: "/components/securitySchemes/OAuth2",
+      message: expect.stringContaining(
+        "Spec override 1 (replace /components/securitySchemes/OAuth2) failed",
+      ),
+    });
+  });
+
+  it("rejects invalid pointers and failed test operations", async () => {
+    const invalidPointer = await Effect.runPromise(
+      applySpecOverrides({ openapi: "3.1.0" }, [
+        { op: "add", path: "openapi", value: "3.0.0" },
+      ]).pipe(Effect.flip),
+    );
+    expect(invalidPointer.message).toContain("Invalid JSON Pointer");
+
+    const failedTest = await Effect.runPromise(
+      applySpecOverrides({ openapi: "3.1.0" }, [
+        { op: "test", path: "/openapi", value: "3.0.0" },
+      ]).pipe(Effect.flip),
+    );
+    expect(failedTest.message).toContain("The test value did not match");
+  });
+
+  it("treats prototype-shaped keys as ordinary JSON properties", async () => {
+    const result = await apply({ openapi: "3.1.0" }, [
+      { op: "add", path: "/__proto__", value: { polluted: true } },
+    ]);
+
+    expect(Object.hasOwn(result, "__proto__")).toBe(true);
+    expect(Object.getPrototypeOf(result)).toBeNull();
+    expect(Object.hasOwn(Object.prototype, "polluted")).toBe(false);
+  });
+});
diff --git a/packages/plugins/openapi/src/sdk/spec-overrides.ts b/packages/plugins/openapi/src/sdk/spec-overrides.ts
new file mode 100644
index 000000000..320274b96
--- /dev/null
+++ b/packages/plugins/openapi/src/sdk/spec-overrides.ts
@@ -0,0 +1,361 @@
+import { Data, Effect, Exit, Match, Schema } from "effect";
+
+import { OpenApiSpecOverrideError } from "./errors";
+
+export const JsonPatchOperationSchema = Schema.Union([
+  Schema.Struct({
+    op: Schema.Literal("add"),
+    path: Schema.String,
+    value: Schema.Unknown,
+  }),
+  Schema.Struct({
+    op: Schema.Literal("remove"),
+    path: Schema.String,
+  }),
+  Schema.Struct({
+    op: Schema.Literal("replace"),
+    path: Schema.String,
+    value: Schema.Unknown,
+  }),
+  Schema.Struct({
+    op: Schema.Literal("move"),
+    path: Schema.String,
+    from: Schema.String,
+  }),
+  Schema.Struct({
+    op: Schema.Literal("copy"),
+    path: Schema.String,
+    from: Schema.String,
+  }),
+  Schema.Struct({
+    op: Schema.Literal("test"),
+    path: Schema.String,
+    value: Schema.Unknown,
+  }),
+]);
+
+export const SpecOverridesSchema = Schema.Array(JsonPatchOperationSchema);
+
+export type JsonPatchOperation = typeof JsonPatchOperationSchema.Type;
+export type SpecOverrides = typeof SpecOverridesSchema.Type;
+
+const decodeSpecOverridesText = Schema.decodeUnknownExit(
+  Schema.fromJsonString(SpecOverridesSchema),
+);
+
+export type SpecOverridesTextResult =
+  | { readonly ok: true; readonly value: SpecOverrides }
+  | { readonly ok: false; readonly message: string };
+
+/** Decode user-authored JSON Patch text into the persisted override contract. */
+export const parseSpecOverridesText = (text: string): SpecOverridesTextResult => {
+  if (text.trim().length === 0) return { ok: true, value: [] };
+  const decoded = decodeSpecOverridesText(text);
+  return Exit.isSuccess(decoded)
+    ? { ok: true, value: decoded.value }
+    : {
+        ok: false,
+        message:
+          "Spec overrides must be a JSON array of RFC 6902 add, remove, replace, move, copy, or test operations.",
+      };
+};
+
+/** Format persisted overrides for the advanced JSON editor. */
+export const formatSpecOverridesText = (overrides: SpecOverrides | undefined): string =>
+  overrides && overrides.length > 0 ? JSON.stringify(overrides, null, 2) : "";
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+class PatchApplicationFailure extends Data.TaggedError("PatchApplicationFailure")<{
+  readonly detail: string;
+}> {}
+
+const patchFailure = (detail: string) => new PatchApplicationFailure({ detail });
+
+const isJsonValue = (value: unknown): value is JsonValue => {
+  if (value === null) return true;
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  if (typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  return Object.values(value).every(isJsonValue);
+};
+
+const overrideError = (operationIndex: number, operation: string, path: string, detail: string) =>
+  new OpenApiSpecOverrideError({
+    operationIndex,
+    operation,
+    path,
+    message: `Spec override ${operationIndex + 1} (${operation} ${path || "/"}) failed: ${detail}`,
+  });
+
+const cloneJsonValue = (value: JsonValue): JsonValue => {
+  if (Array.isArray(value)) return value.map(cloneJsonValue);
+  if (value !== null && typeof value === "object") {
+    const clone: JsonObject = Object.create(null);
+    for (const [key, entry] of Object.entries(value)) clone[key] = cloneJsonValue(entry);
+    return clone;
+  }
+  return value;
+};
+
+const parsePointer = Effect.fn("OpenApi.parseJsonPointer")(function* (pointer: string) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) {
+    return yield* patchFailure(`Invalid JSON Pointer ${JSON.stringify(pointer)}`);
+  }
+  const segments: string[] = [];
+  for (const segment of pointer.slice(1).split("/")) {
+    if (/~(?:[^01]|$)/.test(segment)) {
+      return yield* patchFailure(`Invalid JSON Pointer escape in ${JSON.stringify(pointer)}`);
+    }
+    segments.push(segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+  }
+  return segments;
+});
+
+const arrayIndex = Effect.fn("OpenApi.jsonPatchArrayIndex")(function* (
+  segment: string,
+  length: number,
+  pointer: string,
+  options: { readonly append: boolean; readonly existing: boolean },
+) {
+  if (segment === "-") {
+    if (options.append) return length;
+    return yield* patchFailure(`JSON Pointer ${JSON.stringify(pointer)} cannot use '-' here`);
+  }
+  if (!/^(0|[1-9]\d*)$/.test(segment)) {
+    return yield* patchFailure(
+      `JSON Pointer ${JSON.stringify(pointer)} has invalid array index ${JSON.stringify(segment)}`,
+    );
+  }
+  const index = Number(segment);
+  const upperBound = options.existing ? length - 1 : length;
+  if (!Number.isSafeInteger(index) || index < 0 || index > upperBound) {
+    return yield* patchFailure(
+      `JSON Pointer ${JSON.stringify(pointer)} has array index ${index} outside the valid range`,
+    );
+  }
+  return index;
+});
+
+const valueAt = Effect.fn("OpenApi.jsonPatchValueAt")(function* (root: JsonValue, pointer: string) {
+  const segments = yield* parsePointer(pointer);
+  let current = root;
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      current =
+        current[
+          yield* arrayIndex(segment, current.length, pointer, {
+            append: false,
+            existing: true,
+          })
+        ]!;
+      continue;
+    }
+    if (current !== null && typeof current === "object") {
+      if (!Object.hasOwn(current, segment)) {
+        return yield* patchFailure(`JSON Pointer ${JSON.stringify(pointer)} does not exist`);
+      }
+      current = current[segment]!;
+      continue;
+    }
+    return yield* patchFailure(`JSON Pointer ${JSON.stringify(pointer)} cannot be traversed`);
+  }
+  return current;
+});
+
+const parentAt = Effect.fn("OpenApi.jsonPatchParentAt")(function* (
+  root: JsonValue,
+  pointer: string,
+) {
+  const segments = yield* parsePointer(pointer);
+  if (segments.length === 0) {
+    return yield* patchFailure("The document root has no parent");
+  }
+  const parentPointer = `/${segments
+    .slice(0, -1)
+    .map((segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1"))
+    .join("/")}`;
+  const parent = segments.length === 1 ? root : yield* valueAt(root, parentPointer);
+  if (parent === null || typeof parent !== "object") {
+    return yield* patchFailure(`JSON Pointer ${JSON.stringify(pointer)} has no container`);
+  }
+  return { parent, segment: segments[segments.length - 1]! };
+});
+
+const addValue = Effect.fn("OpenApi.jsonPatchAddValue")(function* (
+  root: JsonValue,
+  pointer: string,
+  value: JsonValue,
+) {
+  if (pointer === "") return cloneJsonValue(value);
+  const { parent, segment } = yield* parentAt(root, pointer);
+  if (Array.isArray(parent)) {
+    const index = yield* arrayIndex(segment, parent.length, pointer, {
+      append: true,
+      existing: false,
+    });
+    parent.splice(index, 0, cloneJsonValue(value));
+  } else {
+    parent[segment] = cloneJsonValue(value);
+  }
+  return root;
+});
+
+const removeValue = Effect.fn("OpenApi.jsonPatchRemoveValue")(function* (
+  root: JsonValue,
+  pointer: string,
+) {
+  if (pointer === "") return { root: null, removed: root };
+  const { parent, segment } = yield* parentAt(root, pointer);
+  if (Array.isArray(parent)) {
+    const index = yield* arrayIndex(segment, parent.length, pointer, {
+      append: false,
+      existing: true,
+    });
+    return { root, removed: parent.splice(index, 1)[0]! };
+  }
+  if (!Object.hasOwn(parent, segment)) {
+    return yield* patchFailure(`JSON Pointer ${JSON.stringify(pointer)} does not exist`);
+  }
+  const removed = parent[segment]!;
+  delete parent[segment];
+  return { root, removed };
+});
+
+const replaceValue = Effect.fn("OpenApi.jsonPatchReplaceValue")(function* (
+  root: JsonValue,
+  pointer: string,
+  value: JsonValue,
+) {
+  if (pointer === "") return cloneJsonValue(value);
+  yield* valueAt(root, pointer);
+  const { parent, segment } = yield* parentAt(root, pointer);
+  if (Array.isArray(parent)) {
+    const index = yield* arrayIndex(segment, parent.length, pointer, {
+      append: false,
+      existing: true,
+    });
+    parent[index] = cloneJsonValue(value);
+  } else {
+    parent[segment] = cloneJsonValue(value);
+  }
+  return root;
+});
+
+const jsonEquals = (left: JsonValue, right: JsonValue): boolean => {
+  if (left === right) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((entry, index) => jsonEquals(entry, right[index]!))
+    );
+  }
+  if (left === null || right === null || typeof left !== "object" || typeof right !== "object") {
+    return false;
+  }
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => Object.hasOwn(right, key) && jsonEquals(left[key]!, right[key]!))
+  );
+};
+
+const operationValue = Effect.fn("OpenApi.jsonPatchOperationValue")(function* (
+  operation: JsonPatchOperation,
+) {
+  if (!("value" in operation) || !isJsonValue(operation.value)) {
+    return yield* patchFailure(`${operation.op} requires a JSON value`);
+  }
+  return operation.value;
+});
+
+const applyOperation = (root: JsonValue, operation: JsonPatchOperation) =>
+  Match.value(operation).pipe(
+    Match.when({ op: "add" }, (entry) =>
+      Effect.gen(function* () {
+        const value = yield* operationValue(entry);
+        return yield* addValue(root, entry.path, value);
+      }),
+    ),
+    Match.when({ op: "remove" }, (entry) =>
+      removeValue(root, entry.path).pipe(Effect.map((result) => result.root)),
+    ),
+    Match.when({ op: "replace" }, (entry) =>
+      Effect.gen(function* () {
+        const value = yield* operationValue(entry);
+        return yield* replaceValue(root, entry.path, value);
+      }),
+    ),
+    Match.when({ op: "copy" }, (entry) =>
+      Effect.gen(function* () {
+        const value = yield* valueAt(root, entry.from);
+        return yield* addValue(root, entry.path, value);
+      }),
+    ),
+    Match.when({ op: "move" }, (entry) =>
+      Effect.gen(function* () {
+        if (entry.path.startsWith(`${entry.from}/`)) {
+          return yield* patchFailure("A value cannot be moved into one of its children");
+        }
+        const removed = yield* removeValue(root, entry.from);
+        return yield* addValue(removed.root, entry.path, removed.removed);
+      }),
+    ),
+    Match.when({ op: "test" }, (entry) =>
+      Effect.gen(function* () {
+        const expected = yield* operationValue(entry);
+        const actual = yield* valueAt(root, entry.path);
+        if (!jsonEquals(actual, expected)) {
+          return yield* patchFailure("The test value did not match");
+        }
+        return root;
+      }),
+    ),
+    Match.exhaustive,
+  );
+
+/** Apply ordered RFC 6902 operations to a cloned JSON document. */
+export const applySpecOverrides = Effect.fn("OpenApi.applySpecOverrides")(function* (
+  document: unknown,
+  overrides: SpecOverrides,
+) {
+  if (!isJsonValue(document)) {
+    return yield* overrideError(
+      0,
+      "parse",
+      "",
+      "OpenAPI document must contain only JSON-compatible values",
+    );
+  }
+
+  let result = cloneJsonValue(document);
+  for (const [operationIndex, operation] of overrides.entries()) {
+    const applied = yield* applyOperation(result, operation).pipe(
+      Effect.mapError((failure) =>
+        overrideError(operationIndex, operation.op, operation.path, failure.detail),
+      ),
+    );
+    result = applied;
+  }
+
+  if (result === null || typeof result !== "object" || Array.isArray(result)) {
+    return yield* overrideError(
+      Math.max(0, overrides.length - 1),
+      overrides.at(-1)?.op ?? "parse",
+      overrides.at(-1)?.path ?? "",
+      "Spec overrides must leave the OpenAPI document as an object",
+    );
+  }
+  return result;
+});

From bdcc62cb974e0b0c58c151a7ed7ac55365c2df91 Mon Sep 17 00:00:00 2001
From: Rhys Sullivan <39114868+RhysSullivan@users.noreply.github.com>
Date: Thu, 16 Jul 2026 18:04:44 -0700
Subject: [PATCH 2/2] Default Figma OAuth scopes

---
 .changeset/persist-openapi-spec-overrides.md  |  3 +-
 packages/core/sdk/src/client.ts               |  2 +
 packages/core/sdk/src/plugin.ts               |  2 +
 .../src/react/AddOpenApiIntegration.test.ts   | 25 ++++++++
 .../src/react/AddOpenApiIntegration.tsx       | 64 ++++++++++++-------
 packages/plugins/openapi/src/sdk/plugin.ts    | 42 +++++++-----
 .../plugins/openapi/src/sdk/presets.test.ts   | 37 +++++++++++
 packages/plugins/openapi/src/sdk/presets.ts   | 38 +++++++++++
 .../plugins/openapi/src/sdk/spec-overrides.ts |  7 +-
 .../provider-service-split/src/planner.ts     |  6 +-
 10 files changed, 183 insertions(+), 43 deletions(-)
 create mode 100644 packages/plugins/openapi/src/sdk/presets.test.ts

diff --git a/.changeset/persist-openapi-spec-overrides.md b/.changeset/persist-openapi-spec-overrides.md
index 09dab81ea..9f46c5b56 100644
--- a/.changeset/persist-openapi-spec-overrides.md
+++ b/.changeset/persist-openapi-spec-overrides.md
@@ -1,5 +1,6 @@
 ---
 "@executor-js/plugin-openapi": patch
+"@executor-js/sdk": patch
 ---
 
-Apply persisted RFC 6902 overrides to OpenAPI specifications during preview, import, and refresh so upstream documents can be corrected without maintaining a fork.
+Apply persisted RFC 6902 overrides to OpenAPI specifications during preview, import, and refresh so upstream documents can be corrected without maintaining a fork. Figma imports automatically narrow OAuth to the scopes supported by its OAuth app configuration.
diff --git a/packages/core/sdk/src/client.ts b/packages/core/sdk/src/client.ts
index 3dcfd697b..d0fc0ee97 100644
--- a/packages/core/sdk/src/client.ts
+++ b/packages/core/sdk/src/client.ts
@@ -116,6 +116,8 @@ export interface IntegrationPreset {
   readonly family?: string;
   readonly specFormat?: string;
   readonly defaultSlug?: string;
+  /** Plugin-specific RFC 6902 operations applied to a fetched specification. */
+  readonly specOverrides?: readonly unknown[];
   readonly authTemplate?: readonly IntegrationPresetAuthentication[];
   readonly healthCheck?: HealthCheckSpec;
 }
diff --git a/packages/core/sdk/src/plugin.ts b/packages/core/sdk/src/plugin.ts
index 1df466856..6d4dbc23b 100644
--- a/packages/core/sdk/src/plugin.ts
+++ b/packages/core/sdk/src/plugin.ts
@@ -568,6 +568,8 @@ export interface IntegrationPreset {
   readonly family?: string;
   readonly specFormat?: string;
   readonly defaultSlug?: string;
+  /** Plugin-specific RFC 6902 operations applied to a fetched specification. */
+  readonly specOverrides?: readonly unknown[];
   readonly authTemplate?: readonly IntegrationPresetAuthentication[];
   readonly healthCheck?: HealthCheckSpec;
   readonly transport?: "remote" | "stdio";
diff --git a/packages/plugins/openapi/src/react/AddOpenApiIntegration.test.ts b/packages/plugins/openapi/src/react/AddOpenApiIntegration.test.ts
index a7dccd0f9..2ffb87096 100644
--- a/packages/plugins/openapi/src/react/AddOpenApiIntegration.test.ts
+++ b/packages/plugins/openapi/src/react/AddOpenApiIntegration.test.ts
@@ -5,7 +5,9 @@ import {
   AddOpenApiHealthCheckSection,
   baseUrlFromSpecInput,
   openApiPreviewFailureMessage,
+  resolveOpenApiPreset,
 } from "./AddOpenApiIntegration";
+import { openApiPresets } from "../sdk/presets";
 
 const visibleText = (node: React.ReactNode): string => {
   if (node === null || node === undefined || typeof node === "boolean") return "";
@@ -42,6 +44,29 @@ describe("openApiPreviewFailureMessage", () => {
   });
 });
 
+describe("resolveOpenApiPreset", () => {
+  it("matches Figma defaults from its canonical spec URL", () => {
+    const preset = resolveOpenApiPreset(
+      openApiPresets,
+      undefined,
+      "https://raw.githubusercontent.com/figma/rest-api-spec/refs/heads/main/openapi/openapi.yaml#ignored",
+    );
+
+    expect(preset?.id).toBe("figma");
+    expect(preset?.specOverrides).toBeTruthy();
+  });
+
+  it("prefers an explicitly selected preset over URL matching", () => {
+    const preset = resolveOpenApiPreset(
+      openApiPresets,
+      "stripe",
+      "https://raw.githubusercontent.com/figma/rest-api-spec/refs/heads/main/openapi/openapi.yaml",
+    );
+
+    expect(preset?.id).toBe("stripe");
+  });
+});
+
 describe("AddOpenApiHealthCheckSection", () => {
   const candidate = {
     operation: "getCurrentUser",
diff --git a/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx b/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
index 7e3ce5e60..19c90b888 100644
--- a/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
+++ b/packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx
@@ -10,7 +10,7 @@ import {
   type HealthCheckCandidate,
   type HealthCheckSpec,
 } from "@executor-js/sdk/shared";
-import { useIntegrationPlugins } from "@executor-js/sdk/client";
+import { useIntegrationPlugins, type IntegrationPreset } from "@executor-js/sdk/client";
 import { integrationWriteKeys, healthCheckWriteKeys } from "@executor-js/react/api/reactivity-keys";
 import { setIntegrationHealthCheck } from "@executor-js/react/api/atoms";
 import {
@@ -49,7 +49,11 @@ import type { SpecPreviewSummary } from "../sdk/preview";
 import { type Authentication } from "../sdk/types";
 import { resolveServerUrl } from "../sdk/openapi-utils";
 import { detectedAuthenticationTemplates } from "../sdk/derive-auth";
-import { parseSpecOverridesText } from "../sdk/spec-overrides";
+import {
+  decodeOpenApiSpecOverrides,
+  formatSpecOverridesText,
+  parseSpecOverridesText,
+} from "../sdk/spec-overrides";
 import { SpecOverridesEditor } from "./SpecOverridesEditor";
 
 const normalizePresetUrl = (url: string): string => {
@@ -61,6 +65,22 @@ const normalizePresetUrl = (url: string): string => {
   return parsed.toString().replace(/\/$/, "");
 };
 
+/** Resolve catalog defaults from an explicit preset id or a matching spec URL. */
+export const resolveOpenApiPreset = (
+  presets: readonly IntegrationPreset[] | undefined,
+  initialPresetId: string | undefined,
+  specUrl: string,
+): IntegrationPreset | null => {
+  const explicitPreset = presets?.find((preset) => preset.id === initialPresetId);
+  if (explicitPreset) return explicitPreset;
+  if (specUrl.trim().length === 0) return null;
+  const normalizedSpecUrl = normalizePresetUrl(specUrl);
+  return (
+    presets?.find((preset) => preset.url && normalizePresetUrl(preset.url) === normalizedSpecUrl) ??
+    null
+  );
+};
+
 const specInputForAdd = (input: string) => {
   const value = input.trim();
   const parsed = Effect.runSyncExit(
@@ -154,12 +174,15 @@ export default function AddOpenApiIntegration(props: {
   const integrationPlugins = useIntegrationPlugins();
   const openApiPlugin = integrationPlugins.find((plugin) => plugin.key === "openapi");
   const openApiPresets = openApiPlugin?.presets;
-  const initialPreset = openApiPresets?.find((preset) => preset.id === props.initialPreset) ?? null;
   const [specUrl, setSpecUrl] = useState(props.initialUrl ?? "");
-  const [specOverridesText, setSpecOverridesText] = useState("");
+  const [specOverridesDraft, setSpecOverridesDraft] = useState<string | null>(null);
   const [analyzing, setAnalyzing] = useState(false);
   const [analyzeError, setAnalyzeError] = useState<string | null>(null);
 
+  const activePreset = resolveOpenApiPreset(openApiPresets, props.initialPreset, specUrl);
+  const presetSpecOverrides = decodeOpenApiSpecOverrides(activePreset?.specOverrides);
+  const specOverridesText = specOverridesDraft ?? formatSpecOverridesText(presetSpecOverrides);
+
   // After analysis
   const [preview, setPreview] = useState<SpecPreviewSummary | null>(null);
   const [baseUrl, setBaseUrl] = useState("");
@@ -167,7 +190,7 @@ export default function AddOpenApiIntegration(props: {
   // until the user types (null = untouched, keep deriving from the preview).
   const [descriptionDraft, setDescriptionDraft] = useState<string | null>(null);
   const identityFallbackName =
-    initialPreset?.name ?? (preview ? Option.getOrElse(preview.title, () => "") : "");
+    activePreset?.name ?? (preview ? Option.getOrElse(preview.title, () => "") : "");
   const identity = useIntegrationIdentity({
     fallbackName: identityFallbackName,
     fallbackNamespace: props.initialNamespace,
@@ -219,14 +242,11 @@ export default function AddOpenApiIntegration(props: {
   const firstServerUrl = firstServer
     ? resolveServerUrl(firstServer.url, Option.getOrUndefined(firstServer.variables), {})
     : "";
-  const previewPresetIcon =
-    openApiPresets?.find(
-      (preset) => preset.url && normalizePresetUrl(preset.url) === normalizePresetUrl(specUrl),
-    )?.icon ?? null;
+  const previewPresetIcon = activePreset?.icon ?? null;
 
   const resolvedBaseUrl = baseUrl.trim();
   const resolvedIntegrationId =
-    initialPreset?.defaultSlug ||
+    activePreset?.defaultSlug ||
     slugifyNamespace(identity.namespace) ||
     (preview ? Option.getOrElse(preview.title, () => "openapi") : "openapi");
   const resolvedDisplayName =
@@ -245,8 +265,8 @@ export default function AddOpenApiIntegration(props: {
   // Keyed off `preview` (stable per analysis) so the memo doesn't re-run on the
   // freshly-allocated `?? []` fallback arrays.
   const authenticationTemplate: readonly Authentication[] = useMemo(() => {
-    if (initialPreset?.authTemplate) {
-      return initialPreset.authTemplate.flatMap((template): readonly Authentication[] =>
+    if (activePreset?.authTemplate) {
+      return activePreset.authTemplate.flatMap((template): readonly Authentication[] =>
         template.kind === "oauth2"
           ? [
               {
@@ -263,7 +283,7 @@ export default function AddOpenApiIntegration(props: {
       preview?.oauth2Presets ?? [],
       resolvedBaseUrl,
     );
-  }, [initialPreset?.authTemplate, preview, resolvedBaseUrl]);
+  }, [activePreset?.authTemplate, preview, resolvedBaseUrl]);
 
   // Editable auth methods, seeded from the spec-detected templates. The add flow
   // registers EVERY method (P6), so this is a LIST, preserving multi-method
@@ -359,7 +379,7 @@ export default function AddOpenApiIntegration(props: {
     const exit = await doPreview({
       payload: {
         spec: specUrl,
-        specFormat: initialPreset?.specFormat,
+        specFormat: activePreset?.specFormat,
         ...(parsedSpecOverrides.value.length > 0
           ? { specOverrides: parsedSpecOverrides.value }
           : {}),
@@ -391,9 +411,9 @@ export default function AddOpenApiIntegration(props: {
           ? { description: resolvedDescription.trim() }
           : {}),
         baseUrl: resolvedBaseUrl,
-        specFormat: initialPreset?.specFormat,
-        family: initialPreset?.family,
-        healthCheck: initialPreset?.healthCheck,
+        specFormat: activePreset?.specFormat,
+        family: activePreset?.family,
+        healthCheck: activePreset?.healthCheck,
         ...(parsedSpecOverrides.ok && parsedSpecOverrides.value.length > 0
           ? { specOverrides: parsedSpecOverrides.value }
           : {}),
@@ -422,9 +442,9 @@ export default function AddOpenApiIntegration(props: {
     resolvedBaseUrl,
     editedAuthenticationTemplate,
     parsedSpecOverrides,
-    initialPreset?.family,
-    initialPreset?.healthCheck,
-    initialPreset?.specFormat,
+    activePreset?.family,
+    activePreset?.healthCheck,
+    activePreset?.specFormat,
   ]);
 
   const handleAdd = async () => {
@@ -565,7 +585,7 @@ export default function AddOpenApiIntegration(props: {
       <SpecOverridesEditor
         value={specOverridesText}
         onChange={(value) => {
-          setSpecOverridesText(value);
+          setSpecOverridesDraft(value);
           setAnalyzeError(null);
           setPreview(null);
           setBaseUrl("");
@@ -583,7 +603,7 @@ export default function AddOpenApiIntegration(props: {
 
       {preview ? (
         <AddOpenApiHealthCheckSection
-          presetHealthCheck={initialPreset?.healthCheck}
+          presetHealthCheck={activePreset?.healthCheck}
           candidates={healthCheckCandidates}
           selected={hcSelected}
           operation={hcOperation}
diff --git a/packages/plugins/openapi/src/sdk/plugin.ts b/packages/plugins/openapi/src/sdk/plugin.ts
index 46b17b12b..234b163f3 100644
--- a/packages/plugins/openapi/src/sdk/plugin.ts
+++ b/packages/plugins/openapi/src/sdk/plugin.ts
@@ -16,6 +16,7 @@ import {
   type AuthMethodDescriptor,
   type Integration,
   type IntegrationConfig,
+  type IntegrationPreset,
   type IntegrationRecord,
   type PluginCtx,
   type StorageFailure,
@@ -39,7 +40,7 @@ import {
   type SpecPreview,
 } from "./preview";
 import { deriveAuthenticationTemplateFromPreview, firstBaseUrlForPreview } from "./derive-auth";
-import { openApiPresets, type OpenApiPreset } from "./presets";
+import { openApiPresets } from "./presets";
 import { makeDefaultOpenapiStore, type OpenapiStore } from "./store";
 import {
   resolveSpecFormatAdapter,
@@ -62,7 +63,12 @@ import {
 } from "./backing";
 import type { InvokeOptions } from "./invoke";
 import { resolveServerUrl } from "./openapi-utils";
-import { applySpecOverrides, SpecOverridesSchema, type SpecOverrides } from "./spec-overrides";
+import {
+  applySpecOverrides,
+  decodeOpenApiSpecOverrides,
+  SpecOverridesSchema,
+  type SpecOverrides,
+} from "./spec-overrides";
 
 const encodeJsonText = Schema.encodeUnknownSync(Schema.UnknownFromJsonString);
 
@@ -608,7 +614,7 @@ export interface OpenApiPluginOptions {
   readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient, never, never>;
   readonly invokeOptions?: InvokeOptions;
   readonly specFormats?: readonly SpecFormatAdapter[];
-  readonly presets?: readonly OpenApiPreset[];
+  readonly presets?: readonly IntegrationPreset[];
 }
 
 export const openApiPlugin = definePlugin<
@@ -687,19 +693,23 @@ export const openApiPlugin = definePlugin<
     id: "openapi" as const,
     packageName: "@executor-js/plugin-openapi",
     clientConfig: options?.presets ? { presets: options.presets } : undefined,
-    integrationPresets: [...openApiPresets, ...(options?.presets ?? [])].map((preset) => ({
-      id: preset.id,
-      name: preset.name,
-      summary: preset.summary,
-      ...(preset.url ? { url: preset.url } : {}),
-      ...(preset.icon ? { icon: preset.icon } : {}),
-      ...(preset.featured ? { featured: preset.featured } : {}),
-      ...(preset.family ? { family: preset.family } : {}),
-      ...(preset.specFormat ? { specFormat: preset.specFormat } : {}),
-      ...(preset.defaultSlug ? { defaultSlug: preset.defaultSlug } : {}),
-      ...(preset.authTemplate ? { authTemplate: preset.authTemplate } : {}),
-      ...(preset.healthCheck ? { healthCheck: preset.healthCheck } : {}),
-    })),
+    integrationPresets: [...openApiPresets, ...(options?.presets ?? [])].map((preset) => {
+      const specOverrides = decodeOpenApiSpecOverrides(preset.specOverrides);
+      return {
+        id: preset.id,
+        name: preset.name,
+        summary: preset.summary,
+        ...(preset.url ? { url: preset.url } : {}),
+        ...(preset.icon ? { icon: preset.icon } : {}),
+        ...(preset.featured ? { featured: preset.featured } : {}),
+        ...(preset.family ? { family: preset.family } : {}),
+        ...(preset.specFormat ? { specFormat: preset.specFormat } : {}),
+        ...(preset.defaultSlug ? { defaultSlug: preset.defaultSlug } : {}),
+        ...(specOverrides ? { specOverrides } : {}),
+        ...(preset.authTemplate ? { authTemplate: preset.authTemplate } : {}),
+        ...(preset.healthCheck ? { healthCheck: preset.healthCheck } : {}),
+      };
+    }),
     storage: (deps): OpenapiStore => makeDefaultOpenapiStore(deps),
 
     extension: (ctx: PluginCtx<OpenapiStore>) => {
diff --git a/packages/plugins/openapi/src/sdk/presets.test.ts b/packages/plugins/openapi/src/sdk/presets.test.ts
new file mode 100644
index 000000000..2b063309d
--- /dev/null
+++ b/packages/plugins/openapi/src/sdk/presets.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { openApiPlugin } from "./plugin";
+import { FIGMA_SPEC_OVERRIDES, FIGMA_SUPPORTED_OAUTH_SCOPES, openApiPresets } from "./presets";
+
+const unsupportedFigmaOAuthScopes = [
+  "file_variables:read",
+  "file_variables:write",
+  "files:read",
+  "library_analytics:read",
+] as const;
+
+describe("OpenAPI presets", () => {
+  it("narrows Figma OAuth to the supported scope set", () => {
+    expect(FIGMA_SUPPORTED_OAUTH_SCOPES).toHaveLength(15);
+    for (const scope of unsupportedFigmaOAuthScopes) {
+      expect(FIGMA_SUPPORTED_OAUTH_SCOPES).not.toContain(scope);
+    }
+
+    const operation = FIGMA_SPEC_OVERRIDES[0];
+    expect(operation).toMatchObject({
+      op: "replace",
+      path: "/components/securitySchemes/OAuth2/flows/authorizationCode/scopes",
+      value: Object.fromEntries(FIGMA_SUPPORTED_OAUTH_SCOPES.map((scope) => [scope, ""])),
+    });
+  });
+
+  it("projects Figma spec overrides through the plugin catalog", () => {
+    const sdkPreset = openApiPresets.find((preset) => preset.id === "figma");
+    const catalogPreset = openApiPlugin().integrationPresets?.find(
+      (preset) => preset.id === "figma",
+    );
+
+    expect(sdkPreset?.specOverrides).toEqual(FIGMA_SPEC_OVERRIDES);
+    expect(catalogPreset?.specOverrides).toEqual(FIGMA_SPEC_OVERRIDES);
+  });
+});
diff --git a/packages/plugins/openapi/src/sdk/presets.ts b/packages/plugins/openapi/src/sdk/presets.ts
index 42f487d5e..dcc2f81b7 100644
--- a/packages/plugins/openapi/src/sdk/presets.ts
+++ b/packages/plugins/openapi/src/sdk/presets.ts
@@ -1,4 +1,5 @@
 import type { HealthCheckSpec, IntegrationPresetAuthentication } from "@executor-js/sdk/core";
+import type { SpecOverrides } from "./spec-overrides";
 
 export interface OpenApiPreset {
   readonly id: string;
@@ -10,11 +11,48 @@ export interface OpenApiPreset {
   readonly family?: string;
   readonly specFormat?: string;
   readonly defaultSlug?: string;
+  readonly specOverrides?: SpecOverrides;
   readonly authTemplate?: readonly IntegrationPresetAuthentication[];
   readonly healthCheck?: HealthCheckSpec;
 }
 
+export const FIGMA_SUPPORTED_OAUTH_SCOPES = [
+  "current_user:read",
+  "file_comments:read",
+  "file_comments:write",
+  "file_content:read",
+  "file_dev_resources:read",
+  "file_dev_resources:write",
+  "file_metadata:read",
+  "file_versions:read",
+  "library_assets:read",
+  "library_content:read",
+  "project_metadata:read",
+  "projects:read",
+  "team_library_content:read",
+  "webhooks:read",
+  "webhooks:write",
+] as const;
+
+export const FIGMA_SPEC_OVERRIDES: SpecOverrides = [
+  {
+    op: "replace",
+    path: "/components/securitySchemes/OAuth2/flows/authorizationCode/scopes",
+    value: Object.fromEntries(FIGMA_SUPPORTED_OAUTH_SCOPES.map((scope) => [scope, ""])),
+  },
+];
+
 const openApiOnlyPresets: readonly OpenApiPreset[] = [
+  {
+    id: "figma",
+    name: "Figma",
+    summary: "Files, comments, components, variables, projects, and webhooks.",
+    url: "https://raw.githubusercontent.com/figma/rest-api-spec/refs/heads/main/openapi/openapi.yaml",
+    icon: "https://integrations.sh/logo/figma.com",
+    featured: true,
+    defaultSlug: "figma_api",
+    specOverrides: FIGMA_SPEC_OVERRIDES,
+  },
   {
     id: "stripe",
     name: "Stripe",
diff --git a/packages/plugins/openapi/src/sdk/spec-overrides.ts b/packages/plugins/openapi/src/sdk/spec-overrides.ts
index 320274b96..029b413e7 100644
--- a/packages/plugins/openapi/src/sdk/spec-overrides.ts
+++ b/packages/plugins/openapi/src/sdk/spec-overrides.ts
@@ -1,4 +1,4 @@
-import { Data, Effect, Exit, Match, Schema } from "effect";
+import { Data, Effect, Exit, Match, Option, Schema } from "effect";
 
 import { OpenApiSpecOverrideError } from "./errors";
 
@@ -42,11 +42,16 @@ export type SpecOverrides = typeof SpecOverridesSchema.Type;
 const decodeSpecOverridesText = Schema.decodeUnknownExit(
   Schema.fromJsonString(SpecOverridesSchema),
 );
+const decodeSpecOverrides = Schema.decodeUnknownOption(SpecOverridesSchema);
 
 export type SpecOverridesTextResult =
   | { readonly ok: true; readonly value: SpecOverrides }
   | { readonly ok: false; readonly message: string };
 
+/** Decode preset or persisted override data at a plugin boundary. */
+export const decodeOpenApiSpecOverrides = (value: unknown): SpecOverrides | undefined =>
+  decodeSpecOverrides(value).pipe(Option.getOrUndefined);
+
 /** Decode user-authored JSON Patch text into the persisted override contract. */
 export const parseSpecOverridesText = (text: string): SpecOverridesTextResult => {
   if (text.trim().length === 0) return { ok: true, value: [] };
diff --git a/packages/plugins/provider-service-split/src/planner.ts b/packages/plugins/provider-service-split/src/planner.ts
index 3e00af5f5..69f5ad113 100644
--- a/packages/plugins/provider-service-split/src/planner.ts
+++ b/packages/plugins/provider-service-split/src/planner.ts
@@ -9,7 +9,7 @@ import {
   MICROSOFT_GRAPH_DEFAULT_PRESET_IDS,
   microsoftCatalog,
 } from "@executor-js/plugin-openapi/providers/microsoft";
-import type { OpenApiPreset } from "@executor-js/plugin-openapi/presets";
+import type { IntegrationPreset } from "@executor-js/sdk/core";
 
 type MonolithPluginId = "google" | "microsoft";
 
@@ -330,11 +330,11 @@ const integrationPatternSegment = (
   return { prefix, integration: tail.split(".")[0] ?? "" };
 };
 
-const googleCatalogById: ReadonlyMap<string, OpenApiPreset> = new Map(
+const googleCatalogById: ReadonlyMap<string, IntegrationPreset> = new Map(
   googleCatalog.map((preset) => [preset.id, preset]),
 );
 
-const microsoftCatalogByMonolithPresetId: ReadonlyMap<string, OpenApiPreset> = new Map(
+const microsoftCatalogByMonolithPresetId: ReadonlyMap<string, IntegrationPreset> = new Map(
   microsoftCatalog.map((preset) => [preset.id.replace(/^microsoft-/, ""), preset]),
 );