diff --git a/apps/desktop/src/main/__tests__/connections-ipc-main.test.ts b/apps/desktop/src/main/__tests__/connections-ipc-main.test.ts
index e0b2cd1585..5a97cb8d97 100644
--- a/apps/desktop/src/main/__tests__/connections-ipc-main.test.ts
+++ b/apps/desktop/src/main/__tests__/connections-ipc-main.test.ts
@@ -350,6 +350,76 @@ describe('connection IPC credential boundary', () => {
     assert.equal(persistedPatch?.baseUrl, 'https://chatgpt.com/backend-api/codex');
   });
 
+  test('create passes relay model profiles through to the store unchanged', async () => {
+    let persistedInput: CreateConnectionInput | undefined;
+    const handlers = registerHandlers({
+      connectionStore: {
+        create: async (input: CreateConnectionInput) => {
+          persistedInput = input;
+          return {
+            ...input,
+            defaultModel: 'my-reasoning-model',
+            enabled: true,
+            createdAt: 1,
+            updatedAt: 1,
+          };
+        },
+        remove: async () => {},
+      },
+    });
+
+    const create = handlers.get('connections:create');
+    assert.ok(create);
+    const relayModelProfiles = {
+      'my-reasoning-model': {
+        thinkingLevels: ['low', 'medium', 'high', 'max'],
+        vision: true,
+      },
+    } as const;
+    await create({}, {
+      slug: 'my-relay',
+      name: 'My Relay',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay.example/v1',
+      defaultModel: 'my-reasoning-model',
+      relayModelProfiles,
+    });
+    assert.deepEqual(persistedInput?.relayModelProfiles, relayModelProfiles);
+    assert.equal(persistedInput?.extras, undefined);
+  });
+
+  test('update passes relay model profiles through to the store unchanged', async () => {
+    let persistedPatch: UpdateConnectionInput | undefined;
+    const existing: LlmConnection = {
+      slug: 'my-relay',
+      name: 'My Relay',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay.example/v1',
+      defaultModel: 'my-reasoning-model',
+      enabled: true,
+      createdAt: 1,
+      updatedAt: 1,
+    };
+    const handlers = registerHandlers({
+      connectionStore: {
+        get: async () => existing,
+        update: async (_slug: string, patch: UpdateConnectionInput) => {
+          persistedPatch = patch;
+          return { ...existing, ...patch };
+        },
+      },
+    });
+
+    const update = handlers.get('connections:update');
+    assert.ok(update);
+    const relayModelProfiles = {
+      'my-reasoning-model': { thinkingLevels: ['low', 'high', 'max'] },
+    } as const;
+    await update({}, existing.slug, { relayModelProfiles });
+    assert.deepEqual(persistedPatch?.relayModelProfiles, relayModelProfiles);
+    assert.equal(persistedPatch?.extras, undefined);
+  });
+
   test('hasSecret uses the read-only credential probe', async () => {
     const connection = {
       slug: 'openai-codex',
diff --git a/apps/desktop/src/main/__tests__/relay-profile-draft.test.ts b/apps/desktop/src/main/__tests__/relay-profile-draft.test.ts
new file mode 100644
index 0000000000..6395e6c4c7
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/relay-profile-draft.test.ts
@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  relayProfileDraftReseedPlan,
+  relayProfileDraftSeed,
+} from '../../renderer/settings/relay-profile-draft.js';
+
+test('a clean draft reseeds on every reload of its own connection', () => {
+  assert.deepEqual(relayProfileDraftReseedPlan({ slug: 'relay-a', dirty: false }, 'relay-a'), {
+    reseed: true,
+    clearDirty: false,
+  });
+});
+
+test('a dirty draft survives same-connection reloads', () => {
+  assert.deepEqual(relayProfileDraftReseedPlan({ slug: 'relay-a', dirty: true }, 'relay-a'), {
+    reseed: false,
+    clearDirty: false,
+  });
+});
+
+test('a connection switch reseeds regardless of unsaved edits — and owns the result', () => {
+  // Dirty belongs to the slug that produced it: A's unsaved declarations
+  // must neither render under B nor be saved into B.
+  for (const dirty of [true, false]) {
+    assert.deepEqual(relayProfileDraftReseedPlan({ slug: 'relay-a', dirty }, 'relay-b'), {
+      reseed: true,
+      clearDirty: true,
+    });
+  }
+});
+
+test('the draft seed sanitizes a hand-edited saved table', () => {
+  // Runtime reads sanitize through relayModelProfile; the editor must show
+  // the same canonical view — a malformed local file degrades to no
+  // declaration, not to UI state TypeScript does not model.
+  assert.deepEqual(
+    relayProfileDraftSeed({
+      reasoner: { thinkingLevels: 'low' as never, contextWindow: '128000' as never },
+      ghost: { thinkingLevels: ['off', 'low'] },
+      visual: { vision: true },
+    }),
+    {
+      ghost: { thinkingLevels: ['low'] },
+      visual: { vision: true },
+    },
+  );
+  assert.deepEqual(relayProfileDraftSeed(undefined), {});
+});
diff --git a/apps/desktop/src/main/__tests__/runtime-host-config-ipc-main.test.ts b/apps/desktop/src/main/__tests__/runtime-host-config-ipc-main.test.ts
new file mode 100644
index 0000000000..c56d12c203
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/runtime-host-config-ipc-main.test.ts
@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type {
+  ConnectionCatalogEntry,
+  ConnectionCatalogSnapshot,
+} from '@maka/core/runtime-policy';
+import type { LlmConnection } from '@maka/core/llm-connections';
+import { saveConnection } from '../runtime-host-config-ipc-main.js';
+
+function existingConnection(overrides: Partial<ConnectionCatalogEntry> = {}): ConnectionCatalogEntry {
+  return {
+    connectionId: 'connection-1',
+    revision: 4,
+    slug: 'my-relay',
+    name: 'Relay',
+    providerType: 'openai-compatible',
+    baseUrl: 'https://relay.example/v1',
+    enabled: true,
+    enabledModelIds: ['model-1'],
+    models: [{ id: 'model-1' }],
+    ...overrides,
+  };
+}
+
+function snapshot(connections: ConnectionCatalogEntry[]): ConnectionCatalogSnapshot {
+  return { revision: 7, defaultTarget: null, connections };
+}
+
+function fakeClient(existing: ConnectionCatalogEntry) {
+  const updatePatches: Record<string, unknown>[] = [];
+  let connections = [existing];
+  const client = {
+    async loadConnectionCatalog() {
+      return snapshot(connections);
+    },
+    async updateConnection(
+      expected: { connectionId: string; revision: number },
+      patch: Record<string, unknown>,
+    ) {
+      updatePatches.push(patch);
+      connections = [
+        {
+          ...existing,
+          revision: existing.revision + 1,
+          ...(patch.relayModelProfiles === null || patch.relayModelProfiles === undefined
+            ? {}
+            : {
+                relayModelProfiles: patch.relayModelProfiles as ConnectionCatalogEntry['relayModelProfiles'],
+              }),
+        },
+      ];
+      return { kind: 'committed' as const };
+    },
+  };
+  return { client, updatePatches };
+}
+
+test('import overwrite with a profile-free snapshot CLEARS existing relay profiles', async () => {
+  // Importing is snapshot replacement: the Host update contract treats an
+  // ABSENT relayModelProfiles as "untouched", which would resurrect the old
+  // declarations after a "no profiles here" backup.
+  const { client, updatePatches } = fakeClient(
+    existingConnection({ relayModelProfiles: { 'model-1': { vision: true } } }),
+  );
+  const incoming: LlmConnection = {
+    slug: 'my-relay',
+    name: 'Relay',
+    providerType: 'openai-compatible',
+    baseUrl: 'https://relay.example/v1',
+    defaultModel: 'model-1',
+    enabled: true,
+    enabledModelIds: ['model-1'],
+    createdAt: 0,
+    updatedAt: 0,
+  };
+
+  await saveConnection(client as never, incoming);
+
+  assert.equal(updatePatches.length, 1);
+  assert.equal(updatePatches[0]?.relayModelProfiles, null);
+});
+
+test('import overwrite with profiles REPLACES the existing table', async () => {
+  const { client, updatePatches } = fakeClient(
+    existingConnection({ relayModelProfiles: { 'model-1': { vision: true } } }),
+  );
+  const incoming: LlmConnection = {
+    slug: 'my-relay',
+    name: 'Relay',
+    providerType: 'openai-compatible',
+    baseUrl: 'https://relay.example/v1',
+    defaultModel: 'model-1',
+    enabled: true,
+    enabledModelIds: ['model-1'],
+    createdAt: 0,
+    updatedAt: 0,
+    relayModelProfiles: { 'model-1': { contextWindow: 64_000 } },
+  };
+
+  await saveConnection(client as never, incoming);
+
+  assert.equal(updatePatches.length, 1);
+  assert.deepEqual(updatePatches[0]?.relayModelProfiles, {
+    'model-1': { contextWindow: 64_000 },
+  });
+});
diff --git a/apps/desktop/src/main/__tests__/runtime-host-github-copilot-ipc-main.test.ts b/apps/desktop/src/main/__tests__/runtime-host-github-copilot-ipc-main.test.ts
index 8aa6c47d39..79031f6866 100644
--- a/apps/desktop/src/main/__tests__/runtime-host-github-copilot-ipc-main.test.ts
+++ b/apps/desktop/src/main/__tests__/runtime-host-github-copilot-ipc-main.test.ts
@@ -58,9 +58,11 @@ test('imports a local GitHub credential through the shared Host account path', a
         connectionId: current.connectionId,
         revision: current.revision,
       });
+      const { relayModelProfiles, ...restChanges } = changes;
       const updated: ConnectionCatalogEntry = {
         ...current,
-        ...changes,
+        ...restChanges,
+        ...(relayModelProfiles === null ? {} : { relayModelProfiles }),
         revision: current.revision + 1,
       };
       catalog = {
diff --git a/apps/desktop/src/main/connections-ipc-validation.ts b/apps/desktop/src/main/connections-ipc-validation.ts
index a01dfcd31b..41666a47cf 100644
--- a/apps/desktop/src/main/connections-ipc-validation.ts
+++ b/apps/desktop/src/main/connections-ipc-validation.ts
@@ -4,6 +4,7 @@ import {
   type UpdateConnectionInput,
 } from '@maka/core';
 import { PROVIDER_DEFAULTS } from '@maka/core/llm-connections';
+import { normalizeRelayModelProfiles } from '@maka/core/model-thinking';
 
 const IPC_CONNECTION_SLUG_MAX_LENGTH = 64;
 const IPC_CONNECTION_SECRET_MAX_LENGTH = 4096;
@@ -51,10 +52,15 @@ export function normalizeCreateConnectionInputForIpc(value: unknown): CreateConn
     ? undefined
     : normalizeConnectionApiKeyForIpc(input.apiKey, 'apiKey');
   const slug = normalizeConnectionSlugForIpc(input.slug, 'connection slug');
+  const relayModelProfiles =
+    input.relayModelProfiles === undefined
+      ? undefined
+      : normalizeRelayModelProfiles(input.relayModelProfiles);
   const normalized = {
     ...input,
     slug,
     ...(apiKey === undefined ? {} : { apiKey }),
+    ...(relayModelProfiles === undefined ? {} : { relayModelProfiles }),
   } as CreateConnectionInput;
   return normalizeConnectionBaseUrlForIpc(normalized);
 }
diff --git a/apps/desktop/src/main/desktop-backend-tool-surface.ts b/apps/desktop/src/main/desktop-backend-tool-surface.ts
index 8b115eea41..f61ae0e2ed 100644
--- a/apps/desktop/src/main/desktop-backend-tool-surface.ts
+++ b/apps/desktop/src/main/desktop-backend-tool-surface.ts
@@ -1,5 +1,6 @@
 import {
   activePlanExecution,
+  relayModelProfile,
   DEFAULT_SESSION_NAME,
   defaultWebSearchSettings,
   isDeepResearchSession,
@@ -348,7 +349,12 @@ function replaceParentAgentTools(
 }
 
 function modelSupportsVision(connection: LlmConnection, model: string): boolean {
-  return resolveModelVisionSupport(connection.providerType, connection.models, model);
+  return resolveModelVisionSupport(
+    connection.providerType,
+    connection.models,
+    model,
+    relayModelProfile(connection, model)?.vision,
+  );
 }
 
 function resolveDurableChildTools(
diff --git a/apps/desktop/src/main/runtime-host-account-connection.ts b/apps/desktop/src/main/runtime-host-account-connection.ts
index 9d85144854..2ac41193df 100644
--- a/apps/desktop/src/main/runtime-host-account-connection.ts
+++ b/apps/desktop/src/main/runtime-host-account-connection.ts
@@ -192,6 +192,10 @@ function accountConnectionChanges(
     ...(connection.baseUrl === undefined ? {} : { baseUrl: connection.baseUrl }),
     enabled,
     enabledModelIds: [...enabledModelIds],
+    // Account (OAuth) connections never declare relay capabilities, and the
+    // omission is the point: with tri-state update semantics an absent key
+    // leaves the stored table untouched, so this path can never clobber
+    // declarations another writer made.
   };
 }
 
diff --git a/apps/desktop/src/main/runtime-host-config-ipc-main.ts b/apps/desktop/src/main/runtime-host-config-ipc-main.ts
index fb47148d4c..a75ead306b 100644
--- a/apps/desktop/src/main/runtime-host-config-ipc-main.ts
+++ b/apps/desktop/src/main/runtime-host-config-ipc-main.ts
@@ -173,7 +173,9 @@ function runtimeHostTransferDeps(
   };
 }
 
-async function saveConnection(
+// Exported for the import-overwrite tests: this adapter is where snapshot
+// semantics meet the Host's tri-state update contract.
+export async function saveConnection(
   client: DesktopRuntimeHostClient,
   connection: LlmConnection,
 ): Promise<LlmConnection> {
@@ -198,12 +200,17 @@ async function saveConnection(
         ...(connection.baseUrl ? { baseUrl: connection.baseUrl } : {}),
         enabled: connection.enabled,
         enabledModelIds: [...(connection.enabledModelIds ?? [])],
+        // Import-overwrite is snapshot replacement: absent in the snapshot
+        // must CLEAR, not inherit — the update contract's "absent means
+        // untouched" would otherwise resurrect the old profiles.
+        relayModelProfiles: connection.relayModelProfiles ?? null,
       },
     );
     if (updated.kind !== 'committed') {
       throw new Error(`Unable to update imported Connection: ${updated.kind}`);
     }
   } else {
+    const importedProfiles = connection.relayModelProfiles;
     const created = await client.createConnection(catalog.revision, {
       slug: connection.slug,
       name: connection.name,
@@ -211,6 +218,7 @@ async function saveConnection(
       ...(connection.baseUrl ? { baseUrl: connection.baseUrl } : {}),
       enabled: connection.enabled,
       enabledModelIds: [...(connection.enabledModelIds ?? [])],
+      ...(importedProfiles === undefined ? {} : { relayModelProfiles: importedProfiles }),
     });
     if (created.kind !== 'committed') {
       throw new Error(`Unable to create imported Connection: ${created.kind}`);
diff --git a/apps/desktop/src/main/runtime-host-connections-ipc-main.ts b/apps/desktop/src/main/runtime-host-connections-ipc-main.ts
index d4d307d7a3..2e5345075d 100644
--- a/apps/desktop/src/main/runtime-host-connections-ipc-main.ts
+++ b/apps/desktop/src/main/runtime-host-connections-ipc-main.ts
@@ -9,6 +9,7 @@ import {
   PROVIDER_DEFAULTS,
   providerAuthRequiresSecret,
 } from '@maka/core/llm-connections';
+import { normalizeRelayModelProfiles } from '@maka/core/model-thinking';
 import type {
   ConnectionCatalogEntry,
   ConnectionCatalogSnapshot,
@@ -86,6 +87,9 @@ export function registerRuntimeHostConnectionsIpc(
   deps.ipcMain.handle('connections:create', async (_event, raw: unknown) => {
     const input = normalizeCreateInput(raw);
     const catalog = await snapshot();
+    // Profiles ride as the typed field end to end — nothing free-form
+    // crosses to the host.
+    const relayModelProfiles = input.relayModelProfiles;
     const created = await deps.client.createConnection(catalog.revision, {
       slug: input.slug,
       name: input.name,
@@ -93,6 +97,7 @@ export function registerRuntimeHostConnectionsIpc(
       ...(input.baseUrl === undefined ? {} : { baseUrl: input.baseUrl }),
       enabled: true,
       enabledModelIds: input.defaultModel ? [input.defaultModel] : [],
+      ...(relayModelProfiles === undefined ? {} : { relayModelProfiles }),
     });
     if (created.kind !== 'committed') {
       throw new Error(`Unable to create Connection: ${created.kind}`);
@@ -129,6 +134,12 @@ export function registerRuntimeHostConnectionsIpc(
             : { baseUrl: patch.baseUrl }),
         enabled: patch.enabled ?? current.enabled,
         enabledModelIds: patch.enabledModelIds ?? current.enabledModelIds,
+        // Tri-state: a patch that mentions profiles re-normalizes them (empty
+        // normalization = clear); a patch without profiles omits the key
+        // entirely, which the store reads as "leave the table alone".
+        ...(patch.relayModelProfiles === undefined
+          ? {}
+          : { relayModelProfiles: normalizeRelayModelProfiles(patch.relayModelProfiles) ?? null }),
       },
     );
     if (updated.kind !== 'committed') {
@@ -229,6 +240,9 @@ export function projectHostConnections(catalog: ConnectionCatalogSnapshot): LlmC
       defaultModel,
       enabledModelIds: [...connection.enabledModelIds],
       models: [...connection.models],
+      ...(connection.relayModelProfiles === undefined
+        ? {}
+        : { relayModelProfiles: connection.relayModelProfiles }),
       ...(connection.modelSource === undefined ? {} : { modelSource: connection.modelSource }),
       ...(connection.modelsFetchedAt === undefined
         ? {}
diff --git a/apps/desktop/src/main/sessions-ipc-main.ts b/apps/desktop/src/main/sessions-ipc-main.ts
index 086da76d1d..82200b32ff 100644
--- a/apps/desktop/src/main/sessions-ipc-main.ts
+++ b/apps/desktop/src/main/sessions-ipc-main.ts
@@ -10,7 +10,7 @@ import {
   isSideConversationSession,
   isThinkingLevel,
   sanitizeTaskLedgerTask,
-  thinkingVariantsForModel,
+  thinkingVariantsForConnection,
 } from '@maka/core';
 import type {
   CreateSessionRequestInput,
@@ -24,7 +24,7 @@ import type {
   GitReviewMutationAction,
   GitReviewSource,
 } from '@maka/core';
-import type { ProviderType } from '@maka/core/llm-connections';
+import type { ConnectionThinkingContext } from '@maka/core/model-thinking';
 import type { WorkspacePrivacyContext } from '@maka/core/incognito';
 import {
   defaultShellPlan,
@@ -166,7 +166,7 @@ function latestStoredMessageTs(messages: readonly StoredMessage[]): number | und
 
 function normalizeSupportedSessionThinkingLevel(
   input: unknown,
-  providerType: ProviderType,
+  connection: ConnectionThinkingContext,
   model: string,
 ): ThinkingLevel | undefined {
   const thinkingLevel = input === undefined || input === null ? undefined : input;
@@ -174,7 +174,7 @@ function normalizeSupportedSessionThinkingLevel(
   if (!isThinkingLevel(thinkingLevel)) {
     throw new Error(`Invalid thinking level: ${String(input)}`);
   }
-  if (!thinkingVariantsForModel(providerType, model).includes(thinkingLevel)) {
+  if (!thinkingVariantsForConnection(connection, model).includes(thinkingLevel)) {
     throw new Error(`当前模型不支持思考级别：${thinkingLevel}`);
   }
   return thinkingLevel;
@@ -515,7 +515,7 @@ export function registerSessionsIpc(
 
     const requestedSlug = input?.llmConnectionSlug ?? (await connectionStore.getDefault());
     const { connection, model } = await getReadyConnection(requestedSlug, input?.model);
-    const thinkingLevel = normalizeSupportedSessionThinkingLevel(input?.thinkingLevel, connection.providerType, model);
+    const thinkingLevel = normalizeSupportedSessionThinkingLevel(input?.thinkingLevel, connection, model);
 
     const session = await createSession({
       ...(input?.cwd ? { cwd: input.cwd } : {}),
@@ -946,7 +946,7 @@ export function registerSessionsIpc(
     if (!connection) {
       throw new Error(`Unknown connection: ${header.llmConnectionSlug}`);
     }
-    const nextThinkingLevel = normalizeSupportedSessionThinkingLevel(input, connection.providerType, header.model);
+    const nextThinkingLevel = normalizeSupportedSessionThinkingLevel(input, connection, header.model);
     const next = await runtime.updateSession(sessionId, nextThinkingLevel === undefined ? { thinkingLevel: undefined } : { thinkingLevel: nextThinkingLevel });
     emitSessionsChanged('updated', sessionId);
     return next;
diff --git a/apps/desktop/src/renderer/locales/settings-provider-copy.ts b/apps/desktop/src/renderer/locales/settings-provider-copy.ts
index 1aa4b06e6b..644af0fa3e 100644
--- a/apps/desktop/src/renderer/locales/settings-provider-copy.ts
+++ b/apps/desktop/src/renderer/locales/settings-provider-copy.ts
@@ -6,6 +6,40 @@ type WidenCopy<T> = T extends string
     ? (...args: Args) => string
     : { [K in keyof T]: WidenCopy<T[K]> };
 
+// Capability-section strings for the connection detail page — the add-provider
+// form deliberately carries no declaration controls (capabilities are edited
+// after the connection exists).
+const zhCapabilitiesCopy = {
+  capabilities: '能力',
+  thinkingEffort: '思考档位（reasoning_effort）',
+  thinkingEffortHelp: '勾选需要的思考强度档位，不勾选即为不声明。',
+  thinkingUndeclared: '未声明',
+  thinkingSelectedCount: (count: number) => `已选择 ${count} 个`,
+  visionInput: '视觉输入（vision）',
+  visionInputHelp: '「自动」跟随内置元数据；「启用/禁用」是显式声明，覆盖自动判断。',
+  visionAuto: '自动',
+  visionEnabledOption: '启用',
+  visionDisabledOption: '禁用',
+  contextWindow: '上下文窗口（tokens）',
+  contextWindowHelp: '声明后压缩与预算按此值计算；留空跟随内置元数据。',
+  saveCapabilities: '保存能力声明',
+};
+const enCapabilitiesCopy = {
+  capabilities: 'Capabilities',
+  thinkingEffort: 'Thinking levels (reasoning_effort)',
+  thinkingEffortHelp: 'Tick the thinking levels this model supports; none ticked means undeclared.',
+  thinkingUndeclared: 'Undeclared',
+  thinkingSelectedCount: (count: number) => `${count} selected`,
+  visionInput: 'Vision input',
+  visionInputHelp: 'Auto follows built-in metadata; Enabled/Disabled overrides it explicitly.',
+  visionAuto: 'Auto',
+  visionEnabledOption: 'Enabled',
+  visionDisabledOption: 'Disabled',
+  contextWindow: 'Context window (tokens)',
+  contextWindowHelp: 'When set, compaction and budgets use this value; when empty, built-in metadata decides.',
+  saveCapabilities: 'Save capability declarations',
+};
+
 const zhCopy = {
   detail: {
     delete: '删除', cancel: '取消', deleteUnused: '不再需要，删除连接',
@@ -25,6 +59,8 @@ const zhCopy = {
     credentialsHelp: '密钥只保存在本机。',
     credentialsHelpAccount: '登录令牌只保存在本机。',
     modelManagementHelp: '这些模型会出现在对话的模型选择器里。',
+    ...zhCapabilitiesCopy,
+    capabilitiesHelp: '声明每个已启用模型的思考档位、视觉与上下文窗口；保存后生效。',
     // Row affordances (settings-sidebar 的 InfoRow / ExpandableRow 语言)：一行
     // 只报状态，改的时候才展开成输入框。
     change: '更换', set: '设置', edit: '编辑', save: '保存',
@@ -102,6 +138,7 @@ const zhCopy = {
     saving: '保存中…', save: '保存供应商', keyRequired: (name: string) => `请填写 ${name} API Key`,
     apiKeyLabel: 'API Key', accountIdLabel: 'Cloudflare Account ID', endpointLabel: '服务地址',
     defaultModel: '默认模型', defaultModelPlaceholder: '填写你的中转站模型 ID，例如 gpt-4o、claude-sonnet-4-5 或自定义模型名', defaultModelHelp: '用于首次连接测试和模型选择器兜底；保存后仍会自动拉取模型目录。', defaultModelRequired: '请填写默认模型 ID。保存后仍会自动拉取模型目录。',
+    ...zhCapabilitiesCopy,
   },
   oauthFlow: {
     refreshFailed: '刷新登录状态失败', accountActionFailed: (name: string) => `${name} 账号操作失败`, loginFailedRetry: '登录失败，请稍后重试。',
@@ -168,6 +205,8 @@ const enCopy: ProviderSettingsCopy = {
     credentialsHelp: 'The key stays on this machine.',
     credentialsHelpAccount: 'The sign-in token stays on this machine.',
     modelManagementHelp: 'These models appear in the chat model picker.',
+    ...enCapabilitiesCopy,
+    capabilitiesHelp: 'Declares thinking levels, vision, and context window per enabled model; applies on save.',
     change: 'Change', set: 'Set', edit: 'Edit', save: 'Save',
     endpointDefault: 'The provider default',
     modelManagement: 'Models',
@@ -243,6 +282,7 @@ const enCopy: ProviderSettingsCopy = {
     saving: 'Saving…', save: 'Save provider', keyRequired: (name: string) => `Enter the ${name} API key`,
     apiKeyLabel: 'API key', accountIdLabel: 'Cloudflare Account ID', endpointLabel: 'Service URL',
     defaultModel: 'Default model', defaultModelPlaceholder: 'Enter your relay model id, e.g. gpt-4o, claude-sonnet-4-5, or a custom model name', defaultModelHelp: 'Used as the first connection-test and picker fallback; Maka still fetches the model catalog after saving.', defaultModelRequired: 'Enter a default model id. Maka still fetches the model catalog after saving.',
+    ...enCapabilitiesCopy,
   },
   oauthFlow: {
     refreshFailed: 'Failed to refresh sign-in status', accountActionFailed: (name: string) => `${name} account action failed`, loginFailedRetry: 'Sign-in failed. Try again later.',
diff --git a/apps/desktop/src/renderer/settings/provider-add-form.tsx b/apps/desktop/src/renderer/settings/provider-add-form.tsx
index bbe411505e..305de4635a 100644
--- a/apps/desktop/src/renderer/settings/provider-add-form.tsx
+++ b/apps/desktop/src/renderer/settings/provider-add-form.tsx
@@ -15,7 +15,14 @@ import {
   providerSupportsModelDiscovery,
 } from '@maka/core/llm-connections';
 import { Banner, HStack, VStack } from '@astryxdesign/core';
-import { Button, FormLayout, TextInput, useMountedRef, useUiLocale } from '@maka/ui';
+import {
+  Button,
+  FormLayout,
+  TextInput,
+  useMountedRef,
+  useUiLocale,
+} from '@maka/ui';
+
 import { buildCatalogRecommendedDefaultModel } from '../model-catalog-choices';
 import { PasswordInput } from './password-input';
 import { providerDisplay } from './provider-display';
@@ -137,12 +144,13 @@ export function AddProviderForm(props: {
             encodeURIComponent(normalizedCloudflareAccountId),
           )
         : baseUrl || undefined;
+      const createdDefaultModel = normalizedDefaultModel || recommendedDefaultModel;
       const connection = await props.bridge.create({
         slug,
         name: name || display.name,
         providerType: props.providerType,
         baseUrl: resolvedBaseUrl,
-        defaultModel: normalizedDefaultModel || recommendedDefaultModel,
+        defaultModel: createdDefaultModel,
         ...(props.providerType === 'opencode-free'
           ? { enabledModelIds: [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS] }
           : {}),
diff --git a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
index c7c4f7101e..cbb1de610a 100644
--- a/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
+++ b/apps/desktop/src/renderer/settings/provider-connection-detail.tsx
@@ -1,9 +1,28 @@
-import { useState, type ReactNode } from 'react';
-import { Banner, Divider, Grid, Heading, HStack, Link, Text, VStack } from '@astryxdesign/core';
+import { useEffect, useState, type ReactNode } from 'react';
+import {
+  Banner,
+  Divider,
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  Grid,
+  Heading,
+  HStack,
+  Link,
+  Text,
+  VStack,
+} from '@astryxdesign/core';
 import { PROVIDER_DEFAULTS } from '@maka/core/llm-connections';
+import {
+  DECLARABLE_RELAY_THINKING_LEVELS,
+  THINKING_LEVELS,
+  type RelayModelProfile,
+  type ThinkingLevel,
+} from '@maka/core/model-thinking';
 import {
   Button,
+  NumberInput,
   RelativeTime,
+  Selector,
   TextInput,
   useMountedRef,
   useToast,
@@ -118,11 +137,28 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
     savedBaseUrl,
     save,
     updateEnabledModels,
+    relayProfileDraft,
+    hasRelayProfileChanges,
+    setDraftThinkingLevels,
+    setDraftVision,
+    setDraftContextWindow,
+    saveRelayProfiles,
     runTest,
     refreshModels,
     remove,
     refreshAfterRelogin,
   } = useConnectionDetail(props);
+  // Capability switches only exist for openai-compatible relays: built-in
+  // providers declare their thinking support in model metadata, a custom
+  // relay's backing model is unknown until the user says what it can do. The
+  // declaration is per model — a relay can front both a reasoner and a plain
+  // instruct model.
+  const showsCapabilities = connection.providerType === 'openai-compatible';
+  // Rows are the enabled models, exactly — the store prunes a model's profile
+  // the moment it is disabled, so no declaration can ever belong to a row
+  // this list does not show. The editor edits the per-model draft; 保存
+  // commits the whole table in one write.
+  const capabilityModelIds = enabledModelIds;
   // One row is a form at a time, the way the settings-sidebar template does it.
   // Opening a row discards the other's draft: leaving an abandoned draft in
   // state meant it reappeared when the user came back to that row, and — until
@@ -306,6 +342,134 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
           )}
         </HStack>
       </DetailSection>
+      {showsCapabilities && (
+        <>
+          <Divider />
+          <DetailSection title={copy.capabilities} description={copy.capabilitiesHelp}>
+            <VStack gap={4}>
+              {capabilityModelIds.map((modelId, modelIndex) => {
+                const declared: RelayModelProfile | undefined = relayProfileDraft[modelId];
+                // Vision resolves to one of three states: absent (Auto),
+                // true (Enabled), false (explicitly Disabled). Only Auto is
+                // ever ambiguous, and three distinct controls keep it honest.
+                const visionValue =
+                  declared?.vision === true
+                    ? 'enabled'
+                    : declared?.vision === false
+                      ? 'disabled'
+                      : 'auto';
+                const draftLevels = declared?.thinkingLevels ?? [];
+                // The menu offers the five declarable levels PLUS anything
+                // the stored table already claims — a level saved while it
+                // was still declarable (or hand-written into the document)
+                // must stay visible and un-checkable, never an invisible
+                // selection the trigger counts but the menu cannot show.
+                const menuLevels: readonly ThinkingLevel[] = THINKING_LEVELS.filter(
+                  (level) =>
+                    (DECLARABLE_RELAY_THINKING_LEVELS as readonly ThinkingLevel[]).includes(
+                      level,
+                    ) || draftLevels.includes(level),
+                );
+                return (
+                  <VStack key={modelId} gap={3}>
+                    {modelIndex > 0 && <Divider />}
+                    <Text weight="semibold">{modelId}</Text>
+                    {/* One row per declaration: label + what it does on the
+                        left, one compact control on the right (the 模型功能
+                        row language). A CheckboxList wall was the reason this
+                        section looked like a form from a different app. */}
+                    <CapabilityRow label={copy.thinkingEffort} description={copy.thinkingEffortHelp}>
+                      {/* DropdownMenu, not MultiSelector: levels have a
+                          canonical order (low → max) that must not shuffle —
+                          MultiSelector pins the selected-at-open options to
+                          the top with no opt-out, which misread as the
+                          declaration being order-sensitive. Checkbox items
+                          stay open between toggles; the trigger carries the
+                          已选择 N 个 state line. */}
+                      <DropdownMenu
+                        button={{
+                          variant: 'secondary',
+                          size: 'sm',
+                          label:
+                            draftLevels.length > 0
+                              ? copy.thinkingSelectedCount(draftLevels.length)
+                              : copy.thinkingUndeclared,
+                          'aria-label': `${copy.thinkingEffort} — ${modelId}`,
+                          isDisabled: detailActionBusy,
+                        }}
+                        hasChevron
+                        menuWidth={224}
+                      >
+                        {menuLevels.map((level) => (
+                          <DropdownMenuCheckboxItem
+                            key={level}
+                            label={level}
+                            aria-label={`${modelId} ${level}`}
+                            value={draftLevels.includes(level)}
+                            onChange={(checked) => {
+                              setDraftThinkingLevels(
+                                modelId,
+                                checked
+                                  ? [...draftLevels, level]
+                                  : draftLevels.filter((existing) => existing !== level),
+                              );
+                            }}
+                            isDisabled={detailActionBusy}
+                          />
+                        ))}
+                      </DropdownMenu>
+                    </CapabilityRow>
+                    <CapabilityRow label={copy.visionInput} description={copy.visionInputHelp}>
+                      <Selector
+                        label={`${copy.visionInput} — ${modelId}`}
+                        isLabelHidden
+                        size="sm"
+                        width={132}
+                        options={[
+                          { value: 'auto', label: copy.visionAuto },
+                          { value: 'enabled', label: copy.visionEnabledOption },
+                          { value: 'disabled', label: copy.visionDisabledOption },
+                        ]}
+                        value={visionValue}
+                        onChange={(value) =>
+                          setDraftVision(
+                            modelId,
+                            value === 'auto' ? undefined : value === 'enabled',
+                          )
+                        }
+                        isDisabled={detailActionBusy}
+                      />
+                    </CapabilityRow>
+                    <CapabilityRow label={copy.contextWindow} description={copy.contextWindowHelp}>
+                      <DeclaredContextWindowField
+                        declared={declared?.contextWindow}
+                        disabled={detailActionBusy}
+                        label={copy.contextWindow}
+                        onCommit={(value) =>
+                          setDraftContextWindow(modelId, value ?? undefined)
+                        }
+                      />
+                    </CapabilityRow>
+                  </VStack>
+                );
+              })}
+              {/* One commit for the whole table. Draft edits stay local until
+                  this lands; the button only arms when the draft truly differs
+                  from the saved table (both sides pass the write-path
+                  normalizer, so reordering levels doesn't arm it falsely). */}
+              <HStack gap={2} justify="end">
+                <Button
+                  variant="primary"
+                  size="sm"
+                  isDisabled={detailActionBusy || !hasRelayProfileChanges}
+                  clickAction={() => void saveRelayProfiles()}
+                  label={copy.saveCapabilities}
+                />
+              </HStack>
+            </VStack>
+          </DetailSection>
+        </>
+      )}
       <Divider />
       {/* Deletion is last, and the only thing beside it is its own warning —
           no quiet action next to the destructive one for a mis-aimed cursor. */}
@@ -332,6 +496,60 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
  * as heading → sentence → controls; it splits into two columns for free if the
  * shell ever widens.
  */
+// A context-window draft commits on blur/Enter only: NumberInput fires
+// onChange per *valid* keystroke, and "128000" must arrive as one draft edit,
+// not six. The committed draft stays local until the section's 保存 — nothing
+// here writes the connection itself. The draft resyncs from the controller's
+// draft whenever it changes (seed, save round-trip, or an unrelated field).
+function DeclaredContextWindowField(props: {
+  declared: number | undefined;
+  disabled: boolean;
+  label: string;
+  onCommit: (value: number | null) => void;
+}) {
+  const [draft, setDraft] = useState<number | null>(props.declared ?? null);
+  useEffect(() => {
+    setDraft(props.declared ?? null);
+  }, [props.declared]);
+  function commit() {
+    if ((draft ?? undefined) === props.declared) return;
+    props.onCommit(draft);
+  }
+  return (
+    <NumberInput
+      size="sm"
+      width={200}
+      label={props.label}
+      isLabelHidden
+      value={draft}
+      hasClear
+      isIntegerOnly
+      min={1}
+      onChange={setDraft}
+      onBlur={commit}
+      onEnter={commit}
+      isDisabled={props.disabled}
+    />
+  );
+}
+
+/**
+ * One declaration row in the 模型功能 shape: what it is (label) and what it
+ * does (one supporting sentence) on the left, its one compact control on the
+ * right. The text column flexes and wraps; the control never does.
+ */
+function CapabilityRow(props: { label: string; description: string; children: ReactNode }) {
+  return (
+    <HStack gap={4} justify="between" vAlign="start">
+      <VStack gap={1} maxWidth={380}>
+        <Text size="sm">{props.label}</Text>
+        <Text type="supporting" color="secondary">{props.description}</Text>
+      </VStack>
+      {props.children}
+    </HStack>
+  );
+}
+
 function DetailSection(props: { title: string; description: string; children: ReactNode }) {
   return (
     /* `columnGap`, not `gap`: the template's 10 is the gutter BETWEEN the two
diff --git a/apps/desktop/src/renderer/settings/relay-profile-draft.ts b/apps/desktop/src/renderer/settings/relay-profile-draft.ts
new file mode 100644
index 0000000000..a885a13215
--- /dev/null
+++ b/apps/desktop/src/renderer/settings/relay-profile-draft.ts
@@ -0,0 +1,52 @@
+import {
+  normalizeRelayModelProfiles,
+  type RelayModelProfile,
+  type RelayModelProfiles,
+} from '@maka/core/model-thinking';
+
+/**
+ * Reseed decision for the relay-profile editor's local draft. The editor is
+ * one component instance that can serve a sequence of connections (the
+ * settings page swaps the `connection` prop under it), and its draft state
+ * is connection-scoped: a dirty draft belongs to the slug that made it.
+ */
+export interface RelayProfileDraftLifecycle {
+  readonly slug: string;
+  readonly dirty: boolean;
+}
+
+export interface RelayProfileDraftReseed {
+  readonly reseed: boolean;
+  readonly clearDirty: boolean;
+}
+
+/**
+ * Slug switch always wins over unsaved edits: carrying draft A onto
+ * connection B would show B one model's capabilities borrowed from A, and
+ * the next 保存能力声明 would write A's declarations into B's document.
+ * A same-slug reload only reseeds while the draft is clean, so an unrelated
+ * refresh never discards typed work.
+ */
+export function relayProfileDraftReseedPlan(
+  lifecycle: RelayProfileDraftLifecycle,
+  connectionSlug: string,
+): RelayProfileDraftReseed {
+  if (lifecycle.slug !== connectionSlug) {
+    return { reseed: true, clearDirty: true };
+  }
+  return { reseed: !lifecycle.dirty, clearDirty: false };
+}
+
+/**
+ * The saved table in draft form. A hand-edited local connections file may
+ * carry values that don't typecheck (`thinkingLevels: "low"`, string context
+ * windows); runtime reads sanitize through `relayModelProfile`, so the
+ * editor seeds from the same sanitizer — the draft shows exactly what would
+ * persist if saved right away, and the "malformed is noise" promise holds
+ * identically on both sides.
+ */
+export function relayProfileDraftSeed(
+  profiles: RelayModelProfiles | undefined,
+): Record<string, RelayModelProfile> {
+  return normalizeRelayModelProfiles(profiles) ?? {};
+}
diff --git a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
index 46aec1a40a..523ebc6190 100644
--- a/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/subagent-settings-page.tsx
@@ -27,7 +27,7 @@ import {
   type UpdateAppSettingsResult,
 } from '@maka/core';
 import { connectionEnabledModelIds } from '@maka/core/llm-connections';
-import { thinkingVariantsForModel } from '@maka/core/model-thinking';
+import { thinkingVariantsForConnection } from '@maka/core/model-thinking';
 import {
   Badge,
   Button,
@@ -349,7 +349,7 @@ function SubagentPresetEditor(props: {
     ? connectionEnabledModelIds(selectedConnection)
     : [];
   const thinkingLevels = selectedConnection
-    ? thinkingVariantsForModel(selectedConnection.providerType, draft.model)
+    ? thinkingVariantsForConnection(selectedConnection, draft.model)
     : [];
   const profileCopy = copy.profiles[draft.profile];
   const validId = isSafeSubagentPresetId(draft.id.trim());
diff --git a/apps/desktop/src/renderer/settings/use-connection-detail.ts b/apps/desktop/src/renderer/settings/use-connection-detail.ts
index 7ea7a65194..ed1d840756 100644
--- a/apps/desktop/src/renderer/settings/use-connection-detail.ts
+++ b/apps/desktop/src/renderer/settings/use-connection-detail.ts
@@ -7,6 +7,12 @@ import {
 } from '@maka/core';
 import { PROVIDER_DEFAULTS, connectionEnabledModelIds } from '@maka/core/llm-connections';
 import { buildConnectionModelCatalogEntries } from '@maka/core/model-catalog';
+import {
+  normalizeRelayModelProfiles,
+  pruneRelayModelProfiles,
+  type RelayModelProfile,
+  type ThinkingLevel,
+} from '@maka/core/model-thinking';
 import { isWiredOAuthProvider } from '@maka/core/provider-registry';
 import {
   providerAuthRequiresSecret,
@@ -16,6 +22,7 @@ import {
 import { useMountedRef, useToast, useUiLocale } from '@maka/ui';
 import { getProviderSettingsCopy } from '../locales/settings-provider-copy';
 import { connectionChipStatus } from './provider-connection-status';
+import { relayProfileDraftReseedPlan, relayProfileDraftSeed } from './relay-profile-draft';
 import { useKeyedActionGuard } from './use-action-guard';
 import type { OAuthLoginFlowBridge } from './use-oauth-login-flow';
 import {
@@ -100,7 +107,7 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
   const [savingEnabledModels, setSavingEnabledModels] = useState(false);
   const [deleting, setDeleting] = useState(false);
   const connectionDetailActionGuard = useKeyedActionGuard<
-    'save' | 'test' | 'fetch-models' | 'save-enabled-models' | 'delete'
+    'save' | 'test' | 'fetch-models' | 'save-enabled-models' | 'save-relay-profiles' | 'delete'
   >();
   const connectionDetailMountedRef = useMountedRef();
   const connectionDetailLifecycleRef = useRef(0);
@@ -327,6 +334,137 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
     }
   }
 
+  // Per-model profile declarations for openai-compatible relays, edited as a
+  // LOCAL DRAFT and committed by an explicit 保存 button — never keystroke by
+  // keystroke. A draft is `Record<modelId, RelayModelProfile>` seeded from the
+  // saved table; entries a user empties fully drop out of the map, and the
+  // ≥1-enabled-model invariant is honored live: the draft is pruned against
+  // `enabledModelIds` on every read, so disabling a model in the section above
+  // removes its unsaved declaration too (the store prunes the SAVED table the
+  // same way on write).
+  const [relayProfileDrafts, setRelayProfileDrafts] = useState<Record<string, RelayModelProfile>>(
+    () => relayProfileDraftSeed(connection.relayModelProfiles),
+  );
+  const [relayProfilesDirty, setRelayProfilesDirty] = useState(false);
+  // The dirty flag names a slug: the same instance continues across the
+  // connection switcher, and draft state is owned by one connection at a
+  // time (see relayProfileDraftReseedPlan).
+  const relayProfileDraftOwnerRef = useRef(connection.slug);
+
+  function updateRelayProfileDraft(
+    modelId: string,
+    next: (current: RelayModelProfile | undefined) => RelayModelProfile | undefined,
+  ): void {
+    setRelayProfilesDirty(true);
+    setRelayProfileDrafts((current) => {
+      const updated = next(current[modelId]);
+      if (updated === undefined) {
+        if (!(modelId in current)) return current;
+        const { [modelId]: _dropped, ...rest } = current;
+        return rest;
+      }
+      return { ...current, [modelId]: updated };
+    });
+  }
+
+  // One shape for all three fields: the field setter pins or removes its key,
+  // and an entry with no keys left IS the undeclared state — storing it would
+  // keep the row looking edited after the user emptied every field.
+  function setDraftThinkingLevels(modelId: string, levels: ThinkingLevel[] | undefined): void {
+    updateRelayProfileDraft(modelId, (current) => {
+      if (levels === undefined || levels.length === 0) {
+        if (!current) return current;
+        const { thinkingLevels: _dropped, ...rest } = current;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+      }
+      return { ...(current ?? {}), thinkingLevels: levels };
+    });
+  }
+
+  // Tri-state vision: undefined = Auto (relay/metadata decides), true/false
+  // pin the declaration. The Selector's three options map straight onto this.
+  function setDraftVision(modelId: string, vision: boolean | undefined): void {
+    updateRelayProfileDraft(modelId, (current) => {
+      if (vision === undefined) {
+        if (!current) return current;
+        const { vision: _dropped, ...rest } = current;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+      }
+      return { ...(current ?? {}), vision };
+    });
+  }
+
+  function setDraftContextWindow(modelId: string, contextWindow: number | undefined): void {
+    updateRelayProfileDraft(modelId, (current) => {
+      if (contextWindow === undefined) {
+        if (!current) return current;
+        const { contextWindow: _dropped, ...rest } = current;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+      }
+      return { ...(current ?? {}), contextWindow };
+    });
+  }
+
+  // Compare against what persistence would store: drafts pruned to the
+  // current selection and order-normalized by the same sanitizer the write
+  // path applies, so a reordered-but-equal draft doesn't keep 保存 lit.
+  const savedRelayProfiles = normalizeRelayModelProfiles(
+    pruneRelayModelProfiles(connection.relayModelProfiles, enabledModelIds) ?? {},
+  );
+  const draftedRelayProfiles = normalizeRelayModelProfiles(
+    pruneRelayModelProfiles(relayProfileDrafts, enabledModelIds) ?? {},
+  );
+  const hasRelayProfileChanges = !relayProfilesEqual(draftedRelayProfiles, savedRelayProfiles);
+
+  useEffect(() => {
+    // Slug switch always reseeds AND clears dirty — carrying A's unsaved
+    // declarations onto B would let one save write them into B's document.
+    // A same-slug reload reseeds only while the draft is clean: mid-edit
+    // reloads (another action's props.onChanged) keep the user's typed work.
+    const plan = relayProfileDraftReseedPlan(
+      { slug: relayProfileDraftOwnerRef.current, dirty: relayProfilesDirty },
+      connection.slug,
+    );
+    relayProfileDraftOwnerRef.current = connection.slug;
+    if (plan.reseed) {
+      setRelayProfileDrafts(relayProfileDraftSeed(connection.relayModelProfiles));
+    }
+    if (plan.clearDirty) {
+      setRelayProfilesDirty(false);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [connection.slug, connection.relayModelProfiles, relayProfilesDirty]);
+
+  async function saveRelayProfiles(): Promise<boolean> {
+    // Refuse while the draft still belongs to the previous connection: in the
+    // window between the slug switch rendering and the reseed effect
+    // flushing, 保存 must not hand B this draft.
+    if (relayProfileDraftOwnerRef.current !== connection.slug) return false;
+    const releaseSave = connectionDetailActionGuard.beginExclusive('save-relay-profiles');
+    if (!releaseSave) return false;
+    const lifecycle = connectionDetailLifecycleRef.current;
+    setBusy(true);
+    try {
+      // Send the whole table — the update contract is whole-table replace —
+      // after the write-path sanitizer so a hand-assembled draft degrades the
+      // same way a saved document would.
+      await props.bridge.update(connection.slug, {
+        relayModelProfiles: draftedRelayProfiles ?? null,
+      });
+      if (!isConnectionDetailCurrent(lifecycle)) return true;
+      setRelayProfilesDirty(false);
+      await props.onChanged();
+      return true;
+    } catch (error) {
+      if (!isConnectionDetailCurrent(lifecycle)) return false;
+      toast.error(copy.saveFailed, providerPanelActionErrorMessage(error, locale));
+      return false;
+    } finally {
+      releaseSave();
+      if (isConnectionDetailCurrent(lifecycle)) setBusy(false);
+    }
+  }
+
   async function runTest() {
     const releaseTest = connectionDetailActionGuard.beginExclusive('test');
     if (!releaseTest) return;
@@ -499,6 +637,13 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
     lastTestAtMs,
     save,
     updateEnabledModels,
+    relayProfileDraft: relayProfileDrafts,
+    relayProfilesDirty,
+    hasRelayProfileChanges,
+    setDraftThinkingLevels,
+    setDraftVision,
+    setDraftContextWindow,
+    saveRelayProfiles,
     runTest,
     refreshModels,
     remove,
@@ -558,3 +703,23 @@ function modelListsEqual(left: ModelInfo[], right: ModelInfo[]): boolean {
 function modelIdListsEqual(left: string[], right: string[]): boolean {
   return left.length === right.length && left.every((id, index) => id === right[index]);
 }
+
+function relayProfilesEqual(
+  left: ReturnType<typeof normalizeRelayModelProfiles>,
+  right: ReturnType<typeof normalizeRelayModelProfiles>,
+): boolean {
+  if (left === undefined || right === undefined) return left === right;
+  const leftIds = Object.keys(left);
+  const rightIds = Object.keys(right);
+  if (leftIds.length !== rightIds.length) return false;
+  for (const id of leftIds) {
+    const a = left[id];
+    const b = right[id];
+    if (!a || !b) return false;
+    if (a.vision !== b.vision || a.contextWindow !== b.contextWindow) return false;
+    const al = a.thinkingLevels ?? [];
+    const bl = b.thinkingLevels ?? [];
+    if (al.length !== bl.length || al.some((level, index) => level !== bl[index])) return false;
+  }
+  return true;
+}
diff --git a/apps/desktop/stories/settings/provider-settings.stories.tsx b/apps/desktop/stories/settings/provider-settings.stories.tsx
index 18f3eebede..ec3d2ad7aa 100644
--- a/apps/desktop/stories/settings/provider-settings.stories.tsx
+++ b/apps/desktop/stories/settings/provider-settings.stories.tsx
@@ -160,6 +160,12 @@ function createBridge(input: {
       const updated: LlmConnection = {
         ...current,
         ...patch,
+        // UpdateConnectionInput.relayModelProfiles is tri-state (null clears);
+        // a stored connection never carries null — clear maps to absent.
+        relayModelProfiles:
+          patch.relayModelProfiles === undefined
+            ? current.relayModelProfiles
+            : (patch.relayModelProfiles ?? undefined),
         updatedAt: NOW,
       };
       connections = connections.map((connection) => connection.slug === slug ? updated : connection);
diff --git a/apps/desktop/stories/settings/settings-pages.stories.tsx b/apps/desktop/stories/settings/settings-pages.stories.tsx
index a9506f9c17..f0ba42bdc7 100644
--- a/apps/desktop/stories/settings/settings-pages.stories.tsx
+++ b/apps/desktop/stories/settings/settings-pages.stories.tsx
@@ -92,7 +92,17 @@ const connectionsBridge: ConnectionsBridge = {
   },
   async update(slug, patch) {
     const current = connections.find((c) => c.slug === slug)!;
-    return { ...current, ...patch, updatedAt: NOW };
+    return {
+      ...current,
+      ...patch,
+      // Tri-state relayModelProfiles (null clears) never stores null on a
+      // connection — clear maps to absent.
+      relayModelProfiles:
+        patch.relayModelProfiles === undefined
+          ? current.relayModelProfiles
+          : (patch.relayModelProfiles ?? undefined),
+      updatedAt: NOW,
+    };
   },
   async delete() {
     /* noop */
diff --git a/packages/cli/src/__tests__/connection-target.test.ts b/packages/cli/src/__tests__/connection-target.test.ts
index fc94b6a99f..8da8e3cec2 100644
--- a/packages/cli/src/__tests__/connection-target.test.ts
+++ b/packages/cli/src/__tests__/connection-target.test.ts
@@ -258,6 +258,64 @@ test('ready model choices apply curation and isolate unavailable credentials', a
   );
 });
 
+test('ready model choices carry the thinking levels declared per relay model', async () => {
+  const relay = makeConnection({
+    slug: 'relay',
+    name: 'Relay',
+    providerType: 'openai-compatible',
+    baseUrl: 'https://relay.example/v1',
+    defaultModel: 'reasoning-model',
+    enabledModelIds: ['reasoning-model', 'plain-model'],
+    models: [{ id: 'reasoning-model' }, { id: 'plain-model' }],
+    relayModelProfiles: {
+      'reasoning-model': { thinkingLevels: ['minimal', 'low', 'high', 'max'] },
+    },
+  });
+
+  const choices = await listReadyModelChoices({
+    connectionStore: {
+      list: async () => [relay],
+      getDefault: async () => 'relay',
+    },
+    credentialStore: { getSecret: async () => 'sk-relay' },
+  });
+
+  // The declaration is keyed by model id: the sibling model on the same
+  // relay stays without a thinking menu.
+  assert.deepEqual(
+    choices.map(({ model, thinkingLevels }) => ({ model, thinkingLevels })),
+    [
+      { model: 'reasoning-model', thinkingLevels: ['minimal', 'low', 'high', 'max'] },
+      { model: 'plain-model', thinkingLevels: [] },
+    ],
+  );
+});
+
+test('ready model choices leave thinkingLevels empty for connections without a declaration', async () => {
+  const plain = makeConnection({
+    slug: 'relay',
+    name: 'Relay',
+    providerType: 'openai-compatible',
+    baseUrl: 'https://relay.example/v1',
+    defaultModel: 'plain-model',
+    enabledModelIds: ['plain-model'],
+    models: [{ id: 'plain-model' }],
+  });
+
+  const choices = await listReadyModelChoices({
+    connectionStore: {
+      list: async () => [plain],
+      getDefault: async () => 'relay',
+    },
+    credentialStore: { getSecret: async () => 'sk-relay' },
+  });
+
+  assert.deepEqual(
+    choices.map(({ thinkingLevels }) => thinkingLevels),
+    [[]],
+  );
+});
+
 function storeFor(connection: LlmConnection) {
   return {
     getDefault: async () => connection.slug,
diff --git a/packages/cli/src/connection-target.ts b/packages/cli/src/connection-target.ts
index f7ff7ae67e..b23c9ec1b1 100644
--- a/packages/cli/src/connection-target.ts
+++ b/packages/cli/src/connection-target.ts
@@ -1,6 +1,7 @@
 import { isConnectionReady, type ChatConfigurationReason } from '@maka/core/connection-readiness';
 import type { LlmConnection, ProviderType } from '@maka/core/llm-connections';
 import { connectionEnabledModelIds, PROVIDER_DEFAULTS } from '@maka/core/llm-connections';
+import { thinkingVariantsForConnection } from '@maka/core/model-thinking';
 import {
   isOAuthSubscriptionProvider,
   resolveOAuthSubscriptionTokens,
@@ -144,6 +145,7 @@ export async function listReadyModelChoices(input: {
           model,
           isDefaultConnection: connection.slug === defaultSlug,
           contextWindow: resolveSelectedModelContextWindow(connection, model),
+          thinkingLevels: thinkingVariantsForConnection(connection, model),
         });
       }
     } catch {
diff --git a/packages/cli/src/pi-tui-contracts.ts b/packages/cli/src/pi-tui-contracts.ts
index 0f5c9e03a2..a3252328d2 100644
--- a/packages/cli/src/pi-tui-contracts.ts
+++ b/packages/cli/src/pi-tui-contracts.ts
@@ -1,5 +1,6 @@
 import type { ForeignSessionDigest, ForeignSessionSummary } from '@maka/core/foreign-session';
 import type { ModelInfo, ProviderType } from '@maka/core/llm-connections';
+import type { ThinkingLevel } from '@maka/core/model-thinking';
 import type { GoalTurnAdmission, HostCapabilities, SkillSource } from '@maka/runtime';
 import type { MakaPiTuiTurnLifecycle } from './pi-tui-turn.js';
 
@@ -9,7 +10,16 @@ export interface ModelChoice {
   providerType: ProviderType;
   model: string;
   isDefaultConnection: boolean;
+  /** Maximum context tokens for this model, resolved from the connection or provider catalog. */
   contextWindow?: number;
+  /**
+   * Thinking levels this model exposes. `listReadyModelChoices` always
+   * computes this with the full connection (so an openai-compatible relay's
+   * declared `relayModelProfiles[model].thinkingLevels` are honoured);
+   * optional only so hand-written choice literals stay valid — consumers
+   * must tolerate its absence.
+   */
+  thinkingLevels?: readonly ThinkingLevel[];
 }
 
 export interface OnboardableProvider {
diff --git a/packages/cli/src/pi-tui-runner.ts b/packages/cli/src/pi-tui-runner.ts
index f368f289f0..14d366bb72 100644
--- a/packages/cli/src/pi-tui-runner.ts
+++ b/packages/cli/src/pi-tui-runner.ts
@@ -210,9 +210,14 @@ export async function runMakaPiTui(input: MakaPiTuiInput): Promise<void> {
   let permissionMode = input.permissionMode;
   let orchestrationMode = input.driver.getOrchestrationMode?.() ?? 'default';
   let thinkingLevel: ThinkingLevel | undefined = undefined;
-  let thinkingLevels: readonly ThinkingLevel[] = providerType
-    ? thinkingVariantsForModel(providerType, input.model)
-    : [];
+  // The boot connection's declared capabilities win (an openai-compatible
+  // relay can declare relayModelProfiles[model].thinkingLevels). The
+  // providerType+model metadata variant is the fallback for modelChoices-free
+  // embeddings of the runner.
+  let thinkingLevels: readonly ThinkingLevel[] =
+    input.modelChoices?.find(
+      (choice) => choice.connectionSlug === connectionSlug && choice.model === model,
+    )?.thinkingLevels ?? (providerType ? thinkingVariantsForModel(providerType, model) : []);
   let sessionListScope: 'current' | 'all' = 'current';
   let busy = false;
   let closed = false;
@@ -1264,7 +1269,12 @@ export async function runMakaPiTui(input: MakaPiTuiInput): Promise<void> {
     permissionMode = input.driver.getPermissionMode?.() ?? summary.permissionMode;
     orchestrationMode = summary.orchestrationMode ?? 'default';
     thinkingLevel = summary.thinkingLevel;
-    thinkingLevels = providerType ? thinkingVariantsForModel(providerType, summary.model) : [];
+    // Choice-first: a relay model's user-declared levels live on the ModelChoice;
+    // the metadata fallback serves providers whose variants derive from the
+    // model id alone.
+    thinkingLevels =
+      contextWindowMatch?.thinkingLevels ??
+      (providerType ? thinkingVariantsForModel(providerType, summary.model) : []);
     refreshEditorCwd?.(cwd);
   };
 
@@ -1314,10 +1324,17 @@ export async function runMakaPiTui(input: MakaPiTuiInput): Promise<void> {
   const setModel = async (nextModel: string) => {
     await input.driver.setModel(nextModel);
     model = nextModel;
-    const match = modelChoices?.find((choice) => choice.model === nextModel);
+    // Same-connection switch: scope the choice lookup to the live connection
+    // (another connection may expose the same model id with different
+    // declared thinking levels).
+    const match = modelChoices?.find(
+      (choice) => choice.connectionSlug === connectionSlug && choice.model === nextModel,
+    );
     if (match) modelContextWindow = match.contextWindow;
     thinkingLevel = undefined;
-    thinkingLevels = providerType ? thinkingVariantsForModel(providerType, nextModel) : [];
+    thinkingLevels =
+      match?.thinkingLevels ??
+      (providerType ? thinkingVariantsForModel(providerType, nextModel) : []);
     state.entries.push({
       kind: 'notice',
       level: 'info',
@@ -1335,7 +1352,8 @@ export async function runMakaPiTui(input: MakaPiTuiInput): Promise<void> {
     providerType = choice.providerType;
     modelContextWindow = choice.contextWindow;
     thinkingLevel = undefined;
-    thinkingLevels = thinkingVariantsForModel(choice.providerType, choice.model);
+    thinkingLevels =
+      choice.thinkingLevels ?? thinkingVariantsForModel(choice.providerType, choice.model);
     state.entries.push({
       kind: 'notice',
       level: 'info',
diff --git a/packages/cli/src/runtime-bootstrap.ts b/packages/cli/src/runtime-bootstrap.ts
index 05b886cccd..c9c8f5e7ca 100644
--- a/packages/cli/src/runtime-bootstrap.ts
+++ b/packages/cli/src/runtime-bootstrap.ts
@@ -86,7 +86,7 @@ import { resolveStorageRoot } from '@maka/storage/root-authority';
 import { resolveWorkspaceIdentity } from '@maka/storage/workspace-identity';
 import { fetchProviderModels } from '@maka/runtime';
 import { createApiKeyOnboardingSurface } from './onboarding.js';
-import { isActiveShellRunStatus, resolveModelVisionSupport } from '@maka/core';
+import { relayModelProfile, isActiveShellRunStatus, resolveModelVisionSupport } from '@maka/core';
 import type { ReadySessionTarget } from './connection-target.js';
 import {
   listReadyModelChoices,
@@ -748,6 +748,7 @@ export async function createMakaCliRuntimeContext(
         ready.connection.providerType,
         ready.connection.models,
         ready.model,
+        relayModelProfile(ready.connection, ready.model)?.vision,
       ),
       readAttachmentBytes: createAttachmentByteReader({ artifactStore, sessionId: ctx.sessionId }),
       loadHistoryCompact: (event) => loadHistoryCompactBlocksFromArtifacts(artifactStore, event),
diff --git a/packages/core/src/__tests__/chat-model-choice.test.ts b/packages/core/src/__tests__/chat-model-choice.test.ts
index 59271c72ea..b3c6b7f726 100644
--- a/packages/core/src/__tests__/chat-model-choice.test.ts
+++ b/packages/core/src/__tests__/chat-model-choice.test.ts
@@ -50,3 +50,29 @@ test('redacts OAuth names and normalizes legacy Codex inventory', () => {
   assert.equal(choice?.connectionName, undefined);
   assert.equal(choice?.isDefault, true);
 });
+
+test('openai-compatible relay choices carry the thinking levels declared per model', () => {
+  const [declared, undeclared] = buildChatModelChoices([
+    connection({
+      slug: 'relay-think',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay.example/v1',
+      defaultModel: 'my-reasoning-model',
+      enabledModelIds: ['my-reasoning-model'],
+      models: [{ id: 'my-reasoning-model' }],
+      relayModelProfiles: {
+        'my-reasoning-model': { thinkingLevels: ['low', 'medium', 'high'] },
+      },
+    }),
+    connection({
+      slug: 'relay-plain',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay2.example/v1',
+      defaultModel: 'my-plain-model',
+      enabledModelIds: ['my-plain-model'],
+      models: [{ id: 'my-plain-model' }],
+    }),
+  ]);
+  assert.deepEqual(declared?.thinkingLevels, ['low', 'medium', 'high']);
+  assert.deepEqual(undeclared?.thinkingLevels, []);
+});
diff --git a/packages/core/src/__tests__/model-metadata.test.ts b/packages/core/src/__tests__/model-metadata.test.ts
index 0cac0c5026..f018b03f99 100644
--- a/packages/core/src/__tests__/model-metadata.test.ts
+++ b/packages/core/src/__tests__/model-metadata.test.ts
@@ -80,6 +80,39 @@ describe('model-metadata vision capability', () => {
     assert.equal(resolveModelVisionSupport('openai', granted, 'some-unlisted-model'), true);
   });
 
+  it('lets a user declaration outrank every other signal, in both directions', () => {
+    // Declared vision wins over stored capabilities, generated metadata, and
+    // the provider default — the relay user knows what the backing model is,
+    // none of the inferred sources can.
+    const stored: ModelInfo[] = [
+      { id: 'my-reasoner', capabilities: { vision: true } },
+      { id: 'claude-opus-6', capabilities: { vision: true } },
+    ];
+    assert.equal(
+      resolveModelVisionSupport('openai-compatible', stored, 'my-reasoner', false),
+      false,
+    );
+    assert.equal(
+      resolveModelVisionSupport('openai-compatible', stored, 'claude-opus-6', false),
+      false,
+    );
+    assert.equal(
+      resolveModelVisionSupport('openai-compatible', undefined, 'some-unlisted-model', true),
+      true,
+    );
+    // anthropic defaults claude-* to vision; an explicit declaration still wins.
+    assert.equal(resolveModelVisionSupport('anthropic', undefined, 'claude-opus-6', false), false);
+    // undefined declaration means "no opinion": the old chain decides.
+    assert.equal(
+      resolveModelVisionSupport('openai-compatible', stored, 'my-reasoner', undefined),
+      true,
+    );
+    assert.equal(
+      resolveModelVisionSupport('openai-compatible', undefined, 'some-unlisted-model', undefined),
+      false,
+    );
+  });
+
   it('publishes the Kimi Coding Plan K3 limits and effort levels from models.dev', () => {
     assert.deepEqual(lookupModelMetadata('kimi-coding-plan', 'k3'), {
       displayName: 'Kimi K3',
diff --git a/packages/core/src/__tests__/model-thinking.test.ts b/packages/core/src/__tests__/model-thinking.test.ts
index 8539ec6bc2..242b91b2f9 100644
--- a/packages/core/src/__tests__/model-thinking.test.ts
+++ b/packages/core/src/__tests__/model-thinking.test.ts
@@ -1,10 +1,16 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import {
+  type ConnectionThinkingContext,
+  DECLARABLE_RELAY_THINKING_LEVELS,
+  normalizeRelayModelProfiles,
+  relayModelProfile,
+  resolveThinkingLevel,
   THINKING_LEVELS,
   deriveThinkingChoices,
   isThinkingLevel,
   thinkingOptionsForModel,
+  thinkingVariantsForConnection,
   thinkingVariantsForModel,
 } from '../model-thinking.js';
 
@@ -15,7 +21,7 @@ test('thinking choices are filtered, ordered, and expose off only with a real wi
   );
   assert.deepEqual([...deriveThinkingChoices({ toggle: true })], []);
   assert.deepEqual(
-    [...deriveThinkingChoices({ toggle: true, offBehavior: 'google-thinking-budget-zero' })],
+    [...deriveThinkingChoices({ toggle: true, offBehavior: 'anthropic-thinking-disabled' })],
     ['off'],
   );
   assert.deepEqual([...deriveThinkingChoices(undefined)], []);
@@ -83,3 +89,192 @@ test('thinking-level guard accepts only the closed display vocabulary', () => {
     assert.equal(isThinkingLevel(value), false);
   }
 });
+
+test('declarable relay levels are every intensity tier but off', () => {
+  // `off` is a disable-wire encoding (reasoning_effort 'none'), not an
+  // intensity tier — a hybrid UI/data contract keeps it out of declarations.
+  assert.deepEqual(
+    [...DECLARABLE_RELAY_THINKING_LEVELS],
+    ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+  );
+  assert.deepEqual(normalizeRelayModelProfiles({ m: { thinkingLevels: ['off', 'low'] } }), {
+    m: { thinkingLevels: ['low'] },
+  });
+  assert.equal(normalizeRelayModelProfiles({ m: { thinkingLevels: ['off'] } }), undefined);
+  const declaredOff = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: { m: { thinkingLevels: ['off', 'low'] } },
+  } as const;
+  assert.deepEqual([...thinkingVariantsForConnection(declaredOff, 'm')], ['low']);
+});
+
+test('relay profiles declare thinking levels per model, precisely', () => {
+  // A declaration is exactly the subset the user ticked — no default set is
+  // ever invented — and display order is restored on read.
+  const connection = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: { reasoner: { thinkingLevels: ['max', 'high'] } },
+  } as const;
+  assert.deepEqual(relayModelProfile(connection, 'reasoner')?.thinkingLevels, ['high', 'max']);
+  assert.deepEqual([...thinkingVariantsForConnection(connection, 'reasoner')], ['high', 'max']);
+  // A sibling model on the same relay without a declaration sees no menu —
+  // the granularity is the model, not the connection.
+  assert.deepEqual([...thinkingVariantsForConnection(connection, 'plain-instruct')], []);
+});
+
+test('relayModelProfile returns undefined without a usable declaration', () => {
+  const connection = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: {
+      empty: {},
+      junk: 'nope',
+      badLevels: { thinkingLevels: 'low' },
+      unknownLevels: { thinkingLevels: ['turbo'] },
+      offOnly: { thinkingLevels: ['off'] },
+      badVision: { vision: 'yes' },
+    },
+  } as unknown as ConnectionThinkingContext;
+  for (const modelId of [
+    'missing',
+    'empty',
+    'junk',
+    'badLevels',
+    'unknownLevels',
+    'offOnly',
+    'badVision',
+  ]) {
+    assert.equal(relayModelProfile(connection, modelId), undefined, modelId);
+  }
+});
+
+test('relayModelProfile normalizes order, keeps explicit vision:false, and bounds context windows', () => {
+  const connection = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: {
+      reasoner: { thinkingLevels: ['high', 'low', 'turbo'], vision: false },
+      visual: { vision: true },
+    },
+  } as unknown as ConnectionThinkingContext;
+  // Declared levels keep display order; unknown values are dropped;
+  // vision:false is a meaningful DISABLE, distinct from absence (Auto).
+  assert.deepEqual(relayModelProfile(connection, 'reasoner'), {
+    thinkingLevels: ['low', 'high'],
+    vision: false,
+  });
+  assert.deepEqual(relayModelProfile(connection, 'visual'), { vision: true });
+
+  const windowed = (contextWindow: unknown) =>
+    ({
+      providerType: 'openai-compatible' as const,
+      relayModelProfiles: { m: { contextWindow } },
+    }) as unknown as ConnectionThinkingContext;
+  assert.deepEqual(relayModelProfile(windowed(128_000), 'm'), { contextWindow: 128_000 });
+  // Unusable values degrade to "no declaration", not to a lie.
+  for (const bad of [0, -1, 1.5, 2 ** 60, '128000', null]) {
+    assert.equal(relayModelProfile(windowed(bad), 'm'), undefined, JSON.stringify(bad));
+  }
+});
+
+test('relayModelProfile gates declarations to openai-compatible relays', () => {
+  const profiles = { m: { vision: true, contextWindow: 64_000 } };
+  assert.deepEqual(
+    relayModelProfile({ providerType: 'openai-compatible', relayModelProfiles: profiles }, 'm'),
+    { vision: true, contextWindow: 64_000 },
+  );
+  // The same table on a non-relay connection is inert: metadata rules.
+  for (const providerType of ['anthropic', 'openai'] as const) {
+    assert.equal(relayModelProfile({ providerType, relayModelProfiles: profiles }, 'm'), undefined);
+  }
+});
+
+test('normalizeRelayModelProfiles sanitizes write-side tables', () => {
+  const sanitized = normalizeRelayModelProfiles({
+    reasoner: { thinkingLevels: ['high', 'low', 'turbo'], vision: true, contextWindow: 200_000 },
+    empty: {},
+    junk: 'not-an-entry',
+    huge: { contextWindow: 2 ** 60 },
+    '': { vision: true },
+    [`${'x'.repeat(513)}`]: { vision: true },
+  });
+  assert.deepEqual(sanitized, {
+    reasoner: { thinkingLevels: ['low', 'high'], vision: true, contextWindow: 200_000 },
+  });
+  assert.equal(normalizeRelayModelProfiles({}), undefined);
+  assert.equal(normalizeRelayModelProfiles(undefined), undefined);
+  assert.equal(normalizeRelayModelProfiles({ junk: 'not-an-entry' }), undefined);
+  // Relay-supplied ids may be prototype keys; the table defines them as own
+  // data properties or the entries would vanish on the next enumeration.
+  const hostile = normalizeRelayModelProfiles(
+    JSON.parse('{"__proto__":{"vision":true},"toString":{"contextWindow":64}}'),
+  );
+  assert.deepEqual(Object.keys(hostile ?? {}).sort(), ['__proto__', 'toString']);
+  assert.equal(JSON.stringify(hostile).includes('"__proto__"'), true);
+});
+
+test('resolveThinkingLevel discards levels the model does not offer', () => {
+  const relay = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: { m: { thinkingLevels: ['off', 'low'] } },
+  } as const;
+  assert.equal(resolveThinkingLevel(relay, 'm', 'low'), 'low');
+  // `off` is not declarable for relays: a stray entry degrades to absent.
+  assert.equal(resolveThinkingLevel(relay, 'm', 'off'), undefined);
+  assert.equal(resolveThinkingLevel(relay, 'm', 'max'), undefined);
+  assert.equal(resolveThinkingLevel(relay, 'm', undefined), undefined);
+  assert.equal(resolveThinkingLevel({ providerType: 'openai' }, 'gpt-5.5', 'xhigh'), 'xhigh');
+});
+
+test('openai-compatible thinking variants are declared per model', () => {
+  const connection = {
+    providerType: 'openai-compatible',
+    relayModelProfiles: { reasoner: { thinkingLevels: ['high', 'low', 'turbo'] } },
+  } as unknown as ConnectionThinkingContext;
+  assert.deepEqual([...thinkingVariantsForConnection(connection, 'reasoner')], ['low', 'high']);
+  // A sibling model on the same relay without a declaration sees no menu —
+  // the granularity is the model, not the connection.
+  assert.deepEqual([...thinkingVariantsForConnection(connection, 'plain-instruct')], []);
+});
+
+test('openai-compatible connections without a declaration fall back to metadata variants', () => {
+  for (const relayModelProfiles of [
+    undefined,
+    {},
+    { 'deepseek-v4-flash': {} },
+    { 'deepseek-v4-flash': { thinkingLevels: [] } },
+    { 'deepseek-v4-flash': { thinkingLevels: 'low' } },
+    { 'deepseek-v4-flash': { thinkingLevels: ['turbo'] } },
+  ]) {
+    assert.deepEqual(
+      [
+        ...thinkingVariantsForConnection(
+          {
+            providerType: 'openai-compatible',
+            relayModelProfiles,
+          } as unknown as ConnectionThinkingContext,
+          'deepseek-v4-flash',
+        ),
+      ],
+      [],
+      JSON.stringify(relayModelProfiles),
+    );
+  }
+  // Non-custom providers keep metadata-derived variants: a profiles table
+  // riding along on their connection is inert.
+  assert.deepEqual(
+    [
+      ...thinkingVariantsForConnection(
+        {
+          providerType: 'openai',
+          relayModelProfiles: { 'gpt-5.5': { thinkingLevels: ['off'] } },
+        },
+        'gpt-5.5',
+      ),
+    ],
+    ['off', 'low', 'medium', 'high', 'xhigh'],
+  );
+});
+
+// Reasoning replay has no toggle: DeepSeek-like relays require
+// reasoning_content in tool-call history (400 otherwise), and other relays
+// ignore it, so the runtime replays unconditionally. That contract is
+// enforced per provider by the runtime provider-contract matrix, not here.
diff --git a/packages/core/src/__tests__/runtime-policy-codec.test.ts b/packages/core/src/__tests__/runtime-policy-codec.test.ts
index 4725be166a..869bd6db2c 100644
--- a/packages/core/src/__tests__/runtime-policy-codec.test.ts
+++ b/packages/core/src/__tests__/runtime-policy-codec.test.ts
@@ -4,7 +4,10 @@ import {
   createDefaultRuntimePolicy,
   decodeCanonicalConnectionCatalogEntry,
   decodeCanonicalRuntimePolicy,
+  decodeRelayModelProfilesTable,
   normalizeCreateCatalogConnectionInput,
+  normalizeConnectionCatalogEntryUpdate,
+  normalizeConnectionCatalogEntryUpdateForProvider,
   normalizeConnectionModelDiscoveryResult,
   normalizeRuntimePolicyMutation,
   normalizeSetCredentialInput,
@@ -66,6 +69,170 @@ test('normalizes catalog inputs while canonical entries reject noncanonical endp
   );
 });
 
+test('relay model profiles round-trip canonical entries and drafts, strictly', () => {
+  const table = {
+    'relay-reasoner': {
+      thinkingLevels: ['minimal', 'low'],
+      vision: true,
+      contextWindow: 128_000,
+    },
+  };
+  const draft = normalizeCreateCatalogConnectionInput({
+    expectedCatalogRevision: 0,
+    connection: {
+      slug: 'relay',
+      name: 'Relay',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay.example/v1',
+      enabled: true,
+      enabledModelIds: ['relay-reasoner'],
+      relayModelProfiles: table,
+    },
+  });
+  assert.deepEqual(draft.connection.relayModelProfiles, table);
+  // The canonical path re-decodes the same table (entry = draft + identity).
+  const entry = decodeCanonicalConnectionCatalogEntry({
+    ...draft.connection,
+    connectionId: '123e4567-e89b-42d3-a456-426614174000',
+    revision: 1,
+    models: [],
+  });
+  assert.deepEqual(entry.relayModelProfiles, table);
+
+  // An empty table is never a state: drafts omit the key, updates read it as
+  // the same clear-instruction `null` gives.
+  const emptyDraft = normalizeCreateCatalogConnectionInput({
+    expectedCatalogRevision: 0,
+    connection: {
+      slug: 'relay',
+      name: 'Relay',
+      providerType: 'openai-compatible',
+      enabled: true,
+      enabledModelIds: [],
+      relayModelProfiles: {},
+    },
+  });
+  assert.equal(emptyDraft.connection.relayModelProfiles, undefined);
+  const emptyUpdate = normalizeConnectionCatalogEntryUpdate({
+    name: 'Relay',
+    enabled: true,
+    enabledModelIds: [],
+    relayModelProfiles: {},
+  });
+  assert.equal(emptyUpdate.relayModelProfiles, null);
+
+  // The update input is tri-state: null (or the equivalent {}) clears, a
+  // table replaces, and an ABSENT key means untouched — absent must never
+  // materialize into a clear, which is what keeps profile-blind writers
+  // safe.
+  const update = normalizeConnectionCatalogEntryUpdate({
+    name: 'Relay',
+    enabled: true,
+    enabledModelIds: [],
+    relayModelProfiles: null,
+  });
+  assert.equal(update.relayModelProfiles, null);
+  const absentUpdate = normalizeConnectionCatalogEntryUpdate({
+    name: 'Relay',
+    enabled: true,
+    enabledModelIds: [],
+  });
+  assert.deepEqual(absentUpdate, {
+    name: 'Relay',
+    enabled: true,
+    enabledModelIds: [],
+  });
+
+  // Profiles are a relay-only feature: non-empty tables on other providers
+  // are rejected at the write seam (null/absent stay legal for cleanup).
+  assert.throws(
+    () =>
+      normalizeCreateCatalogConnectionInput({
+        expectedCatalogRevision: 0,
+        connection: {
+          slug: 'not-a-relay',
+          name: 'Other',
+          providerType: 'openai',
+          enabled: true,
+          enabledModelIds: ['relay-reasoner'],
+          relayModelProfiles: table,
+        },
+      }),
+    RuntimePolicyDomainDecodeError,
+  );
+  assert.throws(
+    () =>
+      normalizeConnectionCatalogEntryUpdateForProvider(
+        {
+          name: 'Other',
+          enabled: true,
+          enabledModelIds: ['relay-reasoner'],
+          relayModelProfiles: table,
+        },
+        'anthropic',
+      ),
+    RuntimePolicyDomainDecodeError,
+  );
+  assert.equal(
+    normalizeConnectionCatalogEntryUpdateForProvider(
+      { name: 'Other', enabled: true, enabledModelIds: [], relayModelProfiles: null },
+      'anthropic',
+    ).relayModelProfiles,
+    null,
+  );
+
+  // The subset invariant: profiles exist only for ENABLED models. The store
+  // prunes profiles of deselected models, so a key outside the set marks a
+  // document the store never wrote.
+  assert.throws(
+    () =>
+      normalizeConnectionCatalogEntryUpdate({
+        name: 'Relay',
+        enabled: true,
+        enabledModelIds: ['relay-reasoner'],
+        relayModelProfiles: { 'disabled-model': { vision: true } },
+      }),
+    RuntimePolicyDomainDecodeError,
+  );
+
+  // Model ids are relay-supplied strings; __proto__/constructor/toString
+  // must survive the table as ordinary own keys — the decode builds the
+  // table with fromEntries precisely so '__proto__' cannot poison the result
+  // object's prototype and quietly drop the entry.
+  const hostileTable = decodeRelayModelProfilesTable(
+    // An object literal could not even express `__proto__` as an own key —
+    // the deserialized document is the realistic carrier of a hostile id.
+    JSON.parse(
+      '{"__proto__":{"vision":true},"constructor":{"vision":false},"toString":{"contextWindow":8192}}',
+    ),
+    ['__proto__', 'constructor', 'toString'],
+  );
+  assert.deepEqual(Object.keys(hostileTable).sort(), ['__proto__', 'constructor', 'toString']);
+  assert.equal(JSON.stringify(hostileTable).includes('"__proto__"'), true);
+
+  // Strictness: writers emit normalized tables, so anything else is corrupt.
+  for (const bad of [
+    'nope',
+    [],
+    { m: { thinkingLevels: ['turbo'] } }, // unknown level
+    { m: { thinkingLevels: ['off'] } }, // disable wire, not a declarable tier
+    { m: { thinkingLevels: ['low', 'low'] } }, // duplicate
+    { m: { thinkingLevels: [] } }, // empty level list
+    { m: {} }, // declares nothing
+    { m: { vision: 'yes' } },
+    { m: { contextWindow: 0 } },
+    { m: { contextWindow: 1.5 } },
+    { m: { contextWindow: 2 ** 60 } }, // not within 1..MAX_SAFE_INTEGER
+    { m: { vision: true, extra: 1 } }, // unknown key in the entry
+  ]) {
+    assert.throws(
+      () => decodeRelayModelProfilesTable(bad, ['m']),
+      RuntimePolicyDomainDecodeError,
+      JSON.stringify(bad),
+    );
+  }
+});
+
 test('normalizes exact bounded model discovery results', () => {
   assert.deepEqual(
     normalizeConnectionModelDiscoveryResult({
diff --git a/packages/core/src/chat-model-choice.ts b/packages/core/src/chat-model-choice.ts
index 488b16dd38..430188ca5d 100644
--- a/packages/core/src/chat-model-choice.ts
+++ b/packages/core/src/chat-model-choice.ts
@@ -1,6 +1,6 @@
 import { normalizeOpenAiCodexConnection } from './connection-readiness.js';
 import { buildConnectionModelCatalogEntries } from './model-catalog.js';
-import { thinkingVariantsForModel, type ThinkingLevel } from './model-thinking.js';
+import { thinkingVariantsForConnection, type ThinkingLevel } from './model-thinking.js';
 import {
   CODEX_SUBSCRIPTION_UNSUPPORTED_CHATGPT_MODELS,
   PROVIDER_DEFAULTS,
@@ -66,7 +66,7 @@ export function buildChatModelChoices(connections: readonly LlmConnection[]): Ch
         label: entry.displayName?.trim() || entry.id,
         ...(provider.authKind === 'oauth_token' ? {} : { connectionName: connection.name }),
         isDefault: entry.isDefault,
-        thinkingLevels: thinkingVariantsForModel(connection.providerType, entry.id),
+        thinkingLevels: thinkingVariantsForConnection(connection, entry.id),
       });
     }
   }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 15d0e04b55..aade53f3a7 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -398,10 +398,21 @@ export {
 } from './tool-result-record-schema.js';
 
 // model-thinking.ts
-export type { ThinkingLevel } from './model-thinking.js';
+export type {
+  ConnectionThinkingContext,
+  RelayModelProfile,
+  RelayModelProfiles,
+  ThinkingLevel,
+} from './model-thinking.js';
 export {
+  DECLARABLE_RELAY_THINKING_LEVELS,
+  normalizeRelayModelProfiles,
+  pruneRelayModelProfiles,
+  relayModelProfile,
   THINKING_LEVELS,
   isThinkingLevel,
+  resolveThinkingLevel,
+  thinkingVariantsForConnection,
   thinkingVariantsForModel,
 } from './model-thinking.js';
 
diff --git a/packages/core/src/llm-connections.ts b/packages/core/src/llm-connections.ts
index e13a329949..255607c61f 100644
--- a/packages/core/src/llm-connections.ts
+++ b/packages/core/src/llm-connections.ts
@@ -6,6 +6,7 @@
  */
 
 import type { BackendKind } from './session.js';
+import type { RelayModelProfiles } from './model-thinking.js';
 import { CODEX_SUBSCRIPTION_UNSUPPORTED_CHATGPT_MODELS } from './codex-model-compatibility.js';
 import {
   CATALOG_PROVIDER_TYPES,
@@ -86,6 +87,20 @@ export interface RuntimeExecutionConnection {
   baseUrl?: string;
   defaultModel: string;
   models?: ModelInfo[];
+  /**
+   * Per-model user declarations for an `openai-compatible` relay: the facts
+   * (offered thinking levels, vision enable/disable, context window) that
+   * neither the relay's /models report nor built-in metadata can decide
+   * (see `RelayModelProfile` in `model-thinking.ts`). First-class and typed —
+   * relay models are unknown to metadata and a catalog refresh rewrites
+   * `models[]` rows, so declarations live next to the user-edited fields.
+   * Invariants enforced at store boundaries: only `openai-compatible`
+   * connections carry profiles, and only for ids in `enabledModelIds`
+   * (disabling a model deletes its profile).
+   */
+  relayModelProfiles?: RelayModelProfiles;
+  /** Free-form, non-secret per-connection data; nothing reads a key unless it is shaped for the connection's provider type. */
+  extras?: Record<string, unknown>;
 }
 
 export interface LlmConnection extends RuntimeExecutionConnection {
@@ -103,7 +118,6 @@ export interface LlmConnection extends RuntimeExecutionConnection {
   lastTestMessage?: string;
   createdAt: number;
   updatedAt: number;
-  extras?: Record<string, unknown>;
 }
 
 /**
@@ -496,6 +510,7 @@ export interface CreateConnectionInput {
   /** When omitted, falls back to the default model alone. */
   enabledModelIds?: string[];
   apiKey?: string;
+  relayModelProfiles?: RelayModelProfiles;
   extras?: Record<string, unknown>;
 }
 
@@ -512,6 +527,12 @@ export interface UpdateConnectionInput {
   lastTestStatus?: ConnectionLastTestStatus;
   lastTestAt?: string;
   lastTestMessage?: string;
+  /**
+   * Replace the whole relay profiles table: absent leaves it untouched,
+   * `null` clears it outright, a table replaces it (with the usual rules —
+   * only `openai-compatible`, only for `enabledModelIds`).
+   */
+  relayModelProfiles?: RelayModelProfiles | null;
   extras?: Record<string, unknown>;
 }
 
diff --git a/packages/core/src/model-metadata.ts b/packages/core/src/model-metadata.ts
index 0fd33a1d1f..d6bc851c23 100644
--- a/packages/core/src/model-metadata.ts
+++ b/packages/core/src/model-metadata.ts
@@ -160,11 +160,14 @@ const VISION_BY_DEFAULT_PROVIDERS: ReadonlySet<ProviderType> = new Set<ProviderT
 /**
  * Resolve whether a model accepts image input for the send path.
  *
- * Stored `connection.models` win when they declare `vision` explicitly
- * (provider-fetched facts). But `model-fetcher` stores bare `{ id }` entries
- * for many providers, and older connections predate any enrichment — so when
- * `vision` is unknown we fall back to the generated models.dev snapshot and
- * access-path-specific in-repo overrides.
+ * A user declaration (`declaredVision`, from the relay connection's
+ * `relayModelProfiles[modelId].vision`) wins over everything below:
+ * for custom relays the user is the only one who actually knows the backing
+ * model. Absent a declaration, stored `connection.models` win when they
+ * declare `vision` explicitly (provider-fetched facts). But `model-fetcher`
+ * stores bare `{ id }` entries for many providers, and older connections
+ * predate any enrichment — so when `vision` is unknown we fall back to the
+ * generated models.dev snapshot and access-path-specific in-repo overrides.
  *
  * Unknown then resolves to false — the send path stays fail-closed for
  * text-only models — with one exception: an unlisted Claude on one of
@@ -176,7 +179,9 @@ export function resolveModelVisionSupport(
   providerType: ProviderType,
   models: readonly ModelInfo[] | undefined,
   modelId: string,
+  declaredVision?: boolean,
 ): boolean {
+  if (declaredVision !== undefined) return declaredVision;
   const stored = models?.find((entry) => entry.id === modelId);
   if (stored?.capabilities?.vision !== undefined) {
     return stored.capabilities.vision === true;
diff --git a/packages/core/src/model-thinking.ts b/packages/core/src/model-thinking.ts
index bdfe826c6d..36f7938ae3 100644
--- a/packages/core/src/model-thinking.ts
+++ b/packages/core/src/model-thinking.ts
@@ -37,6 +37,20 @@ export const THINKING_LEVELS: readonly ThinkingLevel[] = [
   'max',
 ];
 
+/**
+ * The levels a generic-relay declaration may hold — the vocabulary the
+ * settings surfaces offer and the one the data layer admits. `off` is the
+ * sole exclusion: it is not an intensity tier but a *disable* wire
+ * (`reasoning_effort: 'none'`), and no generic relay is presumed to honor
+ * that encoding; built-in providers that support it get `off` from their own
+ * metadata instead. `minimal` and every effort tier above are pure
+ * intensity values — the user declaring them is the authority on what the
+ * relay accepts.
+ */
+export const DECLARABLE_RELAY_THINKING_LEVELS: readonly ThinkingLevel[] = THINKING_LEVELS.filter(
+  (level) => level !== 'off',
+);
+
 export function isThinkingLevel(value: unknown): value is ThinkingLevel {
   return typeof value === 'string' && (THINKING_LEVELS as readonly string[]).includes(value);
 }
@@ -86,6 +100,175 @@ export function deriveThinkingChoices(
   return THINKING_LEVELS.filter((level) => choices.has(level));
 }
 
+/**
+ * One model behind an `openai-compatible` relay, as declared by the user:
+ * the facts neither the relay's /models report nor built-in metadata can be
+ * trusted to know. Every field is independent, and every ABSENT field means
+ * "Auto" — the /models report and the metadata chain decide. The single
+ * exception in shape, not spirit, is `vision: false`: an explicit DISABLE
+ * that overrides Auto, because the runtime would otherwise believe a vision
+ * report the relay may emit regardless.
+ *
+ * Profiles live on the connection as a first-class typed field
+ * (`relayModelProfiles`, keyed by model id): relay models are unknown to
+ * `model-metadata.ts` and a catalog refresh rewrites `models[]` rows, so
+ * declarations sit next to the user-edited connection fields. Two invariants
+ * are enforced at the store boundaries — profiles exist only for
+ * `openai-compatible` connections, and only for models in `enabledModelIds`
+ * (disabling a model deletes its profile).
+ */
+export interface RelayModelProfile {
+  readonly thinkingLevels?: readonly ThinkingLevel[];
+  readonly vision?: boolean;
+  readonly contextWindow?: number;
+}
+
+export type RelayModelProfiles = Readonly<Record<string, RelayModelProfile>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeRelayModelProfile(entry: unknown): RelayModelProfile | undefined {
+  if (!isRecord(entry)) return undefined;
+  const declared: {
+    thinkingLevels?: readonly ThinkingLevel[];
+    vision?: boolean;
+    contextWindow?: number;
+  } = {};
+  if (Array.isArray(entry.thinkingLevels)) {
+    // Declared levels are filtered to the declarable vocabulary, not merely
+    // the level vocabulary: `off` is a disable-wire encoding no generic
+    // relay is presumed to speak, and a declaration table has no business
+    // carrying it. The codec rejects it in persisted documents for the same
+    // reason; normalize silently drops it because it also sanitizes input
+    // that never passed a validator (settings drafts, hand-edited tables).
+    const declaredSet = new Set(
+      entry.thinkingLevels.filter(
+        (level): level is ThinkingLevel =>
+          isThinkingLevel(level) &&
+          (DECLARABLE_RELAY_THINKING_LEVELS as readonly ThinkingLevel[]).includes(level),
+      ),
+    );
+    if (declaredSet.size > 0) {
+      declared.thinkingLevels = DECLARABLE_RELAY_THINKING_LEVELS.filter((level) =>
+        declaredSet.has(level),
+      );
+    }
+  }
+  if (typeof entry.vision === 'boolean') declared.vision = entry.vision;
+  // Safe-integer, matching the store codec's 1..MAX_SAFE_INTEGER bound: a
+  // value that normalizes here must never be rejected by the write it feeds.
+  if (
+    typeof entry.contextWindow === 'number' &&
+    Number.isSafeInteger(entry.contextWindow) &&
+    entry.contextWindow > 0
+  ) {
+    declared.contextWindow = entry.contextWindow;
+  }
+  return Object.keys(declared).length > 0 ? (declared as RelayModelProfile) : undefined;
+}
+
+/**
+ * Write-side sanitation for a whole profiles table (settings drafts, config
+ * imports): every entry passes the same filter the read seam applies,
+ * over-long/empty model ids are dropped (the codec bounds ids the same way),
+ * and the result is `undefined` when nothing usable remains so callers can
+ * omit the field instead of storing an empty table. fromEntries, not
+ * `table[modelId] = profile` on a `{}`: relay-supplied ids may be prototype
+ * keys, and literal assignment would poison the prototype instead of storing
+ * the entry.
+ */
+export function normalizeRelayModelProfiles(
+  table: unknown,
+): Record<string, RelayModelProfile> | undefined {
+  if (!isRecord(table)) return undefined;
+  const parsed: [string, RelayModelProfile][] = [];
+  for (const [modelId, entry] of Object.entries(table)) {
+    if (modelId.length === 0 || modelId.length > 512) continue;
+    const declared = normalizeRelayModelProfile(entry);
+    if (declared) parsed.push([modelId, declared]);
+  }
+  return parsed.length > 0 ? Object.fromEntries(parsed) : undefined;
+}
+
+/**
+ * Restore the `keys(profiles) ⊆ enabledModelIds` invariant after a selection
+ * change that left the table untouched: profiles for models the user just
+ * disabled are dropped rather than kept stale. Returns `undefined` for an
+ * empty remainder so the recycled state reads as "no profiles", never "{}".
+ */
+export function pruneRelayModelProfiles(
+  table: RelayModelProfiles | undefined,
+  enabledModelIds: readonly string[],
+): RelayModelProfiles | undefined {
+  if (table === undefined) return undefined;
+  const kept = Object.fromEntries(
+    Object.entries(table).filter(([modelId]) => enabledModelIds.includes(modelId)),
+  );
+  return Object.keys(kept).length > 0 ? kept : undefined;
+}
+
+/**
+ * Minimal connection shape the connection-aware helpers below need. Kept
+ * structural so callers holding either `LlmConnection` or a partial view can
+ * pass it through without widening runtime connection types.
+ */
+export interface ConnectionThinkingContext {
+  readonly providerType: ProviderType;
+  readonly relayModelProfiles?: RelayModelProfiles;
+}
+
+/**
+ * The one gated read seam for relay profiles. Profiles are an
+ * `openai-compatible` feature — on every other provider the metadata chain
+ * is the truth — and thinking, vision, and context window reads all enter
+ * through here so the gate cannot leak. Entries ride through
+ * `normalizeRelayModelProfile` so even a hand-edited local file degrades to
+ * Auto instead of trusting a malformed field.
+ */
+export function relayModelProfile(
+  connection: ConnectionThinkingContext,
+  modelId: string,
+): RelayModelProfile | undefined {
+  if (connection.providerType !== 'openai-compatible') return undefined;
+  return normalizeRelayModelProfile(connection.relayModelProfiles?.[modelId]);
+}
+
+/**
+ * `openai-compatible` connections declare thinking support **per model** via
+ * `relayModelProfiles[modelId].thinkingLevels` — a relay may front a
+ * DeepSeek-family reasoner and a plain instruct model side by side, so the
+ * declaration granularity is the model, not the connection. Without a usable
+ * declaration for that model every provider (including relays) falls through
+ * to the metadata-derived variants.
+ */
+export function thinkingVariantsForConnection(
+  connection: ConnectionThinkingContext,
+  modelId: string,
+): readonly ThinkingLevel[] {
+  const declared = relayModelProfile(connection, modelId)?.thinkingLevels;
+  if (declared) return declared;
+  return thinkingVariantsForModel(connection.providerType, modelId);
+}
+
+/**
+ * Discard-semantics gate: returns the level when the model offers it,
+ * `undefined` otherwise. Callers that must *reject* a bad level (IPC/session
+ * boundaries with an error channel) keep their own `includes` branch — the
+ * distinction between "silently drop" and "tell the caller" is the policy of
+ * the call site, not of this helper.
+ */
+export function resolveThinkingLevel(
+  connection: ConnectionThinkingContext,
+  modelId: string,
+  level: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+  return level !== undefined && thinkingVariantsForConnection(connection, modelId).includes(level)
+    ? level
+    : undefined;
+}
+
 /**
  * Per-model reasoning options declared in `model-metadata.ts`
  * (mirroring models.dev `reasoning_options`). Returns `undefined` for models
diff --git a/packages/core/src/runtime-policy.ts b/packages/core/src/runtime-policy.ts
index 9acccae319..8251dc18c6 100644
--- a/packages/core/src/runtime-policy.ts
+++ b/packages/core/src/runtime-policy.ts
@@ -5,6 +5,7 @@ import type {
   ModelInfo,
 } from './llm-connections.js';
 import type { ProviderType } from './provider-registry.js';
+import type { RelayModelProfile } from './model-thinking.js';
 import type { ChatDefaultPermissionMode, ProxyProtocol } from './settings.js';
 import {
   WEB_SEARCH_PROVIDERS,
@@ -31,6 +32,7 @@ export {
   decodeCanonicalConnectionBaseUrl,
   decodeCanonicalConnectionCatalogEntry,
   decodeConnectionModelId,
+  decodeRelayModelProfilesTable,
   decodeConnectionModel,
   decodeConnectionName,
   decodeConnectionSlug,
@@ -168,6 +170,12 @@ export interface ConnectionConfiguration {
   readonly baseUrl?: string;
   readonly enabled: boolean;
   readonly enabledModelIds: readonly string[];
+  /**
+   * Per-model relay declarations (thinking levels, vision, context window),
+   * as a typed table scoped to `enabledModelIds` — never an extras bag.
+   * Execution paths read it through the shared `relayModelProfile` seam.
+   */
+  readonly relayModelProfiles?: Readonly<Record<string, RelayModelProfile>>;
 }
 
 export interface ConnectionCatalogEntry extends ConnectionConfiguration {
@@ -186,6 +194,14 @@ export interface ConnectionCatalogEntryUpdate {
   readonly baseUrl?: string;
   readonly enabled: boolean;
   readonly enabledModelIds: readonly string[];
+  /**
+   * Profile-table instruction in three states: an absent key leaves the
+   * stored table untouched (except that an endpoint change in the same update
+   * retires it — declarations belong to the endpoint they were declared
+   * against); `null` clears all declarations; a table replaces them wholly.
+   * Profile-blind writers simply omit the key and can never clobber.
+   */
+  readonly relayModelProfiles?: Readonly<Record<string, RelayModelProfile>> | null;
 }
 
 export interface ConnectionVersionBasis {
diff --git a/packages/core/src/runtime-policy/connection-catalog-codec.ts b/packages/core/src/runtime-policy/connection-catalog-codec.ts
index 7a26886338..78b9cf946f 100644
--- a/packages/core/src/runtime-policy/connection-catalog-codec.ts
+++ b/packages/core/src/runtime-policy/connection-catalog-codec.ts
@@ -1,4 +1,10 @@
 import { PROVIDER_DEFAULTS, validateSlug, type ProviderType } from '../llm-connections.js';
+import {
+  DECLARABLE_RELAY_THINKING_LEVELS,
+  isThinkingLevel,
+  type RelayModelProfile,
+  type ThinkingLevel,
+} from '../model-thinking.js';
 import type {
   ConnectionCatalogEntry,
   ConnectionCatalogEntryDraft,
@@ -87,18 +93,27 @@ export function normalizeConnectionCatalogEntryDraft(value: unknown): Connection
   const item = exactRecord(
     value,
     'connection draft',
-    ['slug', 'name', 'providerType', 'baseUrl', 'enabled', 'enabledModelIds'],
+    ['slug', 'name', 'providerType', 'baseUrl', 'enabled', 'enabledModelIds', 'relayModelProfiles'],
     ['slug', 'name', 'providerType', 'enabled', 'enabledModelIds'],
   );
   const providerType = decodeProviderType(item.providerType);
   const baseUrl = normalizeCatalogConnectionBaseUrl(item.baseUrl, providerType);
+  const enabledModelIds = decodeConnectionModelIds(item.enabledModelIds);
+  const profiles =
+    item.relayModelProfiles === undefined
+      ? {}
+      : nonEmptyRelayProfiles(item.relayModelProfiles, enabledModelIds);
+  if (profiles.relayModelProfiles !== undefined) {
+    rejectForeignProfiles(providerType);
+  }
   return {
     slug: decodeConnectionSlug(item.slug),
     name: decodeConnectionName(item.name),
     providerType,
     ...(baseUrl === undefined ? {} : { baseUrl }),
     enabled: booleanValue(item.enabled, 'connection enabled'),
-    enabledModelIds: decodeConnectionModelIds(item.enabledModelIds),
+    enabledModelIds,
+    ...profiles,
   };
 }
 
@@ -108,15 +123,34 @@ export function normalizeConnectionCatalogEntryUpdate(
   const item = exactRecord(
     value,
     'connection update',
-    ['name', 'baseUrl', 'enabled', 'enabledModelIds'],
+    ['name', 'baseUrl', 'enabled', 'enabledModelIds', 'relayModelProfiles'],
     ['name', 'enabled', 'enabledModelIds'],
   );
   const baseUrl = normalizeCatalogConnectionBaseUrl(item.baseUrl);
+  const enabledModelIds = decodeConnectionModelIds(item.enabledModelIds);
+  // Tri-state profile instruction: an absent key stays absent (untouched),
+  // null clears, a table replaces. An absent key must never materialize into
+  // a clear — profile-blind writers omit the key by definition.
   return {
     name: decodeConnectionName(item.name),
     ...(baseUrl === undefined ? {} : { baseUrl }),
     enabled: booleanValue(item.enabled, 'connection enabled'),
-    enabledModelIds: decodeConnectionModelIds(item.enabledModelIds),
+    enabledModelIds,
+    ...(item.relayModelProfiles === undefined
+      ? {}
+      : profilesUpdateInstruction(item.relayModelProfiles, enabledModelIds)),
+  };
+}
+
+function profilesUpdateInstruction(
+  value: unknown,
+  enabledModelIds: readonly string[],
+): { readonly relayModelProfiles: Readonly<Record<string, RelayModelProfile>> | null } {
+  return {
+    relayModelProfiles:
+      value === null
+        ? null
+        : (nonEmptyRelayProfiles(value, enabledModelIds).relayModelProfiles ?? null),
   };
 }
 
@@ -126,14 +160,120 @@ export function normalizeConnectionCatalogEntryUpdateForProvider(
 ): ConnectionCatalogEntryUpdate {
   const update = normalizeConnectionCatalogEntryUpdate(value);
   const baseUrl = normalizeCatalogConnectionBaseUrl(update.baseUrl, providerType);
+  // A `null` (clear stale data) or absent (untouched) instruction is legal on
+  // any provider; only a non-empty table is relay-only.
+  if (update.relayModelProfiles !== undefined && update.relayModelProfiles !== null) {
+    rejectForeignProfiles(providerType);
+  }
   return {
     name: update.name,
     ...(baseUrl === undefined ? {} : { baseUrl }),
     enabled: update.enabled,
     enabledModelIds: update.enabledModelIds,
+    ...(update.relayModelProfiles === undefined
+      ? {}
+      : { relayModelProfiles: update.relayModelProfiles }),
   };
 }
 
+// Relay profiles are an openai-compatible feature: on any other provider the
+// metadata chain is the truth, and a table here would either sit as dead
+// state or silently shadow metadata for the ungated read seams.
+function rejectForeignProfiles(providerType: ProviderType): void {
+  if (providerType !== 'openai-compatible') {
+    throw domainError('relay model profiles are only supported for openai-compatible connections');
+  }
+}
+
+/**
+ * The relay profiles carried by catalog entries, keyed by model id. Strict
+ * on purpose: writers (the settings UI) emit already-normalized tables, so
+ * anything malformed here is a corrupt document or a foreign writer, and
+ * the catalog fails loudly the way every exactRecord does. Profiles are
+ * scoped to `enabledModelIds` — the store prunes them when the selection
+ * changes, so a key outside the set marks a document the store never wrote.
+ */
+export function decodeRelayModelProfilesTable(
+  value: unknown,
+  enabledModelIds: readonly string[],
+): Readonly<Record<string, RelayModelProfile>> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw domainError('connection relay model profiles must be a record');
+  }
+  // fromEntries, not `table[modelId] = declared` on a `{}`: model ids are
+  // arbitrary relay-supplied strings, and a literal `obj['__proto__'] = x`
+  // assignment poisons the prototype instead of creating an own key — the
+  // entry would then vanish from Object.entries and JSON.stringify (silent
+  // data loss on the persistence roundtrip). fromEntries defines every key
+  // as an own data property.
+  const parsed: [string, RelayModelProfile][] = [];
+  for (const [modelId, rawEntry] of Object.entries(value)) {
+    decodeConnectionModelId(modelId);
+    if (!enabledModelIds.includes(modelId)) {
+      throw domainError(`relay model profile for ${modelId} is not an enabled model`);
+    }
+    const entry = exactRecord(
+      rawEntry,
+      `relay model profile for ${modelId}`,
+      ['thinkingLevels', 'vision', 'contextWindow'],
+      [],
+    );
+    const declared: {
+      thinkingLevels?: readonly ThinkingLevel[];
+      vision?: boolean;
+      contextWindow?: number;
+    } = {};
+    if (entry.thinkingLevels !== undefined) {
+      if (!Array.isArray(entry.thinkingLevels) || entry.thinkingLevels.length === 0) {
+        throw domainError(`declared thinking levels for ${modelId} must be a non-empty array`);
+      }
+      if (new Set(entry.thinkingLevels).size !== entry.thinkingLevels.length) {
+        throw domainError(`declared thinking levels for ${modelId} must not repeat`);
+      }
+      for (const level of entry.thinkingLevels) {
+        if (
+          !isThinkingLevel(level) ||
+          !(DECLARABLE_RELAY_THINKING_LEVELS as readonly ThinkingLevel[]).includes(level)
+        ) {
+          // Not just "unknown": 'off' is a disable-wire encoding, not an
+          // intensity tier, and no declaration may carry it (normalize drops
+          // it at write; a persisted table containing it is foreign/corrupt).
+          throw domainError(`declared thinking level for ${modelId} is not declarable`);
+        }
+      }
+      declared.thinkingLevels = [...entry.thinkingLevels] as ThinkingLevel[];
+    }
+    if (entry.vision !== undefined) {
+      declared.vision = booleanValue(entry.vision, `declared vision for ${modelId}`);
+    }
+    if (entry.contextWindow !== undefined) {
+      declared.contextWindow = integerValue(
+        entry.contextWindow,
+        `declared context window for ${modelId}`,
+        1,
+        Number.MAX_SAFE_INTEGER,
+      );
+    }
+    if (Object.keys(declared).length === 0) {
+      throw domainError(`relay model profile for ${modelId} declares nothing`);
+    }
+    parsed.push([modelId, declared]);
+  }
+  return Object.fromEntries(parsed);
+}
+
+// An empty table is not a state worth storing: drafts/canonical entries omit
+// the key, and updates treat it as the same instruction as `null` (clear).
+function nonEmptyRelayProfiles(
+  value: unknown,
+  enabledModelIds: readonly string[],
+): {
+  readonly relayModelProfiles?: Readonly<Record<string, RelayModelProfile>>;
+} {
+  const table = decodeRelayModelProfilesTable(value, enabledModelIds);
+  return Object.keys(table).length > 0 ? { relayModelProfiles: table } : {};
+}
+
 export function decodeCanonicalConnectionCatalogEntry(value: unknown): ConnectionCatalogEntry {
   const item = exactRecord(
     value,
@@ -147,6 +287,7 @@ export function decodeCanonicalConnectionCatalogEntry(value: unknown): Connectio
       'baseUrl',
       'enabled',
       'enabledModelIds',
+      'relayModelProfiles',
       'models',
       'modelSource',
       'modelsFetchedAt',
@@ -170,6 +311,9 @@ export function decodeCanonicalConnectionCatalogEntry(value: unknown): Connectio
     ...(item.baseUrl === undefined ? {} : { baseUrl: item.baseUrl }),
     enabled: item.enabled,
     enabledModelIds: item.enabledModelIds,
+    ...(item.relayModelProfiles === undefined
+      ? {}
+      : { relayModelProfiles: item.relayModelProfiles }),
   });
   if (
     !Array.isArray(item.models) ||
diff --git a/packages/headless/src/harbor-cell.ts b/packages/headless/src/harbor-cell.ts
index 1330aa3133..b7e170a09d 100644
--- a/packages/headless/src/harbor-cell.ts
+++ b/packages/headless/src/harbor-cell.ts
@@ -10,7 +10,12 @@ import type {
   ProviderType,
   RuntimeEvent,
 } from '@maka/core';
-import { isTerminalRuntimeEvent, isThinkingLevel, resolveModelVisionSupport } from '@maka/core';
+import {
+  relayModelProfile,
+  isTerminalRuntimeEvent,
+  isThinkingLevel,
+  resolveModelVisionSupport,
+} from '@maka/core';
 import {
   AgentGraphCoordinator,
   AGENT_TOOL_GROUP_ID,
@@ -1232,6 +1237,7 @@ export function buildAiSdkCellBackendRegistration(input: {
           connection.providerType,
           connection.models,
           input.model,
+          relayModelProfile(connection, input.model)?.vision,
         ),
         readAttachmentBytes: createAttachmentByteReader({
           artifactStore,
diff --git a/packages/runtime-host/src/__tests__/catalog-reader.test.ts b/packages/runtime-host/src/__tests__/catalog-reader.test.ts
index 4bd2864936..0f4b54a2d1 100644
--- a/packages/runtime-host/src/__tests__/catalog-reader.test.ts
+++ b/packages/runtime-host/src/__tests__/catalog-reader.test.ts
@@ -61,6 +61,45 @@ test('rejects a repeated Skill catalog cursor instead of looping forever', async
   );
 });
 
+test('reassembles per-item relay profiles into the connection profile table', async () => {
+  const profile = { thinkingLevels: ['low'], vision: false, contextWindow: 65_536 } as const;
+  const connection = fakeConnection(async (_operation, input) => {
+    const continuation = input.kind === 'continue';
+    return {
+      kind: 'page',
+      revision: 1,
+      defaultTarget: null,
+      connectionCount: 1,
+      items: continuation
+        ? [{ kind: 'enabled_model_id', connectionIndex: 0, itemIndex: 1, modelId: 'plain' }]
+        : [
+            connectionHeader(2),
+            {
+              kind: 'enabled_model_id',
+              connectionIndex: 0,
+              itemIndex: 0,
+              modelId: 'declared',
+              relayProfile: profile,
+            },
+          ],
+      nextCursor: continuation
+        ? null
+        : { connectionIndex: 0, part: 'enabled_model_id', itemIndex: 1 },
+    };
+  });
+
+  const catalog = await readRuntimeHostConnectionCatalog(connection);
+  assert.deepEqual(catalog.connections, [
+    {
+      enabledModelIds: ['declared', 'plain'],
+      models: [],
+      // Only the profiled model lands in the reassembled table — the item
+      // shape is wire-only and never surfaces per item downstream.
+      relayModelProfiles: { declared: profile },
+    },
+  ]);
+});
+
 test('rejects a Connection catalog with a missing index', async () => {
   const connection = fakeConnection(async () => ({
     kind: 'page',
diff --git a/packages/runtime-host/src/__tests__/execution-model-composition.test.ts b/packages/runtime-host/src/__tests__/execution-model-composition.test.ts
index d45ffdb76a..4d8a98b11f 100644
--- a/packages/runtime-host/src/__tests__/execution-model-composition.test.ts
+++ b/packages/runtime-host/src/__tests__/execution-model-composition.test.ts
@@ -141,6 +141,10 @@ test('backend abort cannot cancel the authority-owned OAuth refresh used by its
   let transports: ReturnType<typeof controlledOAuthTransports> | undefined;
   try {
     const policy = await openInteractiveRuntimePolicyStoresForWrite(owner.lease);
+    // claude-subscription discovery is fallback-only (session-scoped OAuth
+    // tokens cannot call GET /v1/models). Create seeds the curated inventory;
+    // pick an id from that inventory rather than opening a fetch ticket.
+    const subscriptionModelId = 'claude-sonnet-5';
     const created = await policy.connectionCatalog.create({
       expectedCatalogRevision: 0,
       connection: {
@@ -148,7 +152,7 @@ test('backend abort cannot cancel the authority-owned OAuth refresh used by its
         name: 'OAuth backend creation',
         providerType: 'claude-subscription',
         enabled: true,
-        enabledModelIds: [MODEL_ID],
+        enabledModelIds: [subscriptionModelId],
       },
     });
     assert.equal(created.kind, 'committed');
@@ -156,6 +160,10 @@ test('backend abort cannot cancel the authority-owned OAuth refresh used by its
     const connection = created.snapshot.connections[0];
     assert.ok(connection);
     if (!connection) return;
+    assert.ok(
+      connection.models.some((model) => model.id === subscriptionModelId),
+      'create must seed the curated claude-subscription inventory',
+    );
     const tokens: OAuthSubscriptionTokens = {
       access_token: 'expired-oauth-access',
       refresh_token: 'rotating-oauth-refresh',
@@ -187,13 +195,13 @@ test('backend abort cannot cancel the authority-owned OAuth refresh used by its
       )}\n`,
       { encoding: 'utf8', mode: 0o600 },
     );
-    await publishConnectionModel(policy, connection.connectionId, MODEL_ID);
     transports = controlledOAuthTransports();
     const authority = new HostOAuthExecutionAuthority(policy);
     const firstAbort = new AbortController();
     const firstCreation = createHostAiSdkBackend(
       backendCreationFixture({
         abortSignal: firstAbort.signal,
+        modelId: subscriptionModelId,
         resolveExecutionConnection: () =>
           policy.operations.resolveExecutionConnection('backend-creation-connection'),
         runtimePolicy: policy,
@@ -218,6 +226,7 @@ test('backend abort cannot cancel the authority-owned OAuth refresh used by its
     secondBackend = await createHostAiSdkBackend(
       backendCreationFixture({
         abortSignal: new AbortController().signal,
+        modelId: subscriptionModelId,
         resolveExecutionConnection: () =>
           policy.operations.resolveExecutionConnection('backend-creation-connection'),
         runtimePolicy: policy,
diff --git a/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts b/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts
index 9d86d89e89..213d07e075 100644
--- a/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts
+++ b/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts
@@ -598,6 +598,7 @@ test('projects state-dependent OAuth endpoint overrides as invalid requests', as
           baseUrl: 'https://copilot.example.test/v1',
           enabled: connection.enabled,
           enabledModelIds: connection.enabledModelIds,
+          relayModelProfiles: null,
         },
       },
       context,
@@ -665,6 +666,74 @@ test('returns connection_not_found when deleting a credential after its connecti
   });
 });
 
+test('a fully profiled relay catalog paginates with profiles riding per item', async () => {
+  await withCoordinator(async ({ coordinator, stores }) => {
+    // Every claim in one header table used to be what made a long catalog
+    // unreadable: the header item is atomic to the paginator. Profiles now
+    // travel with their own enabled_model_id item, so a connection whose
+    // EVERY enabled model declares a full profile must still paginate.
+    const modelIds = Array.from({ length: 40 }, (_, index) => `relay-model-${index}`);
+    const profiles = Object.fromEntries(
+      modelIds.map((modelId) => [
+        modelId,
+        {
+          thinkingLevels: ['low', 'high'] as ('low' | 'high')[],
+          vision: true,
+          contextWindow: 131_072,
+        },
+      ]),
+    );
+    const created = await stores.connectionCatalog.create({
+      expectedCatalogRevision: 0,
+      connection: {
+        slug: 'profiled-relay',
+        name: 'Profiled relay',
+        providerType: 'openai-compatible',
+        baseUrl: 'https://relay.example/v1',
+        enabled: true,
+        enabledModelIds: modelIds,
+        relayModelProfiles: profiles,
+      },
+    });
+    assert.equal(created.kind, 'committed');
+    if (created.kind !== 'committed') return;
+
+    const seen: Extract<ConnectionCatalogPageItem, { kind: 'enabled_model_id' }>[] = [];
+    const first = await coordinator.handlers['connection.catalog.query'](
+      { kind: 'start' },
+      context,
+    );
+    assert.equal(first.ok, true);
+    if (!first.ok || first.result.kind !== 'page') return;
+    const queue = [first.result];
+    while (queue.length > 0) {
+      const observed = queue.pop()!;
+      assert.ok(
+        Buffer.byteLength(JSON.stringify(observed), 'utf8') <= CONNECTION_CATALOG_PAGE_MAX_BYTES,
+      );
+      for (const item of observed.items) {
+        if (item.kind === 'connection') {
+          assert.ok(!('relayModelProfiles' in item), 'header must not carry the profile table');
+        }
+        if (item.kind === 'enabled_model_id') seen.push(item);
+      }
+      if (observed.nextCursor) {
+        const next = await coordinator.handlers['connection.catalog.query'](
+          { kind: 'continue', revision: observed.revision, cursor: observed.nextCursor },
+          context,
+        );
+        assert.equal(next.ok, true);
+        if (!next.ok || next.result.kind !== 'page') return;
+        queue.push(next.result);
+      }
+    }
+    assert.equal(seen.length, modelIds.length);
+    for (const item of seen) {
+      assert.deepEqual(item.relayProfile, profiles[item.modelId]);
+    }
+  });
+});
+
 test('projects a corrupted runtime policy document as persistence_failed on query', async () => {
   await withCoordinator(async ({ coordinator, root }) => {
     await writeFile(join(root, 'runtime-policy.json'), '{not-json', 'utf8');
@@ -802,7 +871,10 @@ function largeConnection(connectionIndex: number): ConnectionCatalogEntryDraft {
 function expectedCatalogItems(snapshot: ConnectionCatalogSnapshot): ConnectionCatalogPageItem[] {
   const items: ConnectionCatalogPageItem[] = [];
   for (const [connectionIndex, connection] of snapshot.connections.entries()) {
-    const { enabledModelIds, models, ...header } = connection;
+    // Mirror `projectCatalogItems`: profiles ride on their enabled_model_id
+    // item, never in one header table (a header item is atomic to the
+    // paginator — a long declaration list would make it unsplittable).
+    const { enabledModelIds, models, relayModelProfiles, ...header } = connection;
     items.push({
       kind: 'connection',
       connectionIndex,
@@ -811,7 +883,14 @@ function expectedCatalogItems(snapshot: ConnectionCatalogSnapshot): ConnectionCa
       modelCount: models.length,
     });
     for (const [itemIndex, modelId] of enabledModelIds.entries()) {
-      items.push({ kind: 'enabled_model_id', connectionIndex, itemIndex, modelId });
+      const relayProfile = relayModelProfiles?.[modelId];
+      items.push({
+        kind: 'enabled_model_id',
+        connectionIndex,
+        itemIndex,
+        modelId,
+        ...(relayProfile === undefined ? {} : { relayProfile }),
+      });
     }
     for (const [itemIndex, model] of models.entries()) {
       items.push({ kind: 'model', connectionIndex, itemIndex, model });
diff --git a/packages/runtime-host/src/__tests__/session-catalog-coordinator.test.ts b/packages/runtime-host/src/__tests__/session-catalog-coordinator.test.ts
index 164e37ff20..6fcc96ef08 100644
--- a/packages/runtime-host/src/__tests__/session-catalog-coordinator.test.ts
+++ b/packages/runtime-host/src/__tests__/session-catalog-coordinator.test.ts
@@ -8,6 +8,7 @@ import {
   createGenesisExecutionBoundary,
   DEEP_RESEARCH_SESSION_LABEL,
   DEEP_RESEARCH_SESSION_NAME,
+  type RelayModelProfile,
   type SessionHeader,
 } from '@maka/core';
 import { SessionConfigurationTransitionError, headerToSummary } from '@maka/runtime';
@@ -239,6 +240,85 @@ test('creation rejects reserved execution labels before claiming a Session ident
   assert.equal(fixture.drainRequests(), 0);
 });
 
+test('creation on a relay connection honours declared levels via the catalog projection', async () => {
+  // The catalog entry carries the typed relayModelProfiles projection (never
+  // the extras bag), so a declared relay level passes the gate — and what
+  // passes is exactly what execution rebuilds the runtime connection from.
+  let createAttempts = 0;
+  let persistedThinkingLevel: unknown;
+  const fixture = createFixture({
+    connection: {
+      providerType: 'openai-compatible',
+      enabledModelIds: ['relay-model'],
+      models: [{ id: 'relay-model' }],
+      relayModelProfiles: { 'relay-model': { thinkingLevels: ['minimal', 'low'] } },
+    },
+    stores: {
+      createStableSession: async (args) => {
+        createAttempts += 1;
+        persistedThinkingLevel = args.input.thinkingLevel;
+        return {
+          kind: 'existing' as const,
+          record: headerSnapshot(sessionHeader(args.sessionId, ['user-label']), 1),
+        };
+      },
+    },
+  });
+
+  const outcome = await fixture.coordinator.handlers['session.create'](
+    {
+      sessionId: fixture.sessionId,
+      cwd: process.cwd(),
+      modelTarget: { kind: 'explicit', connectionSlug: 'test', model: 'relay-model' },
+      thinkingLevel: 'low',
+    },
+    context,
+  );
+
+  assert.equal(outcome.ok, true);
+  assert.equal(createAttempts, 1);
+  assert.equal(persistedThinkingLevel, 'low');
+});
+
+test('creation on a relay connection without declarations still fails closed on any thinkingLevel', async () => {
+  // Undeclared relay models resolve no variants — accepting an unverifiable
+  // level would be worse than rejecting it, because the wire could never
+  // honour what the catalog cannot see.
+  let createAttempts = 0;
+  const fixture = createFixture({
+    connection: {
+      providerType: 'openai-compatible',
+      enabledModelIds: ['relay-model'],
+      models: [{ id: 'relay-model' }],
+    },
+    stores: {
+      createStableSession: async () => {
+        createAttempts += 1;
+        assert.fail('Unverifiable thinking levels must be rejected before persistence');
+      },
+    },
+  });
+
+  const outcome = await fixture.coordinator.handlers['session.create'](
+    {
+      sessionId: fixture.sessionId,
+      cwd: process.cwd(),
+      modelTarget: { kind: 'explicit', connectionSlug: 'test', model: 'relay-model' },
+      thinkingLevel: 'low',
+    },
+    context,
+  );
+
+  assert.deepEqual(outcome, {
+    ok: false,
+    error: {
+      code: 'invalid_request',
+      message: 'Session model does not support thinking level low',
+    },
+  });
+  assert.equal(createAttempts, 0);
+});
+
 test('creation rejects explore permission without a declared mode', async () => {
   let createAttempts = 0;
   const fixture = createFixture({
@@ -524,6 +604,7 @@ function createFixture(
     readonly stores?: Partial<CatalogStores>;
     readonly manager?: Partial<ConfigurationAuthority>;
     readonly continuity?: Partial<SessionContinuity>;
+    readonly connection?: FixtureConnection;
   } = {},
 ) {
   const sessionId = 'session-1';
@@ -558,7 +639,7 @@ function createFixture(
     },
     ...options.stores,
   };
-  const runtimePolicy = runtimePolicyFixture();
+  const runtimePolicy = runtimePolicyFixture(options.connection ?? {});
   const manager: ConfigurationAuthority = {
     transitionSessionConfiguration: async (_sessionId, input) => {
       header = {
@@ -602,17 +683,27 @@ function createFixture(
   };
 }
 
-function runtimePolicyFixture(): RuntimePolicy {
+type FixtureConnection = {
+  readonly providerType?: 'openai' | 'openai-compatible';
+  readonly enabledModelIds?: readonly string[];
+  readonly models?: readonly { id: string }[];
+  readonly relayModelProfiles?: Readonly<Record<string, RelayModelProfile>>;
+};
+
+function runtimePolicyFixture(overrides: FixtureConnection): RuntimePolicy {
   const policy = createDefaultRuntimePolicy();
   const connection = {
     connectionId: 'connection-1',
     revision: 1,
     slug: 'test',
     name: 'Test',
-    providerType: 'openai' as const,
+    providerType: overrides.providerType ?? ('openai' as const),
     enabled: true,
-    enabledModelIds: ['model-1'],
-    models: [{ id: 'model-1' }],
+    enabledModelIds: overrides.enabledModelIds ?? ['model-1'],
+    models: overrides.models ?? [{ id: 'model-1' }],
+    ...(overrides.relayModelProfiles === undefined
+      ? {}
+      : { relayModelProfiles: overrides.relayModelProfiles }),
   };
   return {
     connectionCatalog: {
diff --git a/packages/runtime-host/src/client/catalog-reader.ts b/packages/runtime-host/src/client/catalog-reader.ts
index 035e054257..5bf9b283d1 100644
--- a/packages/runtime-host/src/client/catalog-reader.ts
+++ b/packages/runtime-host/src/client/catalog-reader.ts
@@ -2,6 +2,8 @@ import type {
   ConnectionCatalogCursor,
   ConnectionCatalogPageItem,
   ConnectionCatalogQueryResult,
+  RelayModelProfile,
+  RelayModelProfiles,
   SessionCatalogFilter,
   SessionCatalogItem,
   SkillCatalogLocalContext,
@@ -26,6 +28,7 @@ export type RuntimeHostConnectionCatalogEntry = Omit<
 > & {
   readonly enabledModelIds: readonly string[];
   readonly models: readonly Extract<ConnectionCatalogPageItem, { kind: 'model' }>['model'][];
+  readonly relayModelProfiles?: RelayModelProfiles;
 };
 
 export interface RuntimeHostConnectionCatalogSnapshot {
@@ -207,6 +210,7 @@ function assembleConnectionCatalog(
       header: Extract<ConnectionCatalogPageItem, { kind: 'connection' }>;
       enabledModelIds: Map<number, string>;
       models: Map<number, RuntimeHostConnectionCatalogEntry['models'][number]>;
+      relayProfiles: Map<string, RelayModelProfile>;
     }
   >();
   for (const item of items) {
@@ -218,6 +222,7 @@ function assembleConnectionCatalog(
       header: item,
       enabledModelIds: new Map(),
       models: new Map(),
+      relayProfiles: new Map(),
     });
   }
   for (const item of items) {
@@ -230,8 +235,14 @@ function assembleConnectionCatalog(
     if (item.itemIndex >= expectedCount || values.has(item.itemIndex)) {
       throw new RuntimeHostCatalogReadError('connection', 'invalid_projection');
     }
-    if (item.kind === 'enabled_model_id') entry.enabledModelIds.set(item.itemIndex, item.modelId);
-    else entry.models.set(item.itemIndex, item.model);
+    if (item.kind === 'enabled_model_id') {
+      entry.enabledModelIds.set(item.itemIndex, item.modelId);
+      // Reassemble the profile table the projector spread across items; the
+      // downstream type is the per-model map, not the wire's per-item shape.
+      if (item.relayProfile !== undefined) entry.relayProfiles.set(item.modelId, item.relayProfile);
+    } else {
+      entry.models.set(item.itemIndex, item.model);
+    }
   }
   if (entries.size !== first.connectionCount) {
     throw new RuntimeHostCatalogReadError('connection', 'invalid_projection');
@@ -256,6 +267,9 @@ function assembleConnectionCatalog(
         ...header,
         enabledModelIds: orderedValues(entry.enabledModelIds),
         models: orderedValues(entry.models),
+        ...(entry.relayProfiles.size === 0
+          ? {}
+          : { relayModelProfiles: Object.fromEntries(entry.relayProfiles) }),
       };
     });
   return { revision: first.revision, defaultTarget: first.defaultTarget, connections };
diff --git a/packages/runtime-host/src/protocol/index.ts b/packages/runtime-host/src/protocol/index.ts
index 5ad6562c30..65d057c53d 100644
--- a/packages/runtime-host/src/protocol/index.ts
+++ b/packages/runtime-host/src/protocol/index.ts
@@ -45,7 +45,10 @@ export const RUNTIME_HOST_PROTOCOL_VERSION = 0 as const;
 // The wire version remains v0 before the first release. This independent epoch
 // lets a new Client retire a stale same-version Host whose closed schema is no
 // longer safe to use.
-export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 4 as const;
+// 5: relay capability declarations moved off the connection header onto
+// each enabled_model_id item (`relayProfile`) — header items are atomic to
+// the paginator, so a per-model table there could make an entry unreadable.
+export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 5 as const;
 // A legal sandbox-boundary expansion can consume 64 KiB before its Interaction
 // envelope and independently bounded justification are added. Keep transport
 // capacity large enough to represent that domain value; narrower surfaces such
diff --git a/packages/runtime-host/src/protocol/runtime-policy.ts b/packages/runtime-host/src/protocol/runtime-policy.ts
index c6a7413e3c..5311014223 100644
--- a/packages/runtime-host/src/protocol/runtime-policy.ts
+++ b/packages/runtime-host/src/protocol/runtime-policy.ts
@@ -40,7 +40,11 @@ import {
   type SetDefaultConnectionTargetInput,
   type UpdateCatalogConnectionInput,
 } from '@maka/core/runtime-policy';
-import { requireExactRecord, requireRecord } from './codec.js';
+import { normalizeRelayModelProfiles, type RelayModelProfile } from '@maka/core/model-thinking';
+// The client subgraph cannot import core subpaths directly (dependency
+// boundary); the wire types it needs are re-exported through this file.
+export type { RelayModelProfile, RelayModelProfiles } from '@maka/core/model-thinking';
+import { requireExactRecord, requireShapedRecord, requireRecord } from './codec.js';
 import { invalidProtocolFrame } from './errors.js';
 import { defineOperation } from './operation-spec.js';
 
@@ -94,7 +98,7 @@ export type ConnectionCatalogQueryInput =
 
 export type ConnectionCatalogHeaderItem = Omit<
   ConnectionCatalogEntry,
-  'enabledModelIds' | 'models'
+  'enabledModelIds' | 'models' | 'relayModelProfiles'
 > & {
   readonly kind: 'connection';
   readonly connectionIndex: number;
@@ -109,6 +113,12 @@ export type ConnectionCatalogPageItem =
       readonly connectionIndex: number;
       readonly itemIndex: number;
       readonly modelId: string;
+      /**
+       * The model's relay profile, when the connection declares one.
+       * Profiles travel per item instead of in one header table so the
+       * paginator can always split a catalog — a header item is atomic.
+       */
+      readonly relayProfile?: RelayModelProfile;
     }
   | {
       readonly kind: 'model';
@@ -454,15 +464,29 @@ function catalogCursor(value: unknown): ConnectionCatalogCursor {
   throw invalidProtocolFrame('Invalid connection catalog cursor part');
 }
 
+// A single profile on an enabled_model_id item. The host emits values the
+// canonical store already validated, so this sanitizes (drops the unusable)
+// rather than re-running the strict table decoder — which would demand an
+// enabledModelIds argument the item does not carry.
+function decodeRelayProfile(value: unknown): RelayModelProfile {
+  const sanitized = normalizeRelayModelProfiles({ m: value })?.m;
+  if (sanitized === undefined) {
+    throw invalidProtocolFrame('Invalid enabled model id relay profile');
+  }
+  return sanitized;
+}
+
 function catalogPageItem(value: unknown): ConnectionCatalogPageItem {
   const item = requireRecord(value, 'connection catalog page item');
   if (item.kind === 'enabled_model_id') {
-    const enabled = requireExactRecord(item, 'enabled model id item', [
-      'kind',
-      'connectionIndex',
-      'itemIndex',
-      'modelId',
-    ]);
+    // Exact-on-the-required-four, relayProfile optional: most models declare
+    // nothing, and requireExactRecord would make the key mandatory.
+    const enabled = requireShapedRecord(
+      item,
+      'enabled model id item',
+      ['kind', 'connectionIndex', 'itemIndex', 'modelId'],
+      ['relayProfile'],
+    );
     return {
       kind: 'enabled_model_id',
       connectionIndex: integer(
@@ -478,6 +502,9 @@ function catalogPageItem(value: unknown): ConnectionCatalogPageItem {
         CONNECTION_CATALOG_MAX_ENABLED_MODEL_IDS - 1,
       ),
       modelId: decodeDomain(() => decodeConnectionModelId(enabled.modelId)),
+      ...(enabled.relayProfile === undefined
+        ? {}
+        : { relayProfile: decodeDomain(() => decodeRelayProfile(enabled.relayProfile)) }),
     };
   }
   if (item.kind === 'model') {
diff --git a/packages/runtime-host/src/server/execution-model-authority.ts b/packages/runtime-host/src/server/execution-model-authority.ts
index 4429764bbe..04d0664a66 100644
--- a/packages/runtime-host/src/server/execution-model-authority.ts
+++ b/packages/runtime-host/src/server/execution-model-authority.ts
@@ -775,12 +775,19 @@ export async function resolveExecutionTarget(
     );
   }
 
+  // Relay profiles ride the connection as a first-class field, so every
+  // downstream seam (buildProviderOptions variant gate, declared vision,
+  // declared context window) reads the host path identically to the
+  // embedded one.
   const connection: RuntimeExecutionConnection = {
     slug: resolved.connection.slug,
     providerType: resolved.connection.providerType,
     ...(resolved.connection.baseUrl ? { baseUrl: resolved.connection.baseUrl } : {}),
     defaultModel: model,
     models: [...resolved.connection.models],
+    ...(resolved.connection.relayModelProfiles === undefined
+      ? {}
+      : { relayModelProfiles: resolved.connection.relayModelProfiles }),
   };
   if (provider.authKind === 'oauth_token') {
     const material = resolved.secretMaterial.connection;
diff --git a/packages/runtime-host/src/server/execution-model-composition.ts b/packages/runtime-host/src/server/execution-model-composition.ts
index b9aae3acbe..3c7ce95859 100644
--- a/packages/runtime-host/src/server/execution-model-composition.ts
+++ b/packages/runtime-host/src/server/execution-model-composition.ts
@@ -4,6 +4,7 @@ import {
   isDeepResearchSession,
 } from '@maka/core/explore-agent';
 import { resolveModelVisionSupport } from '@maka/core/model-metadata';
+import { relayModelProfile } from '@maka/core/model-thinking';
 import { activePlanExecution, type PlanSessionState, type PlanStore } from '@maka/core/plan';
 import type { ModelCallAttempt } from '@maka/core/model-call-attempt';
 import type { RuntimePolicy } from '@maka/core/runtime-policy';
@@ -575,6 +576,7 @@ export async function createHostAiSdkBackend(input: HostAiSdkBackendInput): Prom
           target.connection.providerType,
           target.connection.models,
           target.model,
+          relayModelProfile(target.connection, target.model)?.vision,
         ),
         readAttachmentBytes: createAttachmentByteReader({
           artifactStore: input.artifacts,
diff --git a/packages/runtime-host/src/server/runtime-policy-coordinator.ts b/packages/runtime-host/src/server/runtime-policy-coordinator.ts
index bd64de31ce..368c46b90c 100644
--- a/packages/runtime-host/src/server/runtime-policy-coordinator.ts
+++ b/packages/runtime-host/src/server/runtime-policy-coordinator.ts
@@ -360,7 +360,10 @@ function connectionBasis(connection: ConnectionCatalogEntry): ConnectionVersionB
 function projectCatalogItems(snapshot: ConnectionCatalogSnapshot): ConnectionCatalogPageItem[] {
   const items: ConnectionCatalogPageItem[] = [];
   for (const [connectionIndex, connection] of snapshot.connections.entries()) {
-    const { enabledModelIds, models, ...header } = connection;
+    // Profiles ride on their enabled_model_id item, never in one header
+    // table: a header item is atomic to the paginator, so a long declaration
+    // list would make the whole connection unreadable.
+    const { enabledModelIds, models, relayModelProfiles, ...header } = connection;
     items.push({
       kind: 'connection',
       connectionIndex,
@@ -369,7 +372,14 @@ function projectCatalogItems(snapshot: ConnectionCatalogSnapshot): ConnectionCat
       modelCount: models.length,
     });
     for (const [itemIndex, modelId] of enabledModelIds.entries()) {
-      items.push({ kind: 'enabled_model_id', connectionIndex, itemIndex, modelId });
+      const relayProfile = relayModelProfiles?.[modelId];
+      items.push({
+        kind: 'enabled_model_id',
+        connectionIndex,
+        itemIndex,
+        modelId,
+        ...(relayProfile === undefined ? {} : { relayProfile }),
+      });
     }
     for (const [itemIndex, model] of models.entries()) {
       items.push({ kind: 'model', connectionIndex, itemIndex, model });
diff --git a/packages/runtime-host/src/server/session-catalog-coordinator.ts b/packages/runtime-host/src/server/session-catalog-coordinator.ts
index eca6b9915b..7d17711849 100644
--- a/packages/runtime-host/src/server/session-catalog-coordinator.ts
+++ b/packages/runtime-host/src/server/session-catalog-coordinator.ts
@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { realpath, stat } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
 import { isModelExplicitlyUnsupportedForChat } from '@maka/core/model-catalog';
-import { thinkingVariantsForModel } from '@maka/core/model-thinking';
+import { thinkingVariantsForConnection } from '@maka/core/model-thinking';
 import {
   executionBoundaryDisplayMode,
   type ExecutionBoundary,
@@ -585,9 +585,21 @@ export class HostSessionCatalogCoordinator {
         'Session model identifier exceeds the wire limit',
       );
     }
+    // Fail-closed for undeclared levels only: the catalog entry carries the
+    // typed `relayModelProfiles` table, so a relay's user-declared levels DO
+    // reach this gate. A level outside the resolved variants is still
+    // rejected — execution-model-authority rebuilds the runtime connection
+    // from the same table, so whatever passes here is exactly what the wire
+    // can send.
     if (
       thinkingLevel !== undefined &&
-      !thinkingVariantsForModel(connection.providerType, selected.modelId).includes(thinkingLevel)
+      !thinkingVariantsForConnection(
+        {
+          providerType: connection.providerType,
+          relayModelProfiles: connection.relayModelProfiles,
+        },
+        selected.modelId,
+      ).includes(thinkingLevel)
     ) {
       throw new SessionOperationFailure(
         'invalid_request',
diff --git a/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts b/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
index c61ecb773b..cad48a7b4a 100644
--- a/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
+++ b/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
@@ -195,6 +195,54 @@ function connection(): LlmConnection {
   };
 }
 
+describe('declared relay context window', () => {
+  test('a user declaration outranks the relay /models report and metadata', () => {
+    const relay: LlmConnection = {
+      slug: 'my-relay',
+      name: 'My Relay',
+      providerType: 'openai-compatible',
+      baseUrl: 'https://relay.example/v1',
+      defaultModel: 'reasoner-32k',
+      enabled: true,
+      createdAt: 1,
+      updatedAt: 1,
+      models: [{ id: 'reasoner-32k', contextWindow: 8_192 }],
+      relayModelProfiles: { 'reasoner-32k': { contextWindow: 131_072 } },
+    };
+    const policy = buildDefaultContextBudgetPolicy(relay, { env: {}, modelId: 'reasoner-32k' });
+    // Declared 131_072 wins: reserve 131_072/4 caps at 16_384. The fetched
+    // 8_192 row would have yielded 8_192 − 2_048, and no declaration at all
+    // would have fallen to the 32_000 unknown-model default.
+    assert.equal(policy?.maxHistoryEstimatedTokens, 131_072 - 16_384);
+    // Clearing the declaration falls back to the fetched row's window.
+    const undeclared: LlmConnection = { ...relay, relayModelProfiles: undefined };
+    const fallback = buildDefaultContextBudgetPolicy(undeclared, {
+      env: {},
+      modelId: 'reasoner-32k',
+    });
+    assert.equal(fallback?.maxHistoryEstimatedTokens, 8_192 - 2_048);
+  });
+
+  test('the same table is inert on non-relay providers', () => {
+    // Declarations are an openai-compatible feature; a profiles table riding
+    // along on another provider (stale import, provider flip) must not shadow
+    // that provider's stored rows or metadata.
+    const other: LlmConnection = {
+      slug: 'other',
+      name: 'Other',
+      providerType: 'openai',
+      defaultModel: 'reasoner-32k',
+      enabled: true,
+      createdAt: 1,
+      updatedAt: 1,
+      models: [{ id: 'reasoner-32k', contextWindow: 8_192 }],
+      relayModelProfiles: { 'reasoner-32k': { contextWindow: 131_072 } },
+    };
+    const policy = buildDefaultContextBudgetPolicy(other, { env: {}, modelId: 'reasoner-32k' });
+    assert.equal(policy?.maxHistoryEstimatedTokens, 8_192 - 2_048);
+  });
+});
+
 function agentPlanConnection(): LlmConnection {
   return {
     slug: 'volcengine-agent-plan',
diff --git a/packages/runtime/src/__tests__/model-factory-thinking.test.ts b/packages/runtime/src/__tests__/model-factory-thinking.test.ts
index 69306437fe..993bb83999 100644
--- a/packages/runtime/src/__tests__/model-factory-thinking.test.ts
+++ b/packages/runtime/src/__tests__/model-factory-thinking.test.ts
@@ -596,6 +596,88 @@ describe('buildProviderOptions: openai-compatible namespace', () => {
       { openai: { store: false, forceReasoning: true, reasoningEffort: 'high' } },
     );
   });
+
+  test('custom relay connections use per-model declared levels under the camelCase slug namespace', () => {
+    const declared: LlmConnection = {
+      ...conn('openai-compatible', 'my-relay'),
+      baseUrl: 'https://relay.example/v1',
+      relayModelProfiles: {
+        'dsv4-flash': { thinkingLevels: ['minimal', 'low', 'medium', 'high', 'max'] },
+      },
+    };
+    // Declared levels land under the provider-options key derived from the
+    // connection slug. The SDK's canonical key for a dashed provider name is
+    // its camelCase alias — using the raw form still works but returns a
+    // `deprecated` warning on every call. ('off' cannot appear in a
+    // declaration — see DECLARABLE_RELAY_THINKING_LEVELS — so no off→'none'
+    // mapping for relays is asserted here.)
+    assert.deepEqual(buildProviderOptions(declared, 'dsv4-flash', 'high'), {
+      myRelay: { reasoningEffort: 'high' },
+    });
+    assert.deepEqual(buildProviderOptions(declared, 'dsv4-flash', 'max'), {
+      myRelay: { reasoningEffort: 'max' },
+    });
+    // Levels outside the declaration stay gated off, and undeclared
+    // connections emit nothing (prior behaviour).
+    assert.deepEqual(buildProviderOptions(declared, 'dsv4-flash', 'xhigh'), {});
+    assert.deepEqual(
+      buildProviderOptions(conn('openai-compatible', 'my-relay'), 'any-model', 'high'),
+      {},
+    );
+  });
+
+  test('declared relay levels reach the actual chat-completions request body', async () => {
+    // Intermediate providerOptions objects matching does not prove the wire
+    // carries the effort — this capture asserts the SDK's camelCase slug key
+    // is accepted AND translated into the body with zero deprecations.
+    const bodies: Record<string, unknown>[] = [];
+    const captureFetch: typeof globalThis.fetch = async (_input, init) => {
+      bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+      return new Response(
+        JSON.stringify({
+          id: 'chatcmpl-1',
+          object: 'chat.completion',
+          created: 1,
+          model: 'dsv4-flash',
+          choices: [
+            {
+              index: 0,
+              message: { role: 'assistant', content: 'ok' },
+              finish_reason: 'stop',
+            },
+          ],
+          usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      );
+    };
+    const declared: LlmConnection = {
+      ...conn('openai-compatible', 'my-relay'),
+      baseUrl: 'https://relay.example/v1',
+      relayModelProfiles: {
+        'dsv4-flash': { thinkingLevels: ['minimal', 'low', 'medium', 'high', 'max'] },
+      },
+    };
+    const model = getAIModel({
+      connection: declared,
+      apiKey: 'relay-key',
+      modelId: 'dsv4-flash',
+      fetch: captureFetch,
+    });
+    const result = await model.doGenerate({
+      prompt: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
+      providerOptions: buildProviderOptions(declared, 'dsv4-flash', 'high'),
+    });
+    assert.equal(bodies.length, 1);
+    assert.equal(bodies[0]?.reasoning_effort, 'high');
+    // The raw dashed slug as a providerOptions key is deprecated by the SDK:
+    // the camelCase alias must carry no such warning.
+    assert.equal(
+      (result.warnings ?? []).some((warning) => warning.type === 'deprecated'),
+      false,
+      JSON.stringify(result.warnings),
+    );
+  });
 });
 
 test('models without a real off wire do not expose off', () => {
diff --git a/packages/runtime/src/context-budget-policy.ts b/packages/runtime/src/context-budget-policy.ts
index a8f62c6851..87d0dcab40 100644
--- a/packages/runtime/src/context-budget-policy.ts
+++ b/packages/runtime/src/context-budget-policy.ts
@@ -1,5 +1,6 @@
 import type { RuntimeExecutionConnection } from '@maka/core/llm-connections';
 import { lookupModelMetadata } from '@maka/core/model-metadata';
+import { relayModelProfile } from '@maka/core/model-thinking';
 import type { ContextBudgetPolicy } from './context-budget.js';
 import { finitePositive } from './context-budget-helpers.js';
 
@@ -413,14 +414,16 @@ export function resolveSelectedModelContextWindow(
   modelId: string | undefined,
 ): number | undefined {
   const selectedModelId = modelId ?? connection.defaultModel;
-  const model = selectedModelId
-    ? connection.models?.find((candidate) => candidate.id === selectedModelId)
-    : undefined;
+  if (selectedModelId === undefined) return undefined;
+  // A user declaration outranks both the relay's /models report and generated
+  // metadata — mirrors the declared-vision precedence in model-metadata.ts,
+  // through the same provider-gated seam (relay declarations only).
+  const declared = relayModelProfile(connection, selectedModelId)?.contextWindow;
+  if (declared !== undefined) return declared;
+  const model = connection.models?.find((candidate) => candidate.id === selectedModelId);
   return (
     model?.contextWindow ??
-    (selectedModelId
-      ? lookupModelMetadata(connection.providerType, selectedModelId).contextWindow
-      : undefined)
+    lookupModelMetadata(connection.providerType, selectedModelId).contextWindow
   );
 }
 
diff --git a/packages/runtime/src/model-adapter.ts b/packages/runtime/src/model-adapter.ts
index f18e35661d..bf42b1978c 100644
--- a/packages/runtime/src/model-adapter.ts
+++ b/packages/runtime/src/model-adapter.ts
@@ -164,6 +164,10 @@ export class ModelAdapter {
       toolCalls: true,
       toolResults: true,
       signedThinking: this.runtime.reasoningReplay.kind === 'anthropic-signed',
+      // openai-compatible transports replay stored reasoning unconditionally:
+      // DeepSeek-style endpoints 400 tool calls whose history lacks it, and
+      // relays that don't need the field ignore it. Reasoning is still
+      // recorded to the event log and rendered regardless.
       unsignedThinking: this.runtime.reasoningReplay.kind === 'openai-chat-plaintext',
       openAiResponsesThinking: this.runtime.reasoningReplay.kind === 'openai-responses-item',
     };
diff --git a/packages/runtime/src/model-factory.ts b/packages/runtime/src/model-factory.ts
index ca403081b5..bb799e0f80 100644
--- a/packages/runtime/src/model-factory.ts
+++ b/packages/runtime/src/model-factory.ts
@@ -15,8 +15,9 @@ import { type RuntimeExecutionConnection } from '@maka/core/llm-connections';
 import type { ProviderRuntimeAdapter } from '@maka/core/llm-connections';
 import type { ThinkingLevel } from '@maka/core/model-thinking';
 import {
+  resolveThinkingLevel,
   thinkingOptionsForModel,
-  thinkingVariantsForModel,
+  thinkingVariantsForConnection,
   type ThinkingOptions,
 } from '@maka/core/model-thinking';
 import {
@@ -162,7 +163,7 @@ export function getAIModel(input: ModelFactoryInput): LanguageModelV4 {
           )
         : reasoningTransport.transformRequestBody;
       const model = createOpenAICompatible({
-        name: openAiCompatibleProviderOptionsName(adapter, connection),
+        name: openAiCompatibleProviderName(adapter, connection),
         apiKey,
         baseURL,
         includeUsage: adapter.includeUsage,
@@ -337,8 +338,7 @@ export function buildProviderOptions(
   thinkingLevel?: ThinkingLevel,
 ): SharedV4ProviderOptions {
   const thinkingOptions = thinkingOptionsForModel(connection.providerType, modelId);
-  const variants = thinkingVariantsForModel(connection.providerType, modelId);
-  const level = thinkingLevel && variants.includes(thinkingLevel) ? thinkingLevel : undefined;
+  const level = resolveThinkingLevel(connection, modelId, thinkingLevel);
   switch (connection.providerType) {
     case 'kimi-coding-plan': {
       // Kimi's coding route has no off wire. Check the raw argument, not the
@@ -523,7 +523,8 @@ function buildFamilyWire(
   // Our own declared thinking variants are the authority on that question, so
   // say so with `forceReasoning` rather than letting a name decide.
   if (wire === 'openai-responses') {
-    const reasons = thinkingVariantsForModel(connection.providerType, modelId).length > 0;
+    // Connection-aware: a relay model's declared variants count too.
+    const reasons = thinkingVariantsForConnection(connection, modelId).length > 0;
     return {
       openai: {
         store: false,
@@ -536,7 +537,7 @@ function buildFamilyWire(
   switch (adapter.kind) {
     case 'openai-compatible':
       return {
-        [openAiCompatibleProviderOptionsName(adapter, connection)]: { reasoningEffort },
+        [openAiCompatibleProviderOptionsKey(adapter, connection)]: { reasoningEffort },
       };
     case 'openai':
       return { openai: { reasoningEffort } };
@@ -571,10 +572,11 @@ function buildFamilyWire(
 }
 
 /**
- * providerOptions namespace matches the `name` passed to `createOpenAICompatible`
- * in `getAIModel`; both derive it from this one rule so the two can never drift.
+ * The provider IDENTITY passed as `name` to `createOpenAICompatible` in
+ * `getAIModel` — the raw slug for custom relays. Distinct from the
+ * providerOptions key the SDK wants: see `openAiCompatibleProviderOptionsKey`.
  */
-function openAiCompatibleProviderOptionsName(
+function openAiCompatibleProviderName(
   adapter: ProviderRuntimeAdapter,
   connection: RuntimeExecutionConnection,
 ): string {
@@ -582,3 +584,26 @@ function openAiCompatibleProviderOptionsName(
     ? connection.slug
     : connection.providerType;
 }
+
+// Mirrors @ai-sdk/openai-compatible's own toCamelCase derivation, so the
+// key we emit always matches the alias the SDK resolves.
+function toCamelCase(name: string): string {
+  return name.replace(/[_-]([a-z])/g, (_match, letter: string) => letter.toUpperCase());
+}
+
+/**
+ * The providerOptions key for an openai-compatible model. The SDK still
+ * accepts the raw provider name but flags dashed keys as deprecated (a
+ * `type: 'deprecated'` warning on every doGenerate result); its canonical
+ * key is the camelCase alias. Only the custom-relay path keys options by
+ * the connection slug, so only that path camelCases — built-in adapter
+ * namespaces stay as they were.
+ */
+function openAiCompatibleProviderOptionsKey(
+  adapter: ProviderRuntimeAdapter,
+  connection: RuntimeExecutionConnection,
+): string {
+  return adapter.kind === 'openai-compatible' && adapter.name === 'connection'
+    ? toCamelCase(connection.slug)
+    : connection.providerType;
+}
diff --git a/packages/storage/src/__tests__/connection-store.test.ts b/packages/storage/src/__tests__/connection-store.test.ts
index 1803eab998..2e14b7a1ae 100644
--- a/packages/storage/src/__tests__/connection-store.test.ts
+++ b/packages/storage/src/__tests__/connection-store.test.ts
@@ -100,6 +100,165 @@ describe('FileConnectionStore', () => {
     });
   });
 
+  test('relay profiles sanitize on create and prune when a model is disabled', async () => {
+    await withConnectionStore(async (store) => {
+      const created = await store.create({
+        slug: 'my-relay',
+        name: 'My Relay',
+        providerType: 'openai-compatible',
+        baseUrl: 'https://relay.example/v1',
+        defaultModel: 'reasoner',
+        relayModelProfiles: {
+          reasoner: { thinkingLevels: ['high', 'low'], vision: true },
+          // Not in the seeded selection (only the default starts enabled), so
+          // the ⊆ enabledModelIds invariant drops it at the boundary.
+          'not-enabled': { vision: false },
+        },
+      });
+      assert.deepEqual(created.relayModelProfiles, {
+        reasoner: { thinkingLevels: ['low', 'high'], vision: true },
+      });
+
+      // Enabling a second model and declaring it keeps both profiles under an
+      // update that names no table.
+      await store.update(created.slug, {
+        enabledModelIds: ['reasoner', 'plain'],
+        relayModelProfiles: { reasoner: { vision: true }, plain: { contextWindow: 32_000 } },
+      });
+      // Disabling one model with no profile instruction prunes ONLY its row;
+      // the still-enabled model's declaration survives.
+      const pruned = await store.update(created.slug, { enabledModelIds: ['plain'] });
+      assert.deepEqual(pruned.enabledModelIds, ['plain']);
+      assert.deepEqual(pruned.relayModelProfiles, { plain: { contextWindow: 32_000 } });
+
+      // `null` clears the whole table outright.
+      const cleared = await store.update(created.slug, { relayModelProfiles: null });
+      assert.equal(cleared.relayModelProfiles, undefined);
+      const reloaded = await store.get(created.slug);
+      assert.equal(reloaded?.relayModelProfiles, undefined);
+    });
+  });
+
+  test('create keeps relay profiles for every model in the seeded enabled set', async () => {
+    await withConnectionStore(async (store) => {
+      const created = await store.create({
+        slug: 'import-relay',
+        name: 'Imported Relay',
+        providerType: 'openai-compatible',
+        baseUrl: 'https://relay.example/v1',
+        defaultModel: 'reasoner',
+        enabledModelIds: ['reasoner', 'plain'],
+        relayModelProfiles: {
+          reasoner: { thinkingLevels: ['high'], vision: true },
+          plain: { contextWindow: 16_000 },
+          // Still outside the selection — must not survive create.
+          ghost: { vision: false },
+        },
+      });
+      assert.deepEqual(created.enabledModelIds, ['reasoner', 'plain']);
+      assert.deepEqual(created.relayModelProfiles, {
+        reasoner: { thinkingLevels: ['high'], vision: true },
+        plain: { contextWindow: 16_000 },
+      });
+    });
+  });
+
+  test('relay profile invariants match the catalog codec on every write shape', async () => {
+    await withConnectionStore(async (store) => {
+      // Foreign providers carry no table at all — in create, update, and
+      // snapshot save alike (same gate the catalog codec enforces).
+      await assert.rejects(
+        () =>
+          store.create({
+            slug: 'openai-main',
+            name: 'OpenAI',
+            providerType: 'openai',
+            defaultModel: 'gpt-5',
+            relayModelProfiles: { 'gpt-5': { vision: true } },
+          }),
+        /openai-compatible/,
+      );
+      const plain = await store.create({
+        slug: 'openai-plain',
+        name: 'OpenAI Plain',
+        providerType: 'openai',
+        defaultModel: 'gpt-5',
+      });
+      assert.equal(plain.relayModelProfiles, undefined);
+      await assert.rejects(
+        () => store.update(plain.slug, { relayModelProfiles: { 'gpt-5': { vision: true } } }),
+        /openai-compatible/,
+      );
+      await assert.rejects(
+        () => store.save({ ...plain, relayModelProfiles: { 'gpt-5': { vision: true } } }),
+        /openai-compatible/,
+      );
+
+      const relay = await store.create({
+        slug: 'my-relay',
+        name: 'My Relay',
+        providerType: 'openai-compatible',
+        baseUrl: 'https://relay.example/v1',
+        defaultModel: 'reasoner',
+      });
+
+      // An update's explicit table is pruned against the FINAL selection,
+      // not taken as stated: keys for models outside it never land.
+      const tightened = await store.update(relay.slug, {
+        enabledModelIds: ['reasoner'],
+        relayModelProfiles: {
+          reasoner: { vision: true },
+          'freshly-listed': { vision: false },
+        },
+      });
+      assert.deepEqual(tightened.relayModelProfiles, { reasoner: { vision: true } });
+
+      // save() is the full-snapshot shape of the same rule: a snapshot
+      // naming a model the selection does not have loses that row rather
+      // than stranding it.
+      const saved = await store.save({
+        ...tightened,
+        relayModelProfiles: {
+          reasoner: { vision: false },
+          ghost: { vision: true },
+        },
+      });
+      assert.deepEqual(saved.relayModelProfiles, { reasoner: { vision: false } });
+      const reloaded = await store.get(relay.slug);
+      assert.deepEqual(reloaded?.relayModelProfiles, { reasoner: { vision: false } });
+
+      // Endpoint moves retire the table: declarations belong to the relay
+      // that answered for them, and a same-named model id on relay-b is a
+      // different model — the catalog document store enforces the same.
+      const moved = await store.update(relay.slug, {
+        baseUrl: 'https://relay-b.example/v1',
+      });
+      assert.equal(moved.relayModelProfiles, undefined);
+      const movedReloaded = await store.get(relay.slug);
+      assert.equal(movedReloaded?.relayModelProfiles, undefined);
+
+      // A table riding the moving update declares the NEW endpoint's facts,
+      // so it replaces as written (same rule as the catalog document store).
+      const movedWithTable = await store.update(relay.slug, {
+        baseUrl: 'https://relay-c.example/v1',
+        relayModelProfiles: { reasoner: { contextWindow: 64_000 } },
+      });
+      assert.deepEqual(movedWithTable.relayModelProfiles, {
+        reasoner: { contextWindow: 64_000 },
+      });
+
+      // Restating the SAME persisted endpoint is not a move: the comparison
+      // runs on persisted (trimmed, default-collapsed) values, so a routine
+      // edit that submits the unchanged endpoint cannot retire the table.
+      const restated = await store.update(relay.slug, {
+        baseUrl: 'https://relay-c.example/v1',
+      });
+      assert.deepEqual(restated.relayModelProfiles, {
+        reasoner: { contextWindow: 64_000 },
+      });
+    });
+  });
+
   test('normalizes an updated enabled-model list and writes it as stated', async () => {
     await withConnectionStore(async (store) => {
       const created = await store.create({
diff --git a/packages/storage/src/__tests__/runtime-policy-stores.test.ts b/packages/storage/src/__tests__/runtime-policy-stores.test.ts
index 2fbf073bf8..39df44b6a2 100644
--- a/packages/storage/src/__tests__/runtime-policy-stores.test.ts
+++ b/packages/storage/src/__tests__/runtime-policy-stores.test.ts
@@ -61,6 +61,230 @@ describe('runtime policy stores', () => {
     });
   });
 
+  test('carries, replaces, clears, and endpoint-retires the typed capability table', async () => {
+    await withInteractiveOwner(async ({ stores }) => {
+      const declared = {
+        'relay-model': {
+          thinkingLevels: ['minimal', 'low'] as const,
+          vision: true,
+          contextWindow: 128_000,
+        },
+      };
+      // Create persists the typed projection — and only the projection
+      // (the extras bag never entered the picture).
+      const connection = await createConnection(stores, 0, {
+        ...connectionDraft('my-relay', 'openai-compatible', 'My Relay'),
+        baseUrl: 'https://relay.example/v1',
+        enabledModelIds: ['relay-model'],
+        relayModelProfiles: declared,
+      });
+      assert.deepEqual(connection.relayModelProfiles, declared);
+
+      // Replacement is total: a new table swaps in, null clears.
+      const replaced = await stores.connectionCatalog.update({
+        expected: connectionBasis(connection),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+          relayModelProfiles: { 'relay-model': { vision: false } },
+        },
+      });
+      assert.equal(replaced.kind, 'committed');
+      if (replaced.kind !== 'committed') return;
+      const afterReplace = replaced.snapshot.connections[0];
+      assert.deepEqual(afterReplace?.relayModelProfiles, { 'relay-model': { vision: false } });
+
+      const cleared = await stores.connectionCatalog.update({
+        expected: connectionBasis(afterReplace!),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+          relayModelProfiles: null,
+        },
+      });
+      assert.equal(cleared.kind, 'committed');
+      if (cleared.kind !== 'committed') return;
+      const afterClear = cleared.snapshot.connections[0];
+      assert.equal(afterClear?.relayModelProfiles, undefined);
+
+      // An absent key leaves the table untouched (name-only saves stay
+      // capability-blind), and an UNANNOUNCED endpoint change retires the
+      // table along with the fetched inventory: the new baseUrl fronts
+      // different models, and the old declarations must not outlive them.
+      const retained = await stores.connectionCatalog.update({
+        expected: connectionBasis(afterClear!),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+          relayModelProfiles: declared,
+        },
+      });
+      assert.equal(retained.kind, 'committed');
+      if (retained.kind !== 'committed') return;
+      const nameOnly = await stores.connectionCatalog.update({
+        expected: connectionBasis(retained.snapshot.connections[0]!),
+        changes: {
+          name: 'Renamed Relay',
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+        },
+      });
+      assert.equal(nameOnly.kind, 'committed');
+      if (nameOnly.kind !== 'committed') return;
+      assert.deepEqual(nameOnly.snapshot.connections[0]?.relayModelProfiles, declared);
+
+      const endpointMoved = await stores.connectionCatalog.update({
+        expected: connectionBasis(nameOnly.snapshot.connections[0]!),
+        changes: {
+          name: 'Renamed Relay',
+          baseUrl: 'https://other-relay.example/v1',
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+        },
+      });
+      assert.equal(endpointMoved.kind, 'committed');
+      if (endpointMoved.kind !== 'committed') return;
+      assert.equal(endpointMoved.snapshot.connections[0]?.relayModelProfiles, undefined);
+      assert.deepEqual(endpointMoved.snapshot.connections[0]?.models, []);
+
+      // …unless the same update submits a table of its own — then the table
+      // belongs to the NEW endpoint and is stored. Config import relies on
+      // this exact single-call shape.
+      const movedWithTable = await stores.connectionCatalog.update({
+        expected: connectionBasis(endpointMoved.snapshot.connections[0]!),
+        changes: {
+          name: 'Renamed Relay',
+          baseUrl: 'https://third-relay.example/v1',
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+          relayModelProfiles: declared,
+        },
+      });
+      assert.equal(movedWithTable.kind, 'committed');
+      if (movedWithTable.kind !== 'committed') return;
+      assert.deepEqual(movedWithTable.snapshot.connections[0]?.relayModelProfiles, declared);
+      assert.deepEqual(movedWithTable.snapshot.connections[0]?.models, []);
+    });
+  });
+
+  test('an untouched profile table is pruned to the new enabled-model selection', async () => {
+    await withInteractiveOwner(async ({ stores }) => {
+      const declared = {
+        'relay-model': { vision: true as const },
+        'relay-model-2': { contextWindow: 64_000 as const },
+      };
+      const connection = await createConnection(stores, 0, {
+        ...connectionDraft('prune-relay', 'openai-compatible', 'Prune Relay'),
+        baseUrl: 'https://relay.example/v1',
+        enabledModelIds: ['relay-model', 'relay-model-2'],
+        relayModelProfiles: declared,
+      });
+      assert.deepEqual(connection.relayModelProfiles, declared);
+
+      const disabled = await stores.connectionCatalog.update({
+        expected: connectionBasis(connection),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['relay-model'],
+        },
+      });
+      assert.equal(disabled.kind, 'committed');
+      if (disabled.kind !== 'committed') return;
+      // No profile instruction rode along, so the ⊆ enabledModelIds rule is
+      // the store's job: the disabled model's declaration is gone, never
+      // stranded as a stale key the settings page cannot see.
+      assert.deepEqual(disabled.snapshot.connections[0]?.relayModelProfiles, {
+        'relay-model': { vision: true },
+      });
+
+      // Pruning everything degrades to "no table" — never a stored `{}`.
+      const allDisabled = await stores.connectionCatalog.update({
+        expected: connectionBasis(disabled.snapshot.connections[0]!),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: [],
+        },
+      });
+      assert.equal(allDisabled.kind, 'committed');
+      if (allDisabled.kind !== 'committed') return;
+      assert.equal(allDisabled.snapshot.connections[0]?.relayModelProfiles, undefined);
+    });
+  });
+
+  test('a model refresh prunes profiles for models the inventory retired', async () => {
+    await withInteractiveOwner(async ({ stores }) => {
+      const connection = await createConnection(stores, 0, {
+        ...connectionDraft('refresh-relay', 'openai-compatible', 'Refresh Relay'),
+        baseUrl: 'https://relay.example/v1',
+        enabledModelIds: ['model-a', 'model-b'],
+        relayModelProfiles: {
+          'model-a': { vision: true },
+          'model-b': { contextWindow: 64_000 },
+        },
+      });
+      assert.deepEqual(connection.relayModelProfiles, {
+        'model-a': { vision: true },
+        'model-b': { contextWindow: 64_000 },
+      });
+
+      // A /models fetch needs a credential first — discovery is refused for
+      // credential-less connections before any of this runs.
+      const credential = await stores.credentialVault.set({
+        locator: connectionCredential(connection, 'api_key'),
+        expected: null,
+        secret: 'sk-refresh',
+      });
+      assert.equal(credential.kind, 'committed');
+
+      // The /models refresh drops model-a from the live inventory. The
+      // refresh write bypasses the canonical decoder — without pruning the
+      // table, model-a's profile would persist and every later canonical
+      // read would reject the document.
+      const fetch = await stores.operations.beginModelFetch(connection.connectionId);
+      assert.equal(fetch.kind, 'ready');
+      if (fetch.kind !== 'ready') return;
+      const discovered = await stores.operations.completeModelFetch(fetch.ticket, {
+        models: [{ id: 'model-b' }],
+        source: 'fetched',
+        fetchedAt: 43,
+      });
+      assert.equal(discovered.kind, 'committed');
+      if (discovered.kind !== 'committed') return;
+      const after = discovered.snapshot.connections[0];
+      assert.deepEqual(after?.enabledModelIds, ['model-b']);
+      assert.deepEqual(after?.relayModelProfiles, { 'model-b': { contextWindow: 64_000 } });
+
+      // The document must survive a canonical reload: the next mutation
+      // re-decodes persisted state, and a stranding here would have raised
+      // invalid_document instead of committing.
+      const roundtrip = await stores.connectionCatalog.update({
+        expected: connectionBasis(after!),
+        changes: {
+          name: connection.name,
+          baseUrl: connection.baseUrl,
+          enabled: true,
+          enabledModelIds: ['model-b'],
+        },
+      });
+      assert.equal(roundtrip.kind, 'committed');
+      if (roundtrip.kind !== 'committed') return;
+      assert.deepEqual(roundtrip.snapshot.connections[0]?.relayModelProfiles, {
+        'model-b': { contextWindow: 64_000 },
+      });
+    });
+  });
+
   test('commits closed policy mutations, canonicalizes proxy hosts, and preserves connection identity', async () => {
     await withInteractiveOwner(async ({ root, stores }) => {
       const policy = await stores.runtimePolicy.mutate(personalizationMutation(0));
@@ -135,6 +359,7 @@ describe('runtime policy stores', () => {
         baseUrl: ' https://Gateway.EXAMPLE:443/v1 ',
         enabled: true,
         enabledModelIds: ['gpt-5'],
+        relayModelProfiles: null,
       };
       await assert.rejects(
         () =>
@@ -681,6 +906,7 @@ describe('runtime policy stores', () => {
           baseUrl: current.baseUrl,
           enabled: true,
           enabledModelIds: [],
+          relayModelProfiles: null,
         },
       });
       assert.equal(emptied.kind, 'committed');
@@ -871,6 +1097,7 @@ describe('runtime policy stores', () => {
           baseUrl: current.baseUrl,
           enabled: true,
           enabledModelIds: ['gpt-5-mini'],
+          relayModelProfiles: null,
         },
       });
       assert.equal(updated.kind, 'committed');
@@ -1486,6 +1713,7 @@ describe('runtime policy stores', () => {
           baseUrl: 'https://gateway.example/v1',
           enabled: true,
           enabledModelIds: connection.enabledModelIds,
+          relayModelProfiles: null,
         },
       });
       assert.equal(endpointUpdate.kind, 'committed');
@@ -1513,6 +1741,7 @@ describe('runtime policy stores', () => {
           baseUrl: connection.baseUrl,
           enabled: true,
           enabledModelIds: ['gpt-5-mini'],
+          relayModelProfiles: null,
         },
       });
       assert.equal(modelSelectionUpdate.kind, 'committed');
@@ -1932,6 +2161,7 @@ describe('runtime policy stores', () => {
           name: 'Current revision',
           enabled: true,
           enabledModelIds: ['gpt-5'],
+          relayModelProfiles: null,
         },
       });
       assert.equal(updatedResult.kind, 'committed');
@@ -2299,6 +2529,7 @@ describe('runtime policy stores', () => {
           name: 'Claude renamed',
           enabled: current.enabled,
           enabledModelIds: current.enabledModelIds,
+          relayModelProfiles: null,
         },
       });
       assert.equal(updated.kind, 'committed');
diff --git a/packages/storage/src/connection-store.ts b/packages/storage/src/connection-store.ts
index 835f4662d3..ee77e613ea 100644
--- a/packages/storage/src/connection-store.ts
+++ b/packages/storage/src/connection-store.ts
@@ -13,6 +13,8 @@ import {
   type LlmConnection,
   type UpdateConnectionInput,
 } from '@maka/core/llm-connections';
+import { pruneRelayModelProfiles } from '@maka/core/model-thinking';
+import { relayProfilesForStorage } from './relay-profile-store.js';
 
 export interface ConnectionStore {
   list(): Promise<LlmConnection[]>;
@@ -75,6 +77,20 @@ class FileConnectionStore implements ConnectionStore {
       const now = Date.now();
       const baseUrl = persistedBaseUrl(input.providerType, input.baseUrl);
       const defaultModel = input.defaultModel || defaults.fallbackModels[0] || '';
+      // Profiles prune against the same selection the connection will store —
+      // not just the default. Import/create can seed enabledModelIds + profiles
+      // together; using only defaultModel would drop every non-default profile.
+      const enabledModelIds = connectionEnabledModelIds({
+        defaultModel,
+        // Only fill a missing selection. Explicit [] / subset stays as stated.
+        enabledModelIds:
+          input.enabledModelIds ?? defaultEnabledModelIdsWhenOmitted(input.providerType),
+      });
+      const relayModelProfiles = relayProfilesForStorage(
+        input.providerType,
+        input.relayModelProfiles,
+        enabledModelIds,
+      );
       const next: LlmConnection = {
         slug: input.slug,
         name: input.name || defaults.label,
@@ -82,15 +98,11 @@ class FileConnectionStore implements ConnectionStore {
         ...(baseUrl ? { baseUrl } : {}),
         defaultModel,
         enabled: true,
-        enabledModelIds: connectionEnabledModelIds({
-          defaultModel,
-          // Only fill a missing selection. Explicit [] / subset stays as stated.
-          enabledModelIds:
-            input.enabledModelIds ?? defaultEnabledModelIdsWhenOmitted(input.providerType),
-        }),
+        enabledModelIds,
         createdAt: now,
         updatedAt: now,
         ...(input.extras ? { extras: input.extras } : {}),
+        ...(relayModelProfiles === undefined ? {} : { relayModelProfiles }),
       };
       file.connections.push(next);
       claimVacantWorkspaceDefault(file, next);
@@ -181,13 +193,18 @@ class FileConnectionStore implements ConnectionStore {
         defaultModel = reconciled.defaultModel;
         enabledModelIds = reconciled.enabledModelIds;
       }
+      // Endpoint-keyed semantics, matching the catalog document store: the
+      // comparison must be between the CANONICALIZED endpoints — a patch
+      // restating the current endpoint (or its equivalent) is not a move.
+      const nextBaseUrl =
+        patch.baseUrl !== undefined
+          ? persistedBaseUrl(current.providerType, patch.baseUrl)
+          : current.baseUrl;
+      const endpointChanged = nextBaseUrl !== current.baseUrl;
       const next: LlmConnection = {
         ...current,
         name: patch.name ?? current.name,
-        baseUrl:
-          patch.baseUrl !== undefined
-            ? persistedBaseUrl(current.providerType, patch.baseUrl)
-            : current.baseUrl,
+        baseUrl: nextBaseUrl,
         defaultModel,
         enabled: patch.enabled ?? current.enabled,
         enabledModelIds,
@@ -210,6 +227,24 @@ class FileConnectionStore implements ConnectionStore {
             ? undefined
             : current.lastTestMessage,
         extras: patch.extras ?? current.extras,
+        // Profiles only ever describe enabled models of THIS endpoint on a
+        // relay connection: an explicit table passes the same gate+prune
+        // every write shape applies (a new table in a moving update declares
+        // itself bound to the NEW endpoint, matching the catalog store);
+        // an untouched one retires with the old endpoint — declarations
+        // belong to the relay that answered for them, and a model id that
+        // coincides across endpoints is a different model — and only then
+        // is pruned against the selection just computed.
+        relayModelProfiles:
+          patch.relayModelProfiles === undefined
+            ? endpointChanged
+              ? undefined
+              : pruneRelayModelProfiles(current.relayModelProfiles, enabledModelIds)
+            : relayProfilesForStorage(
+                current.providerType,
+                patch.relayModelProfiles,
+                enabledModelIds,
+              ),
         updatedAt: Date.now(),
       };
       file.connections[index] = next;
@@ -254,14 +289,23 @@ class FileConnectionStore implements ConnectionStore {
       const now = Date.now();
       // save() is a full-replace write; route it through persistedBaseUrl too,
       // or a caller handing back defaults.baseUrl (e.g. OAuth sync) pins the
-      // connection to the current default.
+      // connection to the current default. Profiles come from the same
+      // gate+prune as create/update — snapshot semantics must not bypass
+      // either profile invariant.
       const baseUrl = persistedBaseUrl(connection.providerType, connection.baseUrl);
-      const { baseUrl: _omit, ...rest } = connection;
+      const { baseUrl: _omit, relayModelProfiles: _rawProfiles, ...rest } = connection;
+      const enabledModelIds = connectionEnabledModelIds(connection);
+      const relayModelProfiles = relayProfilesForStorage(
+        connection.providerType,
+        connection.relayModelProfiles,
+        enabledModelIds,
+      );
       const next: LlmConnection = {
         ...rest,
         ...(baseUrl ? { baseUrl } : {}),
         enabled: connection.enabled ?? true,
-        enabledModelIds: connectionEnabledModelIds(connection),
+        enabledModelIds,
+        ...(relayModelProfiles === undefined ? {} : { relayModelProfiles }),
         createdAt: connection.createdAt ?? now,
         updatedAt: connection.updatedAt ?? now,
       };
diff --git a/packages/storage/src/relay-profile-store.ts b/packages/storage/src/relay-profile-store.ts
new file mode 100644
index 0000000000..bfc2d0efa0
--- /dev/null
+++ b/packages/storage/src/relay-profile-store.ts
@@ -0,0 +1,29 @@
+import type { ProviderType } from '@maka/core/llm-connections';
+import {
+  normalizeRelayModelProfiles,
+  pruneRelayModelProfiles,
+  type RelayModelProfiles,
+} from '@maka/core/model-thinking';
+
+/**
+ * The one write-side check every connection-store boundary applies to a
+ * relay profile table, regardless of write shape (create / partial update /
+ * full-snapshot save): profiles exist only on openai-compatible connections
+ * — a non-empty table anywhere else is the same invalid input the catalog
+ * codec rejects — and only for models currently enabled on the connection,
+ * so a stale key never survives the selection a store was just handed.
+ */
+export function relayProfilesForStorage(
+  providerType: ProviderType,
+  table: unknown,
+  enabledModelIds: readonly string[],
+): RelayModelProfiles | undefined {
+  const normalized = normalizeRelayModelProfiles(table);
+  if (providerType !== 'openai-compatible') {
+    if (normalized !== undefined) {
+      throw new Error('relay model profiles are only supported for openai-compatible connections');
+    }
+    return undefined;
+  }
+  return pruneRelayModelProfiles(normalized, enabledModelIds);
+}
diff --git a/packages/storage/src/runtime-policy/connection-catalog-document.ts b/packages/storage/src/runtime-policy/connection-catalog-document.ts
index 3fc45c4f9d..c20cafbbbc 100644
--- a/packages/storage/src/runtime-policy/connection-catalog-document.ts
+++ b/packages/storage/src/runtime-policy/connection-catalog-document.ts
@@ -24,6 +24,7 @@ import {
   type UpdateCatalogConnectionInput,
 } from '@maka/core/runtime-policy';
 import { PROVIDER_DEFAULTS, reconcileConnectionAfterModelFetch } from '@maka/core/llm-connections';
+import { pruneRelayModelProfiles } from '@maka/core/model-thinking';
 import { deepFreeze, nextRevision, record, revision, unique } from './codec.js';
 import {
   codecError,
@@ -174,6 +175,31 @@ export class ConnectionCatalogDocumentOwner {
       ...(changes.baseUrl === undefined ? {} : { baseUrl: changes.baseUrl }),
       enabled: changes.enabled,
       enabledModelIds: changes.enabledModelIds,
+      // Profile-table semantics, in order:
+      //  - the store invariant: profiles exist only for enabled models, so a
+      //    selection change prunes whatever no longer qualifies (disabling a
+      //    model deletes its profile);
+      //  - a table replaces wholesale — it wins even over an endpoint change
+      //    in the same update, because a writer submitting a new endpoint and
+      //    a new table declares that the table belongs to the new endpoint
+      //    (config import does exactly this);
+      //  - null clears;
+      //  - absent leaves the stored table alone, except that an endpoint
+      //    change retires it: declarations are endpoint-keyed like the model
+      //    inventory, and the old table must not outlive the relay it
+      //    described.
+      ...(changes.relayModelProfiles === undefined
+        ? endpointChanged || previous.relayModelProfiles === undefined
+          ? {}
+          : {
+              relayModelProfiles: pruneRelayModelProfiles(
+                previous.relayModelProfiles,
+                changes.enabledModelIds,
+              ),
+            }
+        : changes.relayModelProfiles === null
+          ? {}
+          : { relayModelProfiles: changes.relayModelProfiles }),
       models: endpointChanged ? [] : previous.models,
       ...(endpointChanged || previous.modelSource === undefined
         ? {}
@@ -278,8 +304,18 @@ export class ConnectionCatalogDocumentOwner {
     const defaultTarget = currentDefaultTarget
       ? { connectionId: previous.connectionId, modelId: reconciled.defaultModel }
       : current.defaultTarget;
+    // A refresh is a new enabledModelIds authority on the same endpoint:
+    // profiles keyed by a model the refresh dropped would violate the
+    // subset invariant, and this write path bypasses the canonical decoder,
+    // so prune here or the persisted document is un-loadable on next read.
+    const relayModelProfiles = pruneRelayModelProfiles(
+      previous.relayModelProfiles,
+      reconciled.enabledModelIds,
+    );
+    const { relayModelProfiles: _staleProfiles, ...previousWithoutProfiles } = previous;
     const discovered: ConnectionCatalogEntry = {
-      ...previous,
+      ...previousWithoutProfiles,
+      ...(relayModelProfiles ? { relayModelProfiles } : {}),
       revision: nextRevision(previous.revision),
       enabledModelIds: reconciled.enabledModelIds,
       models: result.models,