@jxsuite/studio 10.0.0 → 10.2.0

package/src/publish/publish-changes.ts

@@ -10,8 +10,16 @@
  * a host that opens pull requests (`createPullRequest`); on one that does not (the dev server and
  * the desktop app today) it is drawn disabled with that sentence rather than falling back to a
  * branch push that opens nothing. On a host whose branches are sessions (`gitHosted`, the cloud) a
- * branch cannot be made and committed to mid-flow, so review there commits to the session's own
- * branch and opens the pull request from it, and the destination's note says so.
+ * branch cannot be checked out mid-flow, so review there commits to the session's own branch and
+ * opens the pull request from it; on the default branch, where every commit is live, the change set
+ * is committed as a branch of its own instead (`gitCommitBranch`), and the destination's note says
+ * which.
+ *
+ * **A remote that moved is not a dead end.** On such a host a commit the remote's newer changes
+ * overlap is refused with the files they share ({@link remoteConflictsOf}). The author is then
+ * offered the same branch of its own: {@link publishAsBranch} commits the change set onto the base
+ * it was edited against, which cannot conflict, and opens a pull request into the branch that
+ * moved, where GitHub reconciles the two.
  *
  * **Every word a control shows is decided here**, so the workspace and the dialog cannot disagree
  * about what a button does: {@link destinationChoices}, {@link publishLabel} and
@@ -24,6 +32,8 @@
 import { errorMessage } from "@jxsuite/schema/parse";
 import { flushAllCollab } from "../collab/collab-session";
 import { getPlatform, hasPlatform } from "../platform";
+import { remoteConflictsOf } from "../platform-errors";
+import { showPromptDialog } from "../ui/layers";
 import { notify } from "../services/notify";
 import { shell } from "../shell";
 import { projectState } from "../store";
@@ -71,6 +81,21 @@ export function reviewBranchName(summary: string): string {
   return `studio/${slug.replace(/-$/, "") || "changes"}`;
 }
 
+/**
+ * Whether this host can commit a change set as a branch of its own without checking it out
+ * (`StudioPlatform.gitCommitBranch`): what lets the cloud send a review from the default branch and
+ * publish a change set the remote has conflicted with.
+ */
+export function platformCommitsBranches(): boolean {
+  return hasPlatform() && getPlatform().gitCommitBranch !== undefined;
+}
+
+/** Whether review on this host commits a branch of its own rather than the session's branch. */
+function reviewBranchesOff(): boolean {
+  const base = defaultBranch();
+  return platformHostsGit() && platformCommitsBranches() && base !== "" && currentBranch() === base;
+}
+
 /** One destination, as a radio card draws it. */
 export interface DestinationChoice {
   value: PublishDestination;
@@ -108,6 +133,9 @@ export function reviewRefusal(): string {
        publish by accident. */
     const base = defaultBranch();
     const branch = currentBranch();
+    if (reviewBranchesOff()) {
+      return "";
+    }
     if (!base || !branch || branch === base) {
       return (
         `Every commit to ${base || "the default branch"} on this host is live. Create a branch ` +
@@ -140,14 +168,17 @@ function liveNote(): string {
 /** What Send for review does, said before it runs. */
 function reviewNote(): string {
   const branch = currentBranch() || "the current branch";
+  const summary = shell.git.commitMessage.trim();
+  const head = summary ? reviewBranchName(summary) : "a new studio/ branch";
+  if (reviewBranchesOff()) {
+    return `Saves to ${head} on GitHub and opens a pull request into ${branch}.`;
+  }
   if (platformHostsGit()) {
     return (
       `Commits to ${branch} and opens a pull request from it into ` +
       `${defaultBranch() || "the default branch"}.`
     );
   }
-  const summary = shell.git.commitMessage.trim();
-  const head = summary ? reviewBranchName(summary) : "a new studio/ branch";
   return `Saves to ${head}, pushes it and opens a pull request into ${branch}.`;
 }
 
@@ -424,6 +455,16 @@ export async function publishChanges(
     await refreshGitStatus();
     return shipped;
   } catch (error) {
+    const conflicts = committed ? null : remoteConflictsOf(error);
+    if (conflicts && platformCommitsBranches()) {
+      shell.git.loading = false;
+      if (await publishAsBranch(message, conflicts)) {
+        return true;
+      }
+      // Declined: the refusal still stands, and it is what the author must read.
+      shell.git.error ??= errorMessage(error);
+      return false;
+    }
     shell.git.error = errorMessage(error);
     shell.git.loading = false;
     // A push that failed after the commit landed must not offer the same summary again.
@@ -434,6 +475,89 @@ export async function publishChanges(
   }
 }
 
+/** Up to three paths, then how many more: what a sentence can name of a list of files. */
+function namePaths(paths: readonly string[]): string {
+  const shown = paths.slice(0, 3).join(", ");
+  return paths.length > 3 ? `${shown} and ${paths.length - 3} more` : shown;
+}
+
+/**
+ * Offer to publish a change set the remote has conflicted with as a branch of its own, and do it.
+ *
+ * Asked, never assumed: the author named a destination, and this is a different one. The dialog
+ * says which files collided and what will happen, and the branch name it proposes is the one Send
+ * for review would use, editable. Confirming commits the change set onto the base it was edited
+ * against (`gitCommitBranch`, which cannot conflict), opens a pull request from it into the branch
+ * that moved, and pulls that branch up to date now that the colliding changes have left it.
+ * Cancelling puts the summary back, as any publish that never committed does.
+ *
+ * @param message The summary the refused commit was made with.
+ * @param conflicts The files the remote changed that this change set changes too.
+ * @returns Whether the change set reached the new branch.
+ */
+export async function publishAsBranch(
+  message: string,
+  conflicts: readonly string[],
+): Promise<boolean> {
+  const plat = getPlatform();
+  const commitBranch = plat.gitCommitBranch;
+  if (!commitBranch) {
+    return false;
+  }
+  const current = currentBranch() || "this branch";
+  const count = conflicts.length === 1 ? "1 file" : `${conflicts.length} files`;
+  const name = await showPromptDialog("Publish to a New Branch", {
+    confirmLabel: "Publish to branch",
+    message:
+      `${current} changed on GitHub after these edits began, and ${count} changed on both sides ` +
+      `(${namePaths(conflicts)}). Publish your changes to a branch of their own instead, and a ` +
+      `pull request will bring them into ${current}.`,
+    value: reviewBranchName(message),
+    validate: (value) => (value.trim() ? "" : "Enter a branch name."),
+  });
+  if (!name) {
+    restoreSummary(message);
+    return false;
+  }
+  shell.git.loading = true;
+  shell.git.error = null;
+  let committed = false;
+  try {
+    const result = await commitBranch({ branch: name, message });
+    committed = true;
+    const open = plat.createPullRequest;
+    const base = currentBranch();
+    const pr = open && base ? await open({ base, head: result.branch, title: message }) : null;
+    if (pr) {
+      shell.publish.review.number = pr.number;
+      shell.publish.review.url = pr.url;
+    }
+    notify.success(
+      pr
+        ? `Published to ${result.branch}. Pull request #${pr.number} brings it into ${base}.`
+        : `Published to ${result.branch}.`,
+      { detail: pr?.url ?? "", key: "publish.branch", source: "Publish" },
+    );
+    /* The colliding edits have left this session, so it can fast-forward to the remote now. A
+       pull that still cannot (another collaborator's edit overlaps too) is not this publish's
+       failure: the status says the branch is behind, and Pull says why. */
+    try {
+      await plat.gitPull();
+    } catch {
+      // Reported by the next Pull, where it can be acted on.
+    }
+    await refreshGitStatus();
+    return true;
+  } catch (error) {
+    shell.git.error = errorMessage(error);
+    shell.git.loading = false;
+    if (!committed) {
+      restoreSummary(message);
+    }
+    return false;
+  }
+}
+
 /** What a pull request is opened with: its title, and the branches when the flow chose them. */
 interface PullRequestRequest {
   title: string;
@@ -454,6 +578,14 @@ async function commitForReview(
   message: string,
   onCommitted: () => void,
 ): Promise<PullRequestRequest> {
+  if (reviewBranchesOff() && plat.gitCommitBranch) {
+    /* Every commit to the default branch here is live, so the change set goes to a branch of its
+       own, parented on the session's base, and leaves the session: it is the pull request's now. */
+    const base = currentBranch();
+    const { branch } = await plat.gitCommitBranch({ branch: reviewBranchName(message), message });
+    onCommitted();
+    return { base, head: branch, title: message };
+  }
   if (platformHostsGit()) {
     // `reviewRefusal` has already refused the default branch, so this commit is not a live one.
     await plat.gitCommit(message);

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,

package/src/services/settings/definitions.ts

@@ -60,6 +60,15 @@ function normalizeBaseUrl(raw: string): string {
   return raw.trim().replace(/\/+$/, "");
 }
 
+/**
+ * The provider family, stored only when it is not the default: `"anthropic"`, or `""` for the
+ * OpenAI-compatible wire every install had before the setting existed. Anything else reads as the
+ * default, so a hand-edited value can never send a key to a family nobody chose.
+ */
+function normalizeProvider(raw: string): string {
+  return raw.trim().toLowerCase() === "anthropic" ? "anthropic" : "";
+}
+
 /** Trim. Credentials are pasted, and a paste carries whitespace. */
 function trimmed(raw: string): string {
   return raw.trim();
@@ -91,6 +100,16 @@ export const SETTINGS = {
     scope: "user",
     secret: true,
   },
+  /**
+   * Which wire the key belongs to (specs/ai.md §2.6). Blank is the OpenAI-compatible default, so an
+   * install that predates the setting keeps the provider it already had.
+   */
+  aiProvider: {
+    default: "",
+    key: "jx.ai.provider",
+    normalize: normalizeProvider,
+    scope: "user",
+  },
   /**
    * `"gpt-4o"` is what a sender falls back to, NOT a stored choice. A surface that writes back must
    * read through `readStoredSetting`, or it persists a model the user never picked.

package/src/settings/contributed-section.ts

@@ -49,7 +49,8 @@ import { resolveContextPointer } from "../services/context-resolver";
 import { deriveSecretEnvName } from "../services/data-service";
 import { validateProjectConfig } from "../services/jx-validate";
 import { notify } from "../services/notify";
-import { SETTINGS_DIALOG_REGION } from "../surfaces/settings-dialog";
+import { REGION_ATTR } from "../ui/regions";
+import { settingsRegion } from "./settings-workspace";
 import { mountContributedSurface } from "../surfaces/settings-contributed";
 
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
@@ -371,15 +372,23 @@ function sectionValue(key: string): JsonObject | null {
 // ─── Per-container mount ──────────────────────────────────────────────────────
 
 /**
- * A region under the settings dialog, which is where a contributed section is drawn (§17.1): its
- * entry rows and its entry editor are named under `overlay.dialog:settings`, so a shot can crop one
+ * A region under the Settings home, which is where a contributed section is drawn (§17.1): its
+ * entry rows and its entry editor are named under `pane.<id>/settings`, so a shot can crop one
  * without a selector.
  *
+ * The home is per pane, and a renderer is handed a container and nothing else, so the base is READ
+ * off the nearest region around the container, which is the home's own: the id is derived from what
+ * is on screen, as every region is (`ui/regions.ts`). A container not yet in a home names the
+ * primary pane's.
+ *
+ * @param {HTMLElement} container The element the section was rendered into
  * @param {string} part
  * @returns {string}
  */
-function sectionRegion(part: string): string {
-  return `${SETTINGS_DIALOG_REGION}/${part}`;
+function sectionRegion(container: HTMLElement, part: string): string {
+  const base =
+    container.closest(`[${REGION_ATTR}]`)?.getAttribute(REGION_ATTR) ?? settingsRegion("primary");
+  return `${base}/${part}`;
 }
 
 /** One mounted section: its document, its two island hosts, and what it was last asked to draw. */
@@ -455,7 +464,7 @@ function project(record: SectionMount): ContributedView {
   const sectionKey = contribution.key;
   const title = contribution.title ?? sectionKey;
   const actionsState = opts.actions ? "slot" : "none";
-  const editorRegion = sectionRegion("editor");
+  const editorRegion = sectionRegion(record.container, "editor");
   const words = entryWords(contribution.settings.entry?.noun);
 
   if ((contribution.settings.layout ?? "form") !== "map") {
@@ -483,7 +492,7 @@ function project(record: SectionMount): ContributedView {
     editorState: editing ? "editing" : "empty",
     entries: Object.keys(entries).map((name) => ({
       key: name,
-      region: sectionRegion(`entry:${name}`),
+      region: sectionRegion(record.container, `entry:${name}`),
       selected: name === selected,
     })),
     entryName: record.echo ?? (editing ? selected : ""),

package/src/settings/css-vars-editor.ts

@@ -386,9 +386,9 @@ function addOverride(container: HTMLElement, token: string, ctx: string): void {
  * per token are defined.
  *
  * Through the command rather than by writing the registry's section: the editor is hosted outside
- * Settings (the Styles workspace's Variables view), so selecting a section of a dialog that is not
- * open would change nothing the reader can see. A refusal is filed under "Styles", the workspace
- * the editor lives in, as the Variables view's own button files it.
+ * Settings (the Styles workspace's Variables view), so selecting a section of a workspace that is
+ * not on screen would change nothing the reader can see. A refusal is filed under "Styles", the
+ * workspace the editor lives in, as the Variables view's own button files it.
  */
 function openContextsSection(): void {
   void runActiveReported("settings.open", { section: "contexts" }, "Styles");
@@ -418,7 +418,7 @@ function actions(container: HTMLElement): CssVarsActions {
        * appended `'--dark': '(prefers-color-scheme: dark)'` to `$media` without ever using the word
        * breakpoint, which made this form the fourth and least discoverable definition site for a
        * map whose other three lived in the wizard, Overview and Properties › Media. It goes there
-       * through `settings.open`, so the dialog opens on Contexts however this editor is hosted.
+       * through `settings.open`, so Settings opens on Contexts however this editor is hosted.
        */
       manageContexts: () => {
         openContextsSection();

package/src/settings/general-settings.ts

@@ -22,7 +22,6 @@ import { projectState } from "../store";
 import { updateSiteConfig } from "../site-context";
 import { activeRegistry } from "../commands/active-registry";
 import { runActiveReported } from "../commands/run-reported";
-import { closeSettingsDialog } from "./settings-dialog";
 import { getPlatform } from "../platform";
 import { mountOverviewSurface } from "../surfaces/settings-overview";
 import { previewAssetSrcFor } from "../canvas/asset-refs";
@@ -265,11 +264,9 @@ function actions(container: HTMLElement): OverviewActions {
      * says how to get there. This used to write `session.ui.canvasMode` here directly — a second
      * implementation of a capability, `studio-ui-guidelines.md` §12.5's defect in miniature: the
      * button and the command could disagree about what "open Project Styles" means, and only one of
-     * them was reachable by name. Overview is drawn in the settings dialog, so the dialog closes
-     * first: left up, it would cover the workspace the reader just asked for.
+     * them was reachable by name.
      */
     openStyles: () => {
-      closeSettingsDialog();
       void runActiveReported("view.setWorkspace", { workspace: "styles" }, "Settings");
     },
     setDescription: (value: string) => {