@jxsuite/studio 10.1.0 → 10.3.0

package/src/panels/data-grid.ts

@@ -23,7 +23,6 @@ import { mountDataActionsSurface } from "../surfaces/data-actions";
 import { mountPushPlanSurface } from "../surfaces/push-plan";
 import { dataSurfaceAvailable, pushSchema, testConnection } from "../services/data-service";
 import { openGridSourcePicker } from "../grid/grid-open";
-import { closeSettingsDialog } from "../settings/settings-dialog";
 import type { DataActionsSurfaceHandle, DataActionsView } from "../surfaces/data-actions";
 import type { DialogSurfaceHandle } from "../surfaces/dialog";
 import type { PushPlanSurfaceHandle, PushPlanView } from "../surfaces/push-plan";
@@ -278,9 +277,6 @@ function paintSectionActions(
     host,
     mountDataActionsSurface(host, projectActions(sectionKey, selected), {
       openGrid: () => {
-        /* The actions row is drawn in the settings dialog, and a grid opens as a TAB: left up, the
-           dialog would cover the very tab the reader asked for (§17.1). */
-        closeSettingsDialog();
         void openGridSourcePicker();
       },
       push: () => {

package/src/panels/pane-context.ts

@@ -800,7 +800,12 @@ function editorAxis(tab: Tab): Partial<PaneContextView> {
   const current = editorKindOf(tab);
   const kinds = IMPLICIT_EDITOR_KINDS.has(current)
     ? [current]
-    : editorKindsOf(tab).filter((kind) => !IMPLICIT_EDITOR_KINDS.has(kind));
+    : editorKindsOf(tab).filter(
+        (kind) =>
+          !IMPLICIT_EDITOR_KINDS.has(kind) &&
+          // A collaborator who cannot write is not offered the editor that exists to write (§9.5).
+          (kind !== "image" || kind === current || !collabState(tab).readOnly),
+      );
   if (kinds.length < 2) {
     // One kind is not a choice. Rendering it as a segmented group would be a control that cannot move —
     // Which is the defect this axis exists to remove, in miniature.

package/src/panels/settings-menu.ts

@@ -15,15 +15,15 @@
  * a record joins the menu by declaring the placement and leaves by not declaring it. The submenus
  * are the enumeration of each parent command's own `section` ARGUMENT, read from that argument's
  * own definition site — which is state the command already validates, not a second vocabulary
- * (`studio-ui-guidelines.md` §12.5). Project Settings' submenu is GROUPED as its dialog's nav is
+ * (`studio-ui-guidelines.md` §12.5). Project Settings' submenu is GROUPED as its own nav is
  * (General, Integrations, Advanced), with a divider where the group changes.
  *
  * **A parent row runs its own command AND owns a submenu.** The APG menu pattern does not describe
  * that and Spectrum's stock submenu forbade it outright; the kit's `jx-menu-item` makes it the rule
  * (`ui.md` §5.1), so the deviation `specs/studio-ui-guidelines.md` §8.4 records is now what the
  * element does rather than what this file hand-rolls around it. Nothing is unreachable by keyboard:
- * Enter runs the row, ArrowRight reaches every child, and every child is also in the settings
- * dialog's own nav.
+ * Enter runs the row, ArrowRight reaches every child, and every child is also in Project Settings'
+ * own nav.
  *
  * The menu is the `menu` surface (`surfaces/menu.json`, through `surfaces/menu.ts`). What is left
  * here is the projection — which records, which sections, what each row runs — and where the panel

package/src/panels/settings-pane.ts

@@ -1,26 +1,25 @@
 /// <reference lib="dom" />
 /**
  * The Project Settings editor's flow: the grouped section list, the section body, and the Moved
- * footnote, drawn inside the settings dialog (§17.1).
+ * footnote, drawn as the Settings workspace's home (§17.1, §22.9).
  *
  * Two columns. The list is the section registry in its three groups (General, Integrations,
- * Advanced), so an extension's section joins the dialog by registering and leaves by going away;
- * the body is whichever section is current, drawn by that section's own renderer.
+ * Advanced), so an extension's section joins Settings by registering and leaves by going away; the
+ * body is whichever section is current, drawn by that section's own renderer.
  *
  * **This file is the FLOW; the markup is a document.** `surfaces/settings-pane.json` owns the two
  * columns, the lists' ARIA and keyboard, and every value in their style;
  * `surfaces/settings-pane.ts` mounts it (studio-ui-guidelines.md §6, §9.3), and
- * `settings/settings-dialog.ts` owns the dialog it is mounted into. What stays here is the part
+ * `settings/settings-workspace.ts` owns the pane it is mounted into. What stays here is the part
  * that is a decision: which sections there are, which one is current, which renderer gets the body,
  * and what a renderer's failure says.
  *
  * **It imports the registry, never the sections.** The section RENDERERS are registered by
  * `settings/settings-document.ts`, which the app loads when it registers its commands.
  *
- * Nothing here is stamped with a region of its own. The dialog carries `overlay.dialog:settings`,
- * and the entry rows and entry editor of a map-layout section are stamped by
- * `settings/contributed-section.ts` under it, as `overlay.dialog:settings/entry:<key>` and
- * `overlay.dialog:settings/editor`.
+ * The home carries the region its host hands in, `pane.<id>/settings`, and the entry rows and entry
+ * editor of a map-layout section are stamped by `settings/contributed-section.ts` under it, as
+ * `pane.<id>/settings/entry:<key>` and `pane.<id>/settings/editor`.
  *
  * @docs studio/projects/settings
  */
@@ -41,6 +40,9 @@ import type { WorkspaceId } from "../workspace/workspace-ids";
 import type { StylesView } from "../style/project-styles";
 import type { PublishTab } from "../publish/publish-ids";
 
+/** The home's heading: the workspace's own title, so the two cannot drift apart. */
+const HEADING = workspaceInfo("settings").title;
+
 /** What the body says when the section that is current is registered by nobody. */
 const NO_SECTIONS = "No settings sections.";
 
@@ -80,9 +82,15 @@ const MOVED: readonly {
 
 /** What the mounted editor is told to do by things only its host can do. */
 export interface SettingsPaneOptions {
+  /** The region the home is stamped with: `pane.<id>/settings`. */
+  region: string;
+  /** Where the Back control goes, as its text says it ("Back to Design"). Read on every draw. */
+  backLabel: () => string;
+  /** The Back control: leave Settings for the workspace it was opened from. */
+  back: () => void;
   /**
-   * A Moved footnote's button: close the dialog and go to the named workspace, and to the named
-   * Inspector tab or Styles view there when the row names one.
+   * A Moved footnote's button: go to the named workspace, and to the named Inspector tab or Styles
+   * view there when the row names one.
    */
   openMoved: (
     workspace: WorkspaceId,
@@ -96,15 +104,10 @@ export interface SettingsPaneOptions {
 export interface SettingsPaneMount {
   /** Settles once the columns are mounted and the current section has been drawn once. */
   ready: Promise<void>;
-  /** Put the keyboard on the current section's row. */
-  focusActive: () => void;
-  /**
-   * Stop following the section registry while the dialog is closed. The editor stays built; a
-   * section registering or a project closing in the meantime is caught up on by {@link resume}.
-   */
-  suspend: () => void;
-  /** Follow the registry again and redraw the current section: the dialog is being shown again. */
-  resume: () => void;
+  /** Put the keyboard on the current section's row. Settles once it has moved. */
+  focusActive: () => Promise<void>;
+  /** Whether the home still stands in the stage it was mounted into. */
+  attached: () => boolean;
   /** Take the editor down and unsubscribe. Idempotent. */
   dispose: () => void;
 }
@@ -122,14 +125,16 @@ function movedRow(value: string): (typeof MOVED)[number] | null {
 /**
  * Everything the document draws, decided here so the document decides nothing.
  *
+ * @param {SettingsPaneOptions} options The host's region and Back control
  * @param {string} failure The current section's failure sentence, or the empty string
  * @returns {SettingsPaneValues}
  */
-function values(failure: string): SettingsPaneValues {
+function values(options: SettingsPaneOptions, failure: string): SettingsPaneValues {
   const active = settingsDocumentSection();
   const grouped = groupedSettingsSections();
   return {
     active,
+    backLabel: options.backLabel(),
     activeTabId: tabIdFor(active),
     empty: NO_SECTIONS,
     failure,
@@ -146,6 +151,7 @@ function values(failure: string): SettingsPaneValues {
       titleId: `settings-group-${group.id}`,
     })),
     hasSection: settingsSection(active) !== undefined,
+    heading: HEADING,
     // The section's own sentence when it has one, its group's otherwise.
     intro:
       settingsSection(active)?.intro ||
@@ -161,11 +167,12 @@ function values(failure: string): SettingsPaneValues {
         workspace: row.workspace,
       };
     }),
+    region: options.region,
   };
 }
 
 /**
- * Mount the editor into `host`, the settings dialog's pane slot, and keep it current.
+ * Mount the editor into `host`, a pane's stage, and keep it current until it is disposed.
  *
  * It subscribes to the section registry and to the chosen section, so an extension's section
  * appearing a tick later redraws the nav, and a deep link to an entry inside the section already on
@@ -198,7 +205,10 @@ export function mountSettingsPane(
   /** Counts renders, so a late rejection from a superseded one cannot overwrite a newer answer. */
   let generation = 0;
 
-  const surface: SettingsPaneHandle = mountSettingsPaneSurface(host, values(failure), {
+  const surface: SettingsPaneHandle = mountSettingsPaneSurface(host, values(options, failure), {
+    back: () => {
+      options.back();
+    },
     openMoved: (workspace: string) => {
       const target = movedRow(workspace);
       if (target !== null) {
@@ -217,7 +227,7 @@ export function mountSettingsPane(
     }
     const label = settingsSection(key)?.label ?? key;
     failure = `Could not show ${label}: ${reason}`;
-    surface.update(values(failure));
+    surface.update(values(options, failure));
   }
 
   /**
@@ -237,7 +247,7 @@ export function mountSettingsPane(
       rendered = null;
     }
     if (!island || (!force && rendered === active)) {
-      surface.update(values(failure));
+      surface.update(values(options, failure));
       return;
     }
     /* Read BEFORE the write: whether the section is changing is what decides the host, and
@@ -245,10 +255,10 @@ export function mountSettingsPane(
     const changed = rendered !== active;
     rendered = active;
     failure = "";
-    surface.update(values(failure));
+    surface.update(values(options, failure));
     const section = settingsSection(active);
     if (!section) {
-      /* Every section unregistered at once: a project closing while the dialog is open. The
+      /* Every section unregistered at once: a project closing while Settings is on screen. The
          document says so itself (`hasSection`), and the island is emptied so a renderer's leftovers
          do not sit under the sentence explaining that there is nothing to draw. */
       sectionHost = null;
@@ -276,12 +286,9 @@ export function mountSettingsPane(
     }
   }
 
-  const follow = (): (() => void) =>
-    onSettingsDocumentChanged(() => {
-      draw(true);
-    });
-  /** The registry subscription, or null while the dialog is closed. */
-  let off: (() => void) | null = follow();
+  const off = onSettingsDocumentChanged(() => {
+    draw(true);
+  });
   /* The island does not exist until the mount lands, so the first pass that reaches a section
      renderer is this one. */
   const ready = surface.ready.then(() => {
@@ -289,37 +296,16 @@ export function mountSettingsPane(
   });
 
   return {
+    attached: () => surface.attached(),
     dispose() {
       if (disposed) {
         return;
       }
       disposed = true;
-      off?.();
-      off = null;
+      off();
       surface.dispose();
     },
-    focusActive: () => {
-      surface.focusActive();
-    },
+    focusActive: () => surface.focusActive(),
     ready,
-    resume() {
-      if (disposed || off !== null) {
-        return;
-      }
-      off = follow();
-      /* Redrawn rather than trusted: anything may have moved while it was closed (a section
-         registered, the project closed or changed, the configuration edited in Styles). Into a
-         FRESH host, as every open drew into when each one built its own frame: several sections
-         keep their form state (a half-typed entry, a failed save's error) in a WeakMap keyed on
-         the host they were given, and an open is a new visit, so none of that may come back from
-         the last one, or from another project's. Only a redraw WHILE open keeps the host, which is
-         what keeps the caret in the field being typed in. */
-      sectionHost = null;
-      draw(true);
-    },
-    suspend() {
-      off?.();
-      off = null;
-    },
   };
 }

package/src/panels/tab-strip.ts

@@ -83,6 +83,7 @@ import { openMenu } from "../surfaces/menu";
 import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
 import { saveFile } from "../files/file-ops";
 import { collabReadOnly } from "../collab/collab-session";
+import { imageEditorDirty } from "../media/image-editor";
 import { collabState } from "../collab/collab-state";
 import { elementAtPoint, rectOf } from "../utils/geometry";
 import { resolveRegion } from "../ui/regions";
@@ -255,6 +256,8 @@ export function mount(host: HTMLElement) {
         // A tab's workspace follows its editor (`project.json` is Styles' in its stylebook only).
         void tab.session.ui.canvasMode;
         void tab.doc.dirty;
+        // An image edit is the tab's unsaved work too (§9.5), held beside the document, not in it.
+        void imageEditorDirty(tab);
         void tab.documentPath;
         void tab.pinned;
         void tab.preview;
@@ -689,7 +692,7 @@ function chipView(
   const pill = entryDraftPill(tab);
   return [
     {
-      dirty: tab.doc.dirty,
+      dirty: tab.doc.dirty || imageEditorDirty(tab),
       draft: pill?.draft ?? false,
       index,
       key: id,
@@ -1336,11 +1339,17 @@ export function tabLabel(tab: Tab): string {
  * buffer rather than resyncing over a half-typed heading), and that text exists nowhere else.
  * {@link tabBufferUnsaved} is that residue, and it is the user's own typing by construction.
  *
+ * **And an image tab's unsaved work is not in its document at all.** A media tab's document is a
+ * stub; an Image editor edit (§9.5) is a recipe held beside it, so it is a third source of dirt,
+ * and it takes the residue's side of the peer-count gate for the residue's reason: a recipe has
+ * never been published, mirrored or written, so no peer focused on the path holds a copy of it.
+ *
  * @param {Tab} tab
  */
 export function shouldWarnOnClose(tab: Tab): boolean {
   const residue = tabBufferUnsaved(tab);
-  if (!tab.doc.dirty && !residue) {
+  const image = imageEditorDirty(tab);
+  if (!tab.doc.dirty && !residue && !image) {
     return false;
   }
   const state = collabState(tab);
@@ -1361,7 +1370,7 @@ export function shouldWarnOnClose(tab: Tab): boolean {
      lock holder is by definition a peer focused on this path, so the busier the room got, the
      quieter the close became. Asked before the peer count rather than after, because the peer count
      has no jurisdiction over text the room has never been told about. */
-  if (residue) {
+  if (residue || image) {
     return true;
   }
   const peersHere = state.peers.filter((p) => p.state.focusedPath === tab.documentPath);

package/src/services/ai-import-tools.ts

@@ -27,7 +27,7 @@ import { IMPORT_MAX_PAGES } from "@jxsuite/protocol";
 import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import { workspace } from "../workspace/workspace";
-import { getBaseUrl, getOpenAiKey } from "./ai-settings";
+import { getAiProvider, getBaseUrl, getOpenAiCompatKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { MAX_IMPORT_DEPTH, clearPendingImportBrief, pendingImportBrief } from "./import-seed";
 import type { ImportBrief } from "./import-seed";
@@ -431,8 +431,11 @@ export function registerImportTools(
         };
         callSignal.addEventListener("abort", stopRun, { once: true });
 
-        const apiKey = getOpenAiKey();
-        const baseUrl = getBaseUrl();
+        /* The importer's component naming speaks only the OpenAI-compatible wire, so a Claude key
+           and its endpoint are withheld rather than sent to an OpenAI client; the import then names
+           components heuristically, as it does with no key at all. */
+        const apiKey = getOpenAiCompatKey();
+        const baseUrl = getAiProvider() === "openai-compat" ? getBaseUrl() : "";
         const model = brief?.model || preferredModel();
 
         const breakpoints = breakpointPolicyFor(

package/src/services/ai-models.ts

@@ -10,12 +10,13 @@
  * @license MIT
  */
 
-import type { AiCredentials } from "@jxsuite/ai/streaming-client";
+import { AI_PROVIDER_HEADER } from "@jxsuite/ai/streaming-client";
+import type { AiCredentials, AiProviderFamily } from "@jxsuite/ai/streaming-client";
 import type { AiModelsResponse, OfferedAction } from "@jxsuite/protocol";
 import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import { offeredActions } from "../platform-errors";
-import { getBaseUrl, getOpenAiKey, hasOpenAiKey, storedModel } from "./ai-settings";
+import { getAiProvider, getBaseUrl, getOpenAiKey, hasOpenAiKey, storedModel } from "./ai-settings";
 import { SETTINGS } from "./settings/definitions";
 import { onSettingsChanged } from "./settings/kernel";
 
@@ -42,19 +43,32 @@ export interface AiModel {
  */
 export type { AiCredentials } from "@jxsuite/ai/streaming-client";
 
+/**
+ * The credentials a model list belongs to, and the family they belong to. `provider` absent is the
+ * OpenAI-compatible default: the same key and endpoint list different catalogues under different
+ * families, so the family is part of what a list was listed under.
+ */
+export interface AiConnection extends AiCredentials {
+  provider?: AiProviderFamily;
+}
+
+/** The model a Claude sender falls back to when neither the user nor the backend chose one. */
+export const ANTHROPIC_DEFAULT_MODEL = "claude-opus-5-5";
+
 /** The credentials the app is configured with right now. */
-export function aiConnection(): AiCredentials {
-  return { apiKey: getOpenAiKey(), baseUrl: getBaseUrl() };
+export function aiConnection(): AiConnection {
+  return { apiKey: getOpenAiKey(), baseUrl: getBaseUrl(), provider: getAiProvider() };
 }
 
 /**
- * An opaque identity for a credential pair.
+ * An opaque identity for a connection.
  *
  * NUL-joined rather than concatenated: a key ending in the base URL's first characters would
  * otherwise be indistinguishable from a shorter key and a longer URL.
  */
-function fingerprint(credentials: AiCredentials): string {
-  return `${credentials.apiKey}\u0000${credentials.baseUrl}`;
+function fingerprint(credentials: AiConnection): string {
+  const family = credentials.provider ?? "openai-compat";
+  return `${credentials.apiKey}\u0000${credentials.baseUrl}\u0000${family}`;
 }
 
 let cache: AiModel[] | null = null;
@@ -77,6 +91,8 @@ let proxyCode: AiModelsResponse["code"];
 let proxyModelsError = "";
 /** What an `action_required` probe offered; null for every other answer. */
 let proxyAction: ProxyActionOffer | null = null;
+/** The families the last probe said the chat route reaches; the default alone until one says more. */
+let proxyProviders: AiProviderFamily[] = ["openai-compat"];
 
 /** What a managed backend says the assistant needs first, in the backend's own words. */
 export interface ProxyActionOffer {
@@ -126,6 +142,7 @@ export function resetModelCache() {
   proxyCode = undefined;
   proxyModelsError = "";
   proxyAction = null;
+  proxyProviders = ["openai-compat"];
   /* The probe's result IS the flags above. Clearing them while keeping the settled promise
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
@@ -137,6 +154,7 @@ export function resetModelCache() {
 const CONNECTION_KEYS = new Set<string>([
   SETTINGS.aiOpenAiKey.key,
   SETTINGS.aiBaseUrl.key,
+  SETTINGS.aiProvider.key,
   SETTINGS.cfToken.key,
   SETTINGS.cfAccountId.key,
 ]);
@@ -151,7 +169,7 @@ onSettingsChanged((keys) => {
  * The cached list, if it was listed under `credentials`. Null when it was not, or when there is
  * none — a caller must not show one provider's catalogue for another's key.
  */
-export function cachedModels(credentials: AiCredentials): AiModel[] | null {
+export function cachedModels(credentials: AiConnection): AiModel[] | null {
   return cache && cacheKey === fingerprint(credentials) ? cache : null;
 }
 
@@ -294,6 +312,18 @@ export function proxyActionOffer(): ProxyActionOffer | null {
   return proxyAction;
 }
 
+/**
+ * The provider families the backend's chat route reaches with a caller's key, as the last probe
+ * reported them. A backend that says nothing reaches the OpenAI-compatible family alone, and a
+ * surface **MUST NOT** offer it another: such a backend forwards every key to an OpenAI-compatible
+ * endpoint (specs/ai.md §2.6).
+ *
+ * @returns {readonly AiProviderFamily[]}
+ */
+export function backendProviders(): readonly AiProviderFamily[] {
+  return proxyProviders;
+}
+
 /** The proxy's preferred model id ("" when it does not declare one). */
 export function getProxyDefaultModel(): string {
   return proxyDefaultModel;
@@ -307,13 +337,15 @@ export function getProxyDefaultModel(): string {
  * that value was fetched, stored and never read — so a user who had chosen nothing got the
  * hardcoded `"gpt-4o"`, which Workers AI does not serve. Asking the backend what it prefers before
  * falling back to a name invented here is the difference between working and a 404 on the first
- * message.
+ * message. The last term follows the family for the same reason: Anthropic serves no `gpt-4o`.
  *
  * It lives here rather than in `ai-settings.ts` because only this module knows what the proxy said,
  * and `ai-settings` must not import it — this module already imports `ai-settings`.
  */
 export function preferredModel(): string {
-  return storedModel() || getProxyDefaultModel() || SETTINGS.aiModel.default;
+  const fallback =
+    getAiProvider() === "anthropic" ? ANTHROPIC_DEFAULT_MODEL : SETTINGS.aiModel.default;
+  return storedModel() || getProxyDefaultModel() || fallback;
 }
 
 /**
@@ -345,6 +377,23 @@ export function siblingRoute(chatUrl: string, segment: string): string {
   return /^https?:/i.test(chatUrl) ? url.href : `${url.pathname}${url.search}`;
 }
 
+/**
+ * The families a probe listed, keeping only the ones this client can speak. The answer is the
+ * backend's JSON, so an entry its type calls a family may be any string; a probe that lists none is
+ * a backend that predates the member, which reaches the default family alone.
+ *
+ * @param {readonly string[] | undefined} listed - The probe's `providers`, as sent
+ * @returns {AiProviderFamily[]}
+ */
+function providersOf(listed: readonly string[] | undefined): AiProviderFamily[] {
+  if (listed === undefined) {
+    return ["openai-compat"];
+  }
+  return listed.filter((family): family is AiProviderFamily =>
+    ["anthropic", "openai-compat"].includes(family),
+  );
+}
+
 /**
  * Fetch the models available through the AI proxy. Returns the cached list when present unless
  * `force` is set; throws on HTTP/network failure (callers surface the error).
@@ -354,7 +403,7 @@ export function siblingRoute(chatUrl: string, segment: string): string {
  * @returns {Promise<AiModel[]>}
  */
 export async function fetchAvailableModels(
-  opts: { credentials?: AiCredentials; force?: boolean } = {},
+  opts: { credentials?: AiConnection; force?: boolean } = {},
 ): Promise<AiModel[]> {
   /* Resolve the credentials BEFORE consulting the cache. Checking the cache first is what let a
      list fetched under one provider be handed to a caller asking about another. */
@@ -374,6 +423,10 @@ export async function fetchAvailableModels(
   if (credentials.baseUrl) {
     headers["X-Api-Base-URL"] = credentials.baseUrl;
   }
+  // The default family says nothing, as the chat request does (`createProxyStreamingClient`).
+  if (credentials.provider === "anthropic") {
+    headers[AI_PROVIDER_HEADER] = credentials.provider;
+  }
 
   const resp = await fetch(modelsUrl, { headers });
   if (!resp.ok) {
@@ -390,6 +443,7 @@ export async function fetchAvailableModels(
   proxyCode = data.code;
   proxyModelsError = data.upstreamError !== undefined ? (data.upstreamMessage ?? "") : "";
   proxyAction = null;
+  proxyProviders = providersOf(data.providers);
   if (data.code === "action_required") {
     const offer: ProxyActionOffer = { actions: offeredActions(data.actions) };
     if (isString(data.detail) && data.detail) {

package/src/services/ai-settings.ts

@@ -19,6 +19,7 @@
  * @license MIT
  */
 
+import type { AiProviderFamily } from "@jxsuite/ai/streaming-client";
 import { SETTINGS } from "./settings/definitions";
 import type { SettingDefinition } from "./settings/definitions";
 import {
@@ -58,6 +59,29 @@ export function getBaseUrl() {
   return readStoredSetting(SETTINGS.aiBaseUrl);
 }
 
+/**
+ * The wire the stored key belongs to (specs/ai.md §2.6): `"anthropic"` for a Claude key, and the
+ * OpenAI-compatible default for anything else, including nothing stored.
+ *
+ * @returns {AiProviderFamily}
+ */
+export function getAiProvider(): AiProviderFamily {
+  return readStoredSetting(SETTINGS.aiProvider) === "anthropic" ? "anthropic" : "openai-compat";
+}
+
+/**
+ * The stored key when it is an OpenAI-compatible one, and `""` when it belongs to another family.
+ *
+ * For the paths that only speak the OpenAI-compatible wire, such as the site importer's component
+ * naming: handing them a Claude key would send it to an OpenAI endpoint, which is the one thing a
+ * key must never do.
+ *
+ * @returns {string}
+ */
+export function getOpenAiCompatKey(): string {
+  return getAiProvider() === "openai-compat" ? getOpenAiKey() : "";
+}
+
 // ─── Model selection ────────────────────────────────────────────────────────
 
 /**
@@ -84,11 +108,25 @@ export function setModel(modelId: string) {
   setSetting(SETTINGS.aiModel, modelId || "");
 }
 
-/** The provider's three values together — what a credentials form drafts and what Save stores. */
+/**
+ * The provider's values together: what a credentials form drafts and what Save stores. `provider`
+ * absent is the OpenAI-compatible default, which is what every caller before it meant.
+ */
 export interface AiProvider {
   apiKey: string;
   baseUrl: string;
   model: string;
+  provider?: AiProviderFamily;
+}
+
+/**
+ * A family as the store holds it: `"anthropic"`, or blank for the default.
+ *
+ * @param {AiProviderFamily | undefined} family
+ * @returns {string}
+ */
+function storedFamily(family: AiProviderFamily | undefined): string {
+  return family === "anthropic" ? "anthropic" : "";
 }
 
 /**
@@ -105,6 +143,7 @@ export function saveAiProvider(provider: AiProvider) {
     [SETTINGS.aiOpenAiKey, provider.apiKey],
     [SETTINGS.aiBaseUrl, provider.baseUrl],
     [SETTINGS.aiModel, provider.model],
+    [SETTINGS.aiProvider, storedFamily(provider.provider)],
   ]);
 }
 
@@ -127,13 +166,14 @@ export function saveAiProvider(provider: AiProvider) {
  * sentence above always claimed to be making.
  *
  * @param {AiProvider} provider The drafts.
- * @returns {boolean} `true` when at least one of the three would move.
+ * @returns {boolean} `true` when at least one of the values would move.
  */
 export function aiProviderDiffers(provider: AiProvider): boolean {
   return (
     !storedEquals(SETTINGS.aiOpenAiKey, provider.apiKey, getOpenAiKey()) ||
     !storedEquals(SETTINGS.aiBaseUrl, provider.baseUrl, getBaseUrl()) ||
-    !storedEquals(SETTINGS.aiModel, provider.model, storedModel())
+    !storedEquals(SETTINGS.aiModel, provider.model, storedModel()) ||
+    storedFamily(provider.provider) !== storedFamily(getAiProvider())
   );
 }
 
@@ -153,11 +193,11 @@ export function storedEquals(
 }
 
 /**
- * Forget the provider entirely — key, endpoint and model.
+ * Forget the provider entirely — key, endpoint, model and family.
  *
  * The one deletion path, and the one the Accounts list's Disconnect uses. Deliberately all three
  * together: a key with an orphaned endpoint is a state no surface knows how to describe.
  */
 export function clearAiProvider() {
-  clearSettings([SETTINGS.aiOpenAiKey, SETTINGS.aiBaseUrl, SETTINGS.aiModel]);
+  clearSettings([SETTINGS.aiOpenAiKey, SETTINGS.aiBaseUrl, SETTINGS.aiModel, SETTINGS.aiProvider]);
 }

package/src/services/document-assistant.ts

@@ -34,7 +34,7 @@ import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
 import { buildSystemPrompt } from "./ai-system-prompt";
 import type { ExtensionCatalogSummary } from "./ai-system-prompt";
-import { getBaseUrl, getOpenAiKey } from "./ai-settings";
+import { getAiProvider, getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
@@ -329,8 +329,11 @@ export function createDocumentAssistant() {
         model: chatState.model,
         // Sent as X-Api-Key; the proxy falls back to the server's OPENAI_API_KEY when empty.
         apiKey: getOpenAiKey() || undefined,
-        // Optional OpenAI-compatible endpoint override; empty uses the proxy default.
+        // Optional endpoint override; empty uses the proxy default for the family.
         baseUrl: getBaseUrl() || undefined,
+        /* The family the key belongs to (specs/ai.md §2.6), named only when it is not the default,
+           so an OpenAI-compatible send is the one it always was. */
+        provider: getAiProvider() === "anthropic" ? "anthropic" : undefined,
         /* The persisted conversation, so the backend can keep its rounds on one warm prompt cache.
            Sent to the backend only, which hashes it before any provider sees it (specs/ai.md §2.5). */
         sessionId,