diff --git a/apps/web/package.json b/apps/web/package.json
index 2bab9e262..75a4ca003 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -42,6 +42,7 @@
     "@unocss/preset-wind3": "^66.5.10",
     "@unocss/reset": "^66.5.10",
     "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/test-utils": "^2.4.11",
     "happy-dom": "^20.0.0",
     "unocss": "^66.5.10",
     "unocss-preset-animations": "^1.3.0",
diff --git a/apps/web/src/api/test-fixtures.ts b/apps/web/src/api/test-fixtures.ts
new file mode 100644
index 000000000..bfb3ef46a
--- /dev/null
+++ b/apps/web/src/api/test-fixtures.ts
@@ -0,0 +1,36 @@
+// Test-only fixtures that satisfy the `@floway-dev/protocols/common` PublicModel
+// shape. Production rows always carry every required field — see the gateway's
+// `toPublicModel` and `toControlPlaneModel` — but tests want to fan out partials
+// without retyping `object` / `type` / `display_name` / `limits` / `endpoints`
+// every time. The factories merge `over` last so any field the test sets wins.
+
+import type { ControlPlaneModel } from './types.ts';
+
+const baseFields = (): Omit<ControlPlaneModel, 'id' | 'upstreams'> => ({
+  object: 'model',
+  type: 'model',
+  display_name: '',
+  limits: {},
+  kind: 'chat',
+  endpoints: { chatCompletions: {} },
+});
+
+export const buildRealModel = (over: Partial<ControlPlaneModel> & { id: string }): ControlPlaneModel => ({
+  ...baseFields(),
+  upstreams: [{ id: 'u1', name: 'U1', kind: 'custom' }],
+  ...over,
+});
+
+export const buildAliasModel = (over: Partial<ControlPlaneModel> & { id: string }): ControlPlaneModel => ({
+  ...baseFields(),
+  upstreams: [],
+  aliasedFrom: { name: over.id, kind: 'chat', selection: 'first-available', targets: [] },
+  ...over,
+});
+
+export const buildUnlistedModel = (over: Partial<ControlPlaneModel> & { id: string }): ControlPlaneModel => ({
+  ...baseFields(),
+  upstreams: [{ id: 'u1', name: 'U1', kind: 'custom' }],
+  unlisted: true,
+  ...over,
+});
diff --git a/apps/web/src/api/types.ts b/apps/web/src/api/types.ts
index 088891e1b..80371f289 100644
--- a/apps/web/src/api/types.ts
+++ b/apps/web/src/api/types.ts
@@ -1,16 +1,30 @@
 // Control-plane DTOs the SPA consumes — serialized shapes the gateway emits at /api.
 
 import type {
+  AliasKind,
+  AliasRules,
+  AliasSelection,
+  AliasTarget,
+  AnnouncedMetadata,
   BillingDimension,
+  ChatAliasRules,
+  ChatModelInfo,
+  ModelAlias,
   ModelEndpointKey,
   ModelEndpoints,
   ModelKind,
   ModelPricing,
+  PublicModel,
+  PublicModelLimits,
 } from '@floway-dev/protocols/common';
 import type { AddressableForm, ModelPrefixConfig } from '@floway-dev/provider/model-prefix';
 
 export type { BillingDimension, ModelEndpointKey, ModelEndpoints, ModelKind, ModelPricing };
 export type { AddressableForm, ModelPrefixConfig };
+export type {
+  AliasKind, AliasRules, AliasSelection, AliasTarget, AnnouncedMetadata, ChatAliasRules, ChatModelInfo, ModelAlias,
+  PublicModel, PublicModelLimits,
+};
 
 export type UpstreamProviderKind = 'custom' | 'azure' | 'copilot' | 'codex' | 'claude-code' | 'ollama';
 
@@ -38,7 +52,7 @@ export interface UpstreamModelConfig {
   kind: ModelKind;
   endpoints: ModelEndpoints;
   display_name?: string;
-  limits?: ModelLimits;
+  limits?: PublicModelLimits;
   cost?: ModelPricing;
   flagOverrides?: { enabled: boolean; values: Record<string, boolean> };
   chat?: UpstreamChatConfig;
@@ -57,7 +71,7 @@ export interface CustomRawModel {
   name?: string;
   created?: number;
   owned_by?: string;
-  limits?: ModelLimits;
+  limits?: PublicModelLimits;
   cost?: ModelPricing;
   kind?: ModelKind;
 }
@@ -322,26 +336,6 @@ export interface ApiKey {
   dump_retention_seconds: number | null;
 }
 
-export interface ModelEndpointInfo {
-  url: string;
-  doc?: string;
-}
-
-export interface ModelLimits {
-  max_context_window_tokens?: number;
-  max_prompt_tokens?: number;
-  max_output_tokens?: number;
-}
-
-export interface PublicModel {
-  id: string;
-  display_name?: string;
-  limits?: ModelLimits;
-  endpoints?: Record<string, ModelEndpointInfo>;
-  cost?: ModelPricing;
-  kind?: ModelKind;
-}
-
 export interface ControlPlaneModel extends PublicModel {
   upstreams: { kind: UpstreamProviderKind; id: string; name: string }[];
 }
diff --git a/apps/web/src/components/alias-edit/AliasEditDialog.vue b/apps/web/src/components/alias-edit/AliasEditDialog.vue
new file mode 100644
index 000000000..3a586514a
--- /dev/null
+++ b/apps/web/src/components/alias-edit/AliasEditDialog.vue
@@ -0,0 +1,363 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+
+import AliasTargetRow from './AliasTargetRow.vue';
+import { computeAnnouncedMetadata } from './announced-metadata.ts';
+import { computeAliasLevelWarnings, realModelIdsOfKind } from './warnings.ts';
+import { callApi, useApi } from '../../api/client.ts';
+import type { AliasKind, AliasSelection, AliasTarget, AnnouncedMetadata, ModelAlias } from '../../api/types.ts';
+import { useModelAliases } from '../../composables/useModelAliases.ts';
+import { useRawModelsStore } from '../../composables/useModels.ts';
+import ChatMetadataEditor from '../shared/ChatMetadataEditor.vue';
+import { Button, Dialog, Input, Select, Switch } from '@floway-dev/ui';
+
+const open = defineModel<boolean>('open', { required: true });
+
+const props = defineProps<{
+  /** null = create; non-null = edit. */
+  record: ModelAlias | null;
+}>();
+
+const emit = defineEmits<{
+  saved: [];
+}>();
+
+const api = useApi();
+const aliasesStore = useModelAliases();
+const modelsStore = useRawModelsStore();
+
+const mode = computed<'create' | 'edit'>(() => (props.record ? 'edit' : 'create'));
+
+// Switching kind discards rule state — a chat-only rule must not survive a
+// switch into embedding/image.
+const emptyRulesFor = (k: AliasKind): AliasTarget['rules'] => (k === 'chat' ? {} : {} as Record<string, never>);
+
+const blankTarget = (k: AliasKind): AliasTarget => ({ target_model_id: '', rules: emptyRulesFor(k) });
+
+const aliasName = ref(props.record?.name ?? '');
+const displayName = ref(props.record?.display_name ?? '');
+const kind = ref<AliasKind>(props.record?.kind ?? 'chat');
+const selection = ref<AliasSelection>(props.record?.selection ?? 'first-available');
+const visibleInModelsList = ref(props.record?.visible_in_models_list ?? true);
+
+const targets = ref<AliasTarget[]>(
+  props.record
+    ? props.record.targets.map(t => ({ target_model_id: t.target_model_id, rules: { ...t.rules } as AliasTarget['rules'] }))
+    : [blankTarget(kind.value)],
+);
+
+const setKind = (k: AliasKind) => {
+  kind.value = k;
+  targets.value = targets.value.map(t => ({ target_model_id: t.target_model_id, rules: emptyRulesFor(k) }));
+};
+
+const addTarget = () => { targets.value = [...targets.value, blankTarget(kind.value)]; };
+
+const updateTarget = (idx: number, next: AliasTarget) => {
+  const copy = targets.value.slice();
+  copy[idx] = next;
+  targets.value = copy;
+};
+
+const moveTarget = (idx: number, delta: -1 | 1) => {
+  const j = idx + delta;
+  if (j < 0 || j >= targets.value.length) return;
+  const copy = targets.value.slice();
+  [copy[idx], copy[j]] = [copy[j], copy[idx]];
+  targets.value = copy;
+};
+
+const removeTarget = (idx: number) => {
+  if (targets.value.length <= 1) return;
+  targets.value = targets.value.filter((_, i) => i !== idx);
+};
+
+// ── Announced metadata ──────────────────────────────────────────────────
+//
+// The override is a sparse AnnouncedMetadata; null means "compute
+// automatically at listing time". When the operator flips the override
+// switch on, we freeze the current computed view into the buffer so the
+// editor starts from a sensible baseline; flipping back off discards
+// the buffer and resets the wire payload to null so the next render
+// snaps back to the live computed view.
+
+const announcedOverride = ref<AnnouncedMetadata | null>(props.record?.announced_metadata ?? null);
+
+const computedAnnouncedMetadata = computed<AnnouncedMetadata>(() =>
+  computeAnnouncedMetadata(targets.value, kind.value, modelsStore.models.value));
+
+const overrideEnabled = computed<boolean>(() => announcedOverride.value !== null);
+
+const showAnnouncedSection = computed(() => kind.value !== 'image');
+
+const announcedSectionExpanded = ref(false);
+const toggleAnnouncedSection = () => { announcedSectionExpanded.value = !announcedSectionExpanded.value; };
+
+const setOverrideEnabled = (on: boolean) => {
+  if (on) {
+    // Freeze the live computed view into the working state — the
+    // operator's edits start from what the wire surface would have
+    // emitted, so a blank override doesn't visually erase the alias's
+    // metadata.
+    announcedOverride.value = structuredClone(computedAnnouncedMetadata.value);
+  } else {
+    announcedOverride.value = null;
+  }
+};
+
+// Source-of-truth for the editor's `modelValue`: the override buffer when
+// the operator is editing, the live computed snapshot otherwise.
+const announcedEditorValue = computed<AnnouncedMetadata>(
+  () => announcedOverride.value ?? computedAnnouncedMetadata.value,
+);
+
+const onAnnouncedChange = (next: AnnouncedMetadata | undefined) => {
+  // Editor only fires this in manual mode (auto is read-only). Persist
+  // an empty object rather than null so the override stays "on" even
+  // when the operator clears every field.
+  announcedOverride.value = next ?? {};
+};
+
+// Switching alias kind discards a chat-only override since the
+// schema would reject it on save (e.g. embedding aliases can not
+// carry a `chat` block).
+watch(kind, k => {
+  if (announcedOverride.value === null) return;
+  if (k === 'image') {
+    announcedOverride.value = null;
+    return;
+  }
+  if (k === 'embedding' && announcedOverride.value.chat !== undefined) {
+    const { chat: _drop, ...rest } = announcedOverride.value;
+    announcedOverride.value = rest;
+  }
+});
+
+// Suggestion list for every target-id combobox. Filtered to non-alias
+// catalog rows of the alias's current kind so an embedding alias only
+// hints at embedding models. Aliases never re-enter the alias layer at
+// runtime, so they're excluded too. Operators can still type any
+// opaque string — the list is a hint, not a constraint.
+const targetIdItems = computed(() => realModelIdsOfKind(modelsStore.models.value, kind.value));
+
+// Alias-level warnings on the live dialog state. Re-projects name +
+// targets to the structural shape `computeAliasLevelWarnings` accepts so
+// the Settings card row and the dialog read the same surface.
+const aliasLevelWarnings = computed(() => computeAliasLevelWarnings(
+  { name: aliasName.value.trim(), targets: targets.value },
+  modelsStore.models.value,
+));
+
+const saving = ref(false);
+const saveError = ref<string | null>(null);
+
+// Collision check excludes the current record so an in-place edit of an
+// unchanged name is allowed.
+const validationError = computed<string | null>(() => {
+  const trimmed = aliasName.value.trim();
+  if (trimmed === '') return 'Alias id is required';
+  const collisions = (aliasesStore.aliases.value ?? []).filter(a => a.name === trimmed && a.name !== props.record?.name);
+  if (collisions.length > 0) return `An alias with id "${trimmed}" already exists`;
+  if (targets.value.some(t => t.target_model_id.trim() === '')) return 'Every target needs a model id';
+  return null;
+});
+
+const canSave = computed(() => validationError.value === null && !saving.value);
+
+const save = async () => {
+  saveError.value = validationError.value;
+  if (saveError.value !== null) return;
+
+  const trimmedName = aliasName.value.trim();
+  const trimmedDisplay = displayName.value.trim();
+  // The Hono RPC body type widens the per-target rules to the loose
+  // `Record<string, unknown>` it gets from the Zod schema, and likewise
+  // widens `announced_metadata` to its zod-inferred shape (mutable
+  // modality arrays). Cast through the loose shapes so the typed body
+  // matches what the schema accepts.
+  const body = {
+    name: trimmedName,
+    kind: kind.value,
+    selection: selection.value,
+    display_name: trimmedDisplay === '' ? null : trimmedDisplay,
+    visible_in_models_list: visibleInModelsList.value,
+    targets: targets.value.map(t => ({
+      target_model_id: t.target_model_id.trim(),
+      rules: t.rules as Record<string, unknown>,
+    })),
+    announced_metadata: announcedOverride.value as Record<string, unknown> | null,
+    sort_order: props.record?.sort_order ?? 0,
+  };
+
+  saving.value = true;
+  try {
+    if (mode.value === 'create') {
+      const { error } = await callApi(() => api.api.aliases.$post({ json: body }));
+      if (error) { saveError.value = error.message; return; }
+    } else if (props.record) {
+      const oldName = props.record.name;
+      const { error } = await callApi(() => api.api.aliases[':name'].$put({
+        param: { name: oldName },
+        json: body,
+      }));
+      if (error) { saveError.value = error.message; return; }
+    }
+    emit('saved');
+    open.value = false;
+  } finally {
+    saving.value = false;
+  }
+};
+
+const title = computed(() => mode.value === 'create' ? 'Create Alias' : `Edit Alias: ${props.record?.name ?? ''}`);
+
+const KIND_OPTIONS: { value: AliasKind; label: string }[] = [
+  { value: 'chat', label: 'Chat' },
+  { value: 'embedding', label: 'Embedding' },
+  { value: 'image', label: 'Image' },
+];
+</script>
+
+<template>
+  <Dialog v-model:open="open" :title="title" size="xl">
+    <div class="space-y-5">
+      <p v-if="saveError" class="rounded-md border border-accent-rose/40 bg-accent-rose/10 px-3 py-2 text-sm text-accent-rose">
+        {{ saveError }}
+      </p>
+
+      <div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Alias id</label>
+          <Input v-model="aliasName" placeholder="my-alias-id" class="font-mono" />
+        </div>
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Display name</label>
+          <Input v-model="displayName" :placeholder="aliasName.trim() === '' ? 'my-alias-id' : aliasName.trim()" />
+        </div>
+      </div>
+
+      <div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Kind</label>
+          <Select :model-value="kind" :options="KIND_OPTIONS" @update:model-value="v => setKind(v as AliasKind)" />
+        </div>
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Selection</label>
+          <div class="inline-flex h-9 items-center overflow-hidden rounded-[10px] border border-white/[0.14] bg-surface-700 text-xs">
+            <button
+              type="button"
+              class="px-3 py-1.5 transition-colors"
+              :class="selection === 'first-available' ? 'bg-accent-cyan/20 text-accent-cyan' : 'text-gray-400 hover:text-gray-200'"
+              @click="selection = 'first-available'"
+            >First available</button>
+            <button
+              type="button"
+              class="px-3 py-1.5 transition-colors"
+              :class="selection === 'random' ? 'bg-accent-cyan/20 text-accent-cyan' : 'text-gray-400 hover:text-gray-200'"
+              @click="selection = 'random'"
+            >Random</button>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <div class="mb-2 flex items-start justify-between gap-3">
+          <div class="min-w-0">
+            <h4 class="text-sm font-semibold text-gray-300">Models</h4>
+            <p class="mt-0.5 text-xs text-gray-500">Click a model id to edit.</p>
+          </div>
+          <Button variant="secondary" size="sm" @click="addTarget">Add target</Button>
+        </div>
+        <div class="space-y-2">
+          <AliasTargetRow
+            v-for="(t, idx) in targets"
+            :key="idx"
+            :model-value="t"
+            :kind="kind"
+            :target-id-items="targetIdItems"
+            :models="modelsStore.models.value"
+            :is-first="idx === 0"
+            :is-last="idx === targets.length - 1"
+            :is-sole="targets.length === 1"
+            @update:model-value="(next: AliasTarget) => updateTarget(idx, next)"
+            @move-up="moveTarget(idx, -1)"
+            @move-down="moveTarget(idx, 1)"
+            @remove="removeTarget(idx)"
+          />
+        </div>
+      </div>
+
+      <section v-if="showAnnouncedSection" class="border-t border-white/[0.06] pt-5">
+        <div class="flex items-center justify-between gap-3">
+          <button
+            type="button"
+            class="flex flex-1 min-w-0 items-start gap-2 text-left"
+            :aria-expanded="announcedSectionExpanded"
+            aria-controls="announced-metadata-body"
+            @click="toggleAnnouncedSection"
+          >
+            <svg
+              class="mt-0.5 size-3.5 shrink-0 self-center text-gray-500 transition-transform"
+              :class="announcedSectionExpanded && 'rotate-90'"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+            >
+              <path d="m9 6 6 6-6 6" />
+            </svg>
+            <div class="min-w-0">
+              <h4 class="text-sm font-semibold text-gray-300">Announced metadata</h4>
+              <p class="mt-0.5 text-xs text-gray-500">What <code class="font-mono">/v1/models</code> reports about this alias.</p>
+            </div>
+          </button>
+          <label class="flex shrink-0 cursor-pointer items-center gap-2">
+            <Switch :model-value="overrideEnabled" @update:model-value="v => setOverrideEnabled(v === true)" />
+            <span class="text-xs text-gray-400">Manual</span>
+          </label>
+        </div>
+
+        <div v-if="announcedSectionExpanded" id="announced-metadata-body" class="mt-4">
+          <p class="mb-3 text-xs text-gray-500">
+            Defaults to the intersection across every currently-available
+            target (rule-pinned sub-fields are not modifiable on client
+            side so treated as unsupported).
+          </p>
+          <ChatMetadataEditor
+            :model-value="announcedEditorValue"
+            :kind="kind"
+            :mode="overrideEnabled ? 'manual' : 'auto'"
+            @update:model-value="onAnnouncedChange"
+          />
+        </div>
+      </section>
+
+      <div v-if="aliasLevelWarnings.length > 0" class="rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm text-amber-300">
+        <ul class="list-disc space-y-1 pl-5">
+          <li v-for="w in aliasLevelWarnings" :key="w.type">
+            <template v-if="w.type === 'shadow'">
+              This alias name shadows a real model id:
+              <code class="font-mono">{{ w.shadowedId }}</code>
+              <template v-if="w.shadowedDisplayName !== null">
+                (<strong class="font-semibold">{{ w.shadowedDisplayName }}</strong>).
+              </template>
+              <template v-else>.</template>
+            </template>
+            <template v-else>{{ w.message }}</template>
+          </li>
+        </ul>
+      </div>
+
+      <div class="flex flex-wrap items-center justify-between gap-3 border-t border-white/[0.06] pt-5">
+        <label class="flex items-center gap-2">
+          <Switch v-model="visibleInModelsList" />
+          <span class="text-sm text-gray-300">Visible in <code class="font-mono">/v1/models</code></span>
+        </label>
+        <div class="flex items-center gap-2">
+          <Button variant="secondary" :disabled="saving" @click="open = false">Cancel</Button>
+          <Button :loading="saving" :disabled="!canSave" @click="save">Save</Button>
+        </div>
+      </div>
+    </div>
+  </Dialog>
+</template>
diff --git a/apps/web/src/components/alias-edit/AliasEditDialog_test.ts b/apps/web/src/components/alias-edit/AliasEditDialog_test.ts
new file mode 100644
index 000000000..7757d0475
--- /dev/null
+++ b/apps/web/src/components/alias-edit/AliasEditDialog_test.ts
@@ -0,0 +1,268 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { nextTick, ref } from 'vue';
+
+import { buildRealModel } from '../../api/test-fixtures.ts';
+import type { ControlPlaneModel, ModelAlias } from '../../api/types.ts';
+
+// Mock the API client + composables so the dialog mounts without hitting the
+// network. The composables expose `ref`-based state — return the same shape
+// so the dialog reads the catalog and the alias list directly off these
+// stubs.
+const aliasesRef = ref<ModelAlias[]>([]);
+const modelsRef = ref<ControlPlaneModel[]>([]);
+const postSpy = vi.fn(async (_arg: unknown) => new Response(JSON.stringify({}), { status: 201 }));
+const putSpy = vi.fn(async (_arg: unknown) => new Response(JSON.stringify({}), { status: 200 }));
+
+vi.mock('../../composables/useModelAliases.ts', () => ({
+  useModelAliases: () => ({ aliases: aliasesRef, loading: ref(false), error: ref<string | null>(null), load: async () => {} }),
+}));
+vi.mock('../../composables/useModels.ts', () => ({
+  useRawModelsStore: () => ({ models: modelsRef, loading: ref(false), error: ref<string | null>(null), load: async () => {} }),
+}));
+vi.mock('../../api/client.ts', () => ({
+  useApi: () => ({
+    api: {
+      aliases: {
+        $post: (arg: unknown) => postSpy(arg),
+        ':name': { $put: (arg: unknown) => putSpy(arg) },
+      },
+    },
+  }),
+  callApi: async <T>(fn: () => Promise<Response>) => {
+    const res = await fn();
+    if (!res.ok) return { error: { status: res.status, message: 'mock-error' } };
+    return { data: (await res.json()) as T };
+  },
+  authFetch: vi.fn(),
+}));
+
+// Import after mocks are registered.
+const { default: AliasEditDialog } = await import('./AliasEditDialog.vue');
+
+const realModel = (id: string, display?: string): ControlPlaneModel =>
+  buildRealModel(display !== undefined ? { id, display_name: display } : { id });
+
+const baseAlias = (over: Partial<ModelAlias> & { name: string }): ModelAlias => ({
+  kind: 'chat',
+  selection: 'first-available',
+  display_name: null,
+  visible_in_models_list: true,
+  targets: [{ target_model_id: 'gpt-5', rules: {} }],
+  announced_metadata: null,
+  sort_order: 0,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+  ...over,
+});
+
+// Reka-UI's DialogPortal teleports content out of the wrapper. Read the
+// portal-rooted DOM by scanning document.body directly.
+const portalText = () => document.body.textContent ?? '';
+const portalQuery = <T extends Element>(selector: string): T | null => document.body.querySelector<T>(selector);
+const portalQueryAll = <T extends Element>(selector: string): T[] => Array.from(document.body.querySelectorAll<T>(selector));
+
+beforeEach(() => {
+  aliasesRef.value = [];
+  modelsRef.value = [realModel('gpt-5', 'GPT 5'), realModel('claude')];
+  postSpy.mockClear();
+  putSpy.mockClear();
+});
+
+afterEach(() => {
+  // Reka-UI portals append to document.body; clear them between tests so
+  // subsequent assertions don't see stale content.
+  document.body.innerHTML = '';
+});
+
+describe('AliasEditDialog', () => {
+  it('starts create mode with one blank target row and seeds the form fields', async () => {
+    const w = mount(AliasEditDialog, { props: { open: true, record: null }, attachTo: document.body });
+    await nextTick();
+    expect(portalQueryAll('[aria-label="Toggle target row"]')).toHaveLength(1);
+    const inputs = portalQueryAll<HTMLInputElement>('input[type="text"]');
+    expect(inputs[0].value).toBe('');
+    w.unmount();
+  });
+
+  it('"Add target" appends a row', async () => {
+    const w = mount(AliasEditDialog, { props: { open: true, record: null }, attachTo: document.body });
+    await nextTick();
+    expect(portalQueryAll('[aria-label="Toggle target row"]')).toHaveLength(1);
+    const addBtn = portalQueryAll<HTMLButtonElement>('button').find(b => b.textContent?.trim() === 'Add target')!;
+    addBtn.click();
+    await nextTick();
+    expect(portalQueryAll('[aria-label="Toggle target row"]')).toHaveLength(2);
+    w.unmount();
+  });
+
+  it('expands the chat rule body for chat aliases; the row toggle is disabled for non-chat aliases', async () => {
+    const chat = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'a', targets: [{ target_model_id: 'gpt-5', rules: { reasoning: { effort: 'low' } } }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    portalQuery<HTMLButtonElement>('button[aria-label="Toggle target row"]')!.click();
+    await nextTick();
+    expect(portalText()).toContain('Reasoning effort');
+    chat.unmount();
+    document.body.innerHTML = '';
+
+    const embed = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'e', kind: 'embedding', targets: [{ target_model_id: 'embed-1', rules: {} as never }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    const toggle = portalQuery<HTMLButtonElement>('button[aria-label="Toggle target row"]')!;
+    expect(toggle.disabled).toBe(true);
+    expect(portalText()).not.toContain('Reasoning effort');
+    embed.unmount();
+  });
+
+  it('Save is disabled on empty name and on collision with another alias; enabled once the name is unique', async () => {
+    aliasesRef.value = [baseAlias({ name: 'existing' })];
+    // Seed the edit dialog with a valid target so the only validation knob
+    // under test is the alias name (the borderless combobox in the target
+    // row doesn't surface a plain HTMLInput we can drive from the test).
+    const w = mount(AliasEditDialog, {
+      props: {
+        open: true,
+        record: baseAlias({ name: '', targets: [{ target_model_id: 'gpt-5', rules: {} }] }),
+      },
+      attachTo: document.body,
+    });
+    await nextTick();
+
+    const saveBtn = portalQueryAll<HTMLButtonElement>('button').find(b => b.textContent?.trim() === 'Save')!;
+    expect(saveBtn.disabled).toBe(true);
+
+    const nameInput = portalQueryAll<HTMLInputElement>('input[type="text"]')[0];
+    nameInput.value = 'existing';
+    nameInput.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+    expect(saveBtn.disabled).toBe(true);
+
+    nameInput.value = 'fresh';
+    nameInput.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+    expect(saveBtn.disabled).toBe(false);
+
+    w.unmount();
+  });
+
+  it('renders the shadow warning card when the alias name collides with a real model and no target references it', async () => {
+    const w = mount(AliasEditDialog, { props: { open: true, record: null }, attachTo: document.body });
+    await nextTick();
+
+    const nameInput = portalQueryAll<HTMLInputElement>('input[type="text"]')[0];
+    nameInput.value = 'gpt-5';
+    nameInput.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+
+    expect(portalText()).toContain('shadows a real model id');
+    expect(document.body.innerHTML).toContain('<strong class="font-semibold">GPT 5</strong>');
+    w.unmount();
+  });
+
+  // ── Announced metadata section ────────────────────────────────────────
+
+  // The section header always renders for chat/embedding; the body only
+  // renders the editor when the "Manual" switch is on. Image
+  // aliases never see the section at all.
+
+  const expandAnnouncedSection = async () => {
+    const header = portalQueryAll<HTMLButtonElement>('button').find(b => (b.textContent ?? '').includes('Announced metadata'))!;
+    header.click();
+    await nextTick();
+  };
+
+  const announcedSwitch = (): HTMLButtonElement => {
+    // The override switch sits at the right end of the section header
+    // row. Reka-UI renders Switch as a <button role="switch">, so scan
+    // by role + the surrounding "Manual" label.
+    const label = Array.from(document.body.querySelectorAll<HTMLLabelElement>('label')).find(l => (l.textContent ?? '').includes('Manual'))!;
+    return label.querySelector<HTMLButtonElement>('button[role="switch"]')!;
+  };
+
+  // Locate the "Effort levels" toggle inside the ChatMetadataEditor by
+  // scanning labels in the portal-rooted DOM. Reka-UI renders Switch as
+  // a `<button role="switch">`, sitting next to its caption.
+  const effortSwitch = (): HTMLButtonElement | null => {
+    const label = Array.from(document.body.querySelectorAll<HTMLLabelElement>('label'))
+      .find(l => (l.textContent ?? '').trim().startsWith('Effort levels'));
+    return label?.querySelector<HTMLButtonElement>('button[role="switch"]') ?? null;
+  };
+
+  it('announced metadata: override off → editor renders in auto (read-only) mode', async () => {
+    const w = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'a', targets: [{ target_model_id: 'gpt-5', rules: {} }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    await expandAnnouncedSection();
+
+    // The override switch is present but off.
+    expect(announcedSwitch().getAttribute('aria-checked')).toBe('false');
+    // The shared editor mounts and renders the Reasoning toggles, but
+    // every Switch in there is disabled because mode='auto'.
+    const sw = effortSwitch();
+    expect(sw).not.toBeNull();
+    expect(sw!.disabled).toBe(true);
+    w.unmount();
+  });
+
+  it('announced metadata: toggling override on switches the editor into manual (enabled) mode and seeds it from the computed view', async () => {
+    modelsRef.value = [
+      buildRealModel({
+        id: 'gpt-5',
+        display_name: 'GPT 5',
+        chat: { reasoning: { effort: { supported: ['low', 'medium'], default: 'medium' } } },
+      }),
+    ];
+    const w = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'a', targets: [{ target_model_id: 'gpt-5', rules: {} }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    await expandAnnouncedSection();
+
+    announcedSwitch().click();
+    await nextTick();
+
+    // The editor now accepts input.
+    const sw = effortSwitch();
+    expect(sw).not.toBeNull();
+    expect(sw!.disabled).toBe(false);
+    // The frozen seed includes the computed `medium` default, so the
+    // editor's pinned-default tag for `medium` is part of the visible DOM.
+    expect(portalText()).toContain('medium');
+    w.unmount();
+  });
+
+  it('announced metadata: toggling override off restores auto (read-only) mode', async () => {
+    const w = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'a', targets: [{ target_model_id: 'gpt-5', rules: {} }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    await expandAnnouncedSection();
+
+    const sw = announcedSwitch();
+    sw.click(); await nextTick();
+    expect(effortSwitch()!.disabled).toBe(false);
+    sw.click(); await nextTick();
+    // Auto mode: effort switch disabled again.
+    expect(effortSwitch()!.disabled).toBe(true);
+    w.unmount();
+  });
+
+  it('announced metadata: image-kind aliases never see the section', async () => {
+    const w = mount(AliasEditDialog, {
+      props: { open: true, record: baseAlias({ name: 'img', kind: 'image', targets: [{ target_model_id: 'dalle', rules: {} as never }] }) },
+      attachTo: document.body,
+    });
+    await nextTick();
+    expect(portalText()).not.toContain('Announced metadata');
+    w.unmount();
+  });
+});
diff --git a/apps/web/src/components/alias-edit/AliasTargetRow.vue b/apps/web/src/components/alias-edit/AliasTargetRow.vue
new file mode 100644
index 000000000..3095ed0c5
--- /dev/null
+++ b/apps/web/src/components/alias-edit/AliasTargetRow.vue
@@ -0,0 +1,270 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+
+import { computeModelWarnings, computeRuleWarnings, findCatalogModel } from './warnings.ts';
+import type { AliasKind, AliasTarget, ChatAliasRules, ControlPlaneModel } from '../../api/types.ts';
+import { Combobox, Select, Tooltip } from '@floway-dev/ui';
+
+const target = defineModel<AliasTarget>({ required: true });
+
+const props = defineProps<{
+  kind: AliasKind;
+  targetIdItems: readonly string[];
+  models: readonly ControlPlaneModel[] | null;
+  isFirst: boolean;
+  isLast: boolean;
+  isSole: boolean;
+}>();
+
+const emit = defineEmits<{
+  moveUp: [];
+  moveDown: [];
+  remove: [];
+}>();
+
+const expanded = ref(false);
+const canExpand = computed(() => props.kind === 'chat');
+const toggleExpanded = () => { if (canExpand.value) expanded.value = !expanded.value; };
+
+// Switching the alias kind on the parent collapses every non-chat row's
+// body — there's no rule form to show, so an open chevron would be a
+// dead state.
+watch(() => props.kind, k => { if (k !== 'chat') expanded.value = false; });
+
+const targetId = computed({
+  get: () => target.value.target_model_id,
+  set: v => { target.value = { ...target.value, target_model_id: v }; },
+});
+
+// Setters always clone the rules object so the v-model emit fires and the
+// parent's targets array stays referentially up to date.
+const setRules = (next: ChatAliasRules) => { target.value = { ...target.value, rules: next }; };
+
+const patchReasoning = (patch: Partial<NonNullable<ChatAliasRules['reasoning']>>) => {
+  const current = target.value.rules.reasoning ?? {};
+  const next = { ...current, ...patch };
+  for (const k of Object.keys(patch) as (keyof typeof patch)[]) {
+    if (patch[k] === undefined) delete (next as Record<string, unknown>)[k];
+  }
+  if (Object.keys(next).length === 0) {
+    const { reasoning: _, ...rest } = target.value.rules;
+    setRules(rest);
+  } else {
+    setRules({ ...target.value.rules, reasoning: next });
+  }
+};
+
+const setEffort = (raw: string) => patchReasoning({ effort: raw === '' ? undefined : raw });
+const setSummary = (raw: string) => patchReasoning({ summary: raw === '' ? undefined : raw });
+
+// Three-state adaptive control: `undefined` means "defer to the model";
+// `true` forces reasoning on; `false` forces it off. A Switch can't
+// represent the third state, so editing an existing record that had
+// adaptive=false would silently round-trip to undefined.
+type AdaptiveSelect = 'auto' | 'on' | 'off';
+const ADAPTIVE_OPTIONS: { value: AdaptiveSelect; label: string }[] = [
+  { value: 'auto', label: 'Auto (defer to model)' },
+  { value: 'on', label: 'On (force adaptive)' },
+  { value: 'off', label: 'Off (force non-adaptive)' },
+];
+const adaptiveSelect = computed<AdaptiveSelect>(() => {
+  const v = target.value.rules.reasoning?.adaptive;
+  if (v === true) return 'on';
+  if (v === false) return 'off';
+  return 'auto';
+});
+const setAdaptive = (raw: AdaptiveSelect | undefined) => {
+  patchReasoning({ adaptive: raw === 'on' ? true : raw === 'off' ? false : undefined });
+};
+const setVerbosity = (raw: string) => {
+  const next = { ...target.value.rules };
+  if (raw === '') delete next.verbosity;
+  else next.verbosity = raw;
+  setRules(next);
+};
+const setServiceTier = (raw: string) => {
+  const next = { ...target.value.rules };
+  if (raw === '') delete next.serviceTier;
+  else next.serviceTier = raw;
+  setRules(next);
+};
+
+// String-bound view of the integer budget. Keeping the typed string in
+// state means an in-progress "" or "1024foo" doesn't clobber the
+// underlying numeric value mid-keystroke; the rules object only updates
+// when the parsed number is a finite integer. The watch syncs the input
+// back to the parent's value when the parent resets the rule object (e.g.
+// the dialog switches `kind` and re-initialises every target row's rules).
+const budgetText = ref(target.value.rules.reasoning?.budget_tokens === undefined ? '' : String(target.value.rules.reasoning.budget_tokens));
+watch(() => target.value.rules.reasoning?.budget_tokens, parsed => {
+  const next = parsed === undefined ? '' : String(parsed);
+  if (next !== budgetText.value.trim()) budgetText.value = next;
+});
+const onBudgetChange = (raw: string) => {
+  budgetText.value = raw;
+  const trimmed = raw.trim();
+  if (trimmed === '') {
+    patchReasoning({ budget_tokens: undefined });
+    return;
+  }
+  if (!/^\d+$/.test(trimmed)) return;
+  patchReasoning({ budget_tokens: Number(trimmed) });
+};
+
+// Canonical presets pinned as type-ahead hints in the chat-rule comboboxes.
+const EFFORT_ITEMS = ['none', 'low', 'medium', 'high', 'xhigh'];
+const SUMMARY_ITEMS = ['auto', 'concise', 'detailed', 'none'];
+const VERBOSITY_ITEMS = ['low', 'medium', 'high'];
+const SERVICE_TIER_ITEMS = ['default', 'flex', 'priority', 'scale', 'fast'];
+
+const catalog = computed(() => findCatalogModel(props.models, target.value.target_model_id));
+const modelWarnings = computed(() => computeModelWarnings(target.value.target_model_id, catalog.value, props.kind));
+const ruleWarnings = computed(() => computeRuleWarnings(target.value.rules, catalog.value));
+const warningFor = (field: string) => ruleWarnings.value.find(w => w.field === field)?.message;
+const modelWarningTooltip = computed(() => modelWarnings.value.join('\n'));
+</script>
+
+<template>
+  <div class="overflow-hidden rounded-lg border border-white/[0.06] bg-surface-800/40">
+    <header class="flex items-center gap-2 px-3 py-2">
+      <button
+        type="button"
+        class="grid size-6 shrink-0 place-items-center rounded text-gray-500 transition-colors hover:bg-white/5 hover:text-gray-200 disabled:cursor-not-allowed disabled:opacity-30 disabled:hover:bg-transparent disabled:hover:text-gray-500"
+        :aria-expanded="expanded"
+        :disabled="!canExpand"
+        aria-label="Toggle target row"
+        @click="toggleExpanded"
+      >
+        <svg
+          class="size-4 transition-transform"
+          :class="expanded && 'rotate-180'"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+        >
+          <path d="m6 9 6 6 6-6" />
+        </svg>
+      </button>
+
+      <div class="min-w-0 flex-1">
+        <Combobox
+          v-model="targetId"
+          :items="targetIdItems"
+          placeholder="target model id"
+          input-class="font-mono"
+          borderless
+          hide-dropdown-trigger
+        />
+      </div>
+
+      <div class="flex shrink-0 items-center gap-1">
+        <Tooltip v-if="modelWarnings.length > 0" :content="modelWarningTooltip">
+          <span class="inline-flex h-7 w-7 items-center justify-center rounded-md text-amber-400" aria-label="Model warning">
+            <i class="i-lucide-alert-triangle size-4" />
+          </span>
+        </Tooltip>
+        <button
+          type="button"
+          class="grid size-7 place-items-center rounded text-gray-500 transition-colors hover:bg-white/5 hover:text-gray-200 disabled:opacity-30 disabled:hover:bg-transparent disabled:hover:text-gray-500"
+          :disabled="isFirst"
+          aria-label="Move target up"
+          @click="emit('moveUp')"
+        >
+          <i class="i-lucide-arrow-up size-4" />
+        </button>
+        <button
+          type="button"
+          class="grid size-7 place-items-center rounded text-gray-500 transition-colors hover:bg-white/5 hover:text-gray-200 disabled:opacity-30 disabled:hover:bg-transparent disabled:hover:text-gray-500"
+          :disabled="isLast"
+          aria-label="Move target down"
+          @click="emit('moveDown')"
+        >
+          <i class="i-lucide-arrow-down size-4" />
+        </button>
+        <button
+          type="button"
+          class="grid size-7 place-items-center rounded text-gray-500 transition-colors hover:bg-white/5 hover:text-accent-rose disabled:opacity-30 disabled:hover:bg-transparent disabled:hover:text-gray-500"
+          :disabled="isSole"
+          aria-label="Remove target"
+          @click="emit('remove')"
+        >
+          <i class="i-lucide-x size-4" />
+        </button>
+      </div>
+    </header>
+
+    <div v-if="expanded" class="border-t border-white/[0.06] p-3">
+      <div v-if="kind === 'chat'" class="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Reasoning effort</label>
+          <Combobox
+            :model-value="target.rules.reasoning?.effort ?? ''"
+            :items="EFFORT_ITEMS"
+            placeholder="e.g. low"
+            @update:model-value="setEffort"
+          />
+          <p v-if="warningFor('reasoning.effort')" class="mt-1 text-xs text-amber-300">{{ warningFor('reasoning.effort') }}</p>
+        </div>
+
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Reasoning budget tokens</label>
+          <input
+            type="text"
+            inputmode="numeric"
+            placeholder="e.g. 4096"
+            class="h-9 w-full rounded-[10px] border border-white/[0.14] bg-surface-700 px-3 text-sm text-white placeholder:text-gray-600 focus:border-accent-cyan/50 focus:outline-none focus:ring-1 focus:ring-accent-cyan/30 font-mono"
+            :value="budgetText"
+            @input="(e: Event) => onBudgetChange((e.target as HTMLInputElement).value)"
+          >
+          <p v-if="warningFor('reasoning.budget_tokens')" class="mt-1 text-xs text-amber-300">{{ warningFor('reasoning.budget_tokens') }}</p>
+        </div>
+
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Adaptive reasoning</label>
+          <Select
+            :model-value="adaptiveSelect"
+            :options="ADAPTIVE_OPTIONS"
+            @update:model-value="setAdaptive"
+          />
+          <p v-if="warningFor('reasoning.adaptive')" class="mt-1 text-xs text-amber-300">{{ warningFor('reasoning.adaptive') }}</p>
+        </div>
+
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Reasoning summary</label>
+          <Combobox
+            :model-value="target.rules.reasoning?.summary ?? ''"
+            :items="SUMMARY_ITEMS"
+            placeholder="e.g. auto"
+            @update:model-value="setSummary"
+          />
+          <p v-if="warningFor('reasoning.summary')" class="mt-1 text-xs text-amber-300">{{ warningFor('reasoning.summary') }}</p>
+        </div>
+
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Verbosity</label>
+          <Combobox
+            :model-value="target.rules.verbosity ?? ''"
+            :items="VERBOSITY_ITEMS"
+            placeholder="e.g. medium"
+            @update:model-value="setVerbosity"
+          />
+          <p v-if="warningFor('verbosity')" class="mt-1 text-xs text-amber-300">{{ warningFor('verbosity') }}</p>
+        </div>
+
+        <div>
+          <label class="mb-1.5 block text-xs font-medium text-gray-500">Service tier</label>
+          <Combobox
+            :model-value="target.rules.serviceTier ?? ''"
+            :items="SERVICE_TIER_ITEMS"
+            placeholder="e.g. default"
+            @update:model-value="setServiceTier"
+          />
+          <p v-if="warningFor('serviceTier')" class="mt-1 text-xs text-amber-300">{{ warningFor('serviceTier') }}</p>
+        </div>
+      </div>
+
+      <p v-else class="text-xs text-gray-500">No per-target rules for this kind.</p>
+    </div>
+  </div>
+</template>
diff --git a/apps/web/src/components/alias-edit/AliasTargetRow_test.ts b/apps/web/src/components/alias-edit/AliasTargetRow_test.ts
new file mode 100644
index 000000000..c310c7127
--- /dev/null
+++ b/apps/web/src/components/alias-edit/AliasTargetRow_test.ts
@@ -0,0 +1,89 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { nextTick } from 'vue';
+
+import AliasTargetRow from './AliasTargetRow.vue';
+import { buildRealModel } from '../../api/test-fixtures.ts';
+import type { AliasTarget, ControlPlaneModel } from '../../api/types.ts';
+
+const target = (over: Partial<AliasTarget> = {}): AliasTarget => ({
+  target_model_id: 'gpt-5',
+  rules: {},
+  ...over,
+});
+
+const realModel = (id: string, chat?: ControlPlaneModel['chat']): ControlPlaneModel =>
+  buildRealModel(chat ? { id, chat } : { id });
+
+const mountRow = (props: Partial<InstanceType<typeof AliasTargetRow>['$props']>) => mount(AliasTargetRow, {
+  props: {
+    modelValue: target(),
+    kind: 'chat',
+    targetIdItems: ['gpt-5', 'claude-sonnet'],
+    models: [realModel('gpt-5')],
+    isFirst: false,
+    isLast: false,
+    isSole: false,
+    ...props,
+  },
+});
+
+describe('AliasTargetRow', () => {
+  it('disables Move Up on the first row, Move Down on the last, and Remove when it is the sole row', () => {
+    const first = mountRow({ isFirst: true });
+    expect((first.find('button[aria-label="Move target up"]').element as HTMLButtonElement).disabled).toBe(true);
+    expect((first.find('button[aria-label="Move target down"]').element as HTMLButtonElement).disabled).toBe(false);
+
+    const last = mountRow({ isLast: true });
+    expect((last.find('button[aria-label="Move target up"]').element as HTMLButtonElement).disabled).toBe(false);
+    expect((last.find('button[aria-label="Move target down"]').element as HTMLButtonElement).disabled).toBe(true);
+
+    const sole = mountRow({ isSole: true });
+    expect((sole.find('button[aria-label="Remove target"]').element as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it('emits move-up / move-down / remove', async () => {
+    const w = mountRow({});
+    await w.find('button[aria-label="Move target up"]').trigger('click');
+    await w.find('button[aria-label="Move target down"]').trigger('click');
+    await w.find('button[aria-label="Remove target"]').trigger('click');
+    expect(w.emitted('moveUp')).toHaveLength(1);
+    expect(w.emitted('moveDown')).toHaveLength(1);
+    expect(w.emitted('remove')).toHaveLength(1);
+  });
+
+  it('expands to the chat rule body when the kind is chat; the toggle is disabled for non-chat kinds', async () => {
+    const chatRow = mountRow({});
+    expect(chatRow.text()).not.toContain('Reasoning effort');
+    await chatRow.find('button[aria-label="Toggle target row"]').trigger('click');
+    expect(chatRow.text()).toContain('Reasoning effort');
+    expect(chatRow.text()).toContain('Verbosity');
+
+    // Non-chat aliases carry an empty rules record, so the row has nothing
+    // to expand — the toggle is disabled and the body never renders.
+    const embedRow = mountRow({ kind: 'embedding', modelValue: { target_model_id: 'e1', rules: {} } });
+    const toggle = embedRow.find('button[aria-label="Toggle target row"]').element as HTMLButtonElement;
+    expect(toggle.disabled).toBe(true);
+    expect(embedRow.text()).not.toContain('Reasoning effort');
+  });
+
+  it('shows the model-level warning icon when the target id does not resolve to any catalog entry', () => {
+    const known = mountRow({ modelValue: target({ target_model_id: 'gpt-5' }), models: [realModel('gpt-5')] });
+    expect(known.find('span[aria-label="Model warning"]').exists()).toBe(false);
+
+    const unknown = mountRow({ modelValue: target({ target_model_id: 'mystery' }), models: [realModel('gpt-5')] });
+    expect(unknown.find('span[aria-label="Model warning"]').exists()).toBe(true);
+  });
+
+  it('renders a rule-level warning under reasoning.effort when the target does not advertise it', async () => {
+    const w = mountRow({
+      modelValue: { target_model_id: 'gpt-5', rules: { reasoning: { effort: 'xhigh' } } },
+      models: [realModel('gpt-5', { reasoning: { effort: { supported: ['low', 'medium'], default: 'medium' } } })],
+    });
+    await w.find('button[aria-label="Toggle target row"]').trigger('click');
+    await nextTick();
+    const html = w.html();
+    expect(html).toContain('text-amber-300');
+    expect(html).toContain('low, medium');
+  });
+});
diff --git a/apps/web/src/components/alias-edit/announced-metadata.ts b/apps/web/src/components/alias-edit/announced-metadata.ts
new file mode 100644
index 000000000..953314ae1
--- /dev/null
+++ b/apps/web/src/components/alias-edit/announced-metadata.ts
@@ -0,0 +1,144 @@
+// Frontend mirror of the backend `synthesizeOne`'s rule-aware
+// intersection. The dashboard renders the read-only view of an
+// alias's announced metadata when no operator override is set; the
+// edit dialog also seeds the editor with this exact payload when
+// the operator flips the override switch on, so the editor starts
+// from the same baseline the wire surface would have published.
+//
+// Mirrors packages/gateway/src/data-plane/models/alias-listing.ts.
+// Keeping a local copy avoids a server round-trip per dialog open,
+// at the cost of a duplicated computation that we keep in sync by
+// hand. The backend stays authoritative — what `/v1/models` reports
+// is what the gateway computes there, not what this helper emits.
+
+import type { AliasTarget, AnnouncedMetadata, ChatAliasRules, ChatModelInfo, ControlPlaneModel, PublicModelLimits } from '../../api/types.ts';
+
+const chatRules = (target: AliasTarget): ChatAliasRules => target.rules;
+
+const intersectArrays = <T>(arrays: readonly (readonly T[])[]): T[] => {
+  if (arrays.length === 0) return [];
+  const [head, ...tail] = arrays;
+  return head.filter(value => tail.every(other => other.includes(value)));
+};
+
+// Apply the rule-driven downgrade: a target with a pinned rule
+// reports the corresponding catalog sub-field as unsupported for
+// the purposes of intersection.
+const effectiveChatForIntersection = (chat: ChatModelInfo | undefined, target: AliasTarget): ChatModelInfo | undefined => {
+  if (chat === undefined) return undefined;
+  const rules = chatRules(target);
+  const ruleReasoning = rules.reasoning;
+  if (ruleReasoning === undefined) return chat;
+  if (chat.reasoning === undefined) return chat;
+
+  const reasoning: NonNullable<ChatModelInfo['reasoning']> = { ...chat.reasoning };
+  if (ruleReasoning.effort !== undefined) delete reasoning.effort;
+  if (ruleReasoning.budget_tokens !== undefined) delete reasoning.budget_tokens;
+  if (ruleReasoning.adaptive === true) delete reasoning.adaptive;
+
+  return { ...chat, reasoning };
+};
+
+const intersectChat = (chats: readonly ChatModelInfo[]): ChatModelInfo | undefined => {
+  const result: ChatModelInfo = {};
+
+  const modalityChats = chats.filter(c => c.modalities !== undefined);
+  if (modalityChats.length === chats.length) {
+    const input = intersectArrays(modalityChats.map(c => c.modalities!.input));
+    const output = intersectArrays(modalityChats.map(c => c.modalities!.output));
+    // Both halves must survive — `{ input: ['text'], output: [] }`
+    // would advertise a chat model that consumes input but produces
+    // nothing. Mirrors the gateway-side rule.
+    if (input.length > 0 && output.length > 0) result.modalities = { input, output };
+  }
+
+  const reasoningChats = chats.filter(c => c.reasoning !== undefined);
+  if (reasoningChats.length === chats.length) {
+    const reasoning: NonNullable<ChatModelInfo['reasoning']> = {};
+
+    const effortChats = reasoningChats.filter(c => c.reasoning!.effort !== undefined);
+    if (effortChats.length === reasoningChats.length) {
+      const supported = intersectArrays(effortChats.map(c => c.reasoning!.effort!.supported));
+      const defaults = new Set(effortChats.map(c => c.reasoning!.effort!.default));
+      if (supported.length > 0) {
+        const agreedDefault = defaults.size === 1 ? [...defaults][0] : undefined;
+        reasoning.effort = agreedDefault !== undefined && supported.includes(agreedDefault)
+          ? { supported, default: agreedDefault }
+          : { supported, default: supported[0]! };
+      }
+    }
+
+    const budgetChats = reasoningChats.filter(c => c.reasoning!.budget_tokens !== undefined);
+    if (budgetChats.length === reasoningChats.length) {
+      const mins = budgetChats.map(c => c.reasoning!.budget_tokens!.min).filter((v): v is number => v !== undefined);
+      const maxes = budgetChats.map(c => c.reasoning!.budget_tokens!.max).filter((v): v is number => v !== undefined);
+      // Both min and max must be all-declared — a half-declared block
+      // would claim a capability some target does not report. Mirrors the
+      // gateway-side rule.
+      if (mins.length === budgetChats.length && maxes.length === budgetChats.length) {
+        const min = Math.max(...mins);
+        const max = Math.min(...maxes);
+        if (min <= max) reasoning.budget_tokens = { min, max };
+      }
+    }
+
+    const adaptiveAgreed = new Set(reasoningChats.map(c => c.reasoning!.adaptive));
+    if (adaptiveAgreed.size === 1) {
+      const value = [...adaptiveAgreed][0];
+      if (value !== undefined) reasoning.adaptive = value;
+    }
+    const mandatoryAgreed = new Set(reasoningChats.map(c => c.reasoning!.mandatory));
+    if (mandatoryAgreed.size === 1) {
+      const value = [...mandatoryAgreed][0];
+      if (value !== undefined) reasoning.mandatory = value;
+    }
+
+    if (Object.keys(reasoning).length > 0) result.reasoning = reasoning;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+const LIMIT_KEYS = ['max_context_window_tokens', 'max_prompt_tokens', 'max_output_tokens'] as const;
+
+const intersectLimits = (limitsList: readonly PublicModelLimits[]): PublicModelLimits => {
+  if (limitsList.length === 0) return {};
+  const result: PublicModelLimits = {};
+  for (const key of LIMIT_KEYS) {
+    const values = limitsList.map(l => l[key]).filter((v): v is number => v !== undefined);
+    if (values.length === limitsList.length) result[key] = Math.min(...values);
+  }
+  return result;
+};
+
+// Returns the rule-aware intersection across the targets that the live
+// catalog currently serves under the alias's kind. The returned shape
+// matches AnnouncedMetadata; an empty payload (no targets matched)
+// returns `{}` so callers can still render a skeleton.
+export const computeAnnouncedMetadata = (
+  targets: readonly AliasTarget[],
+  kind: 'chat' | 'embedding' | 'image',
+  models: readonly ControlPlaneModel[] | null | undefined,
+): AnnouncedMetadata => {
+  const realById = new Map((models ?? []).filter(m => m.aliasedFrom === undefined).map(m => [m.id, m] as const));
+  const available = targets
+    .map(target => ({ target, real: realById.get(target.target_model_id) }))
+    .filter((entry): entry is { target: AliasTarget; real: ControlPlaneModel } => entry.real?.kind === kind);
+
+  if (available.length === 0) return {};
+
+  const limitsList = available.map(({ real }) => real.limits);
+  const limits = intersectLimits(limitsList);
+
+  const effectiveChats = available
+    .map(({ target, real }) => effectiveChatForIntersection(real.chat, target))
+    .filter((c): c is ChatModelInfo => c !== undefined);
+  const chat = effectiveChats.length === available.length
+    ? intersectChat(effectiveChats)
+    : undefined;
+
+  const out: AnnouncedMetadata = {};
+  if (Object.keys(limits).length > 0) out.limits = limits;
+  if (chat !== undefined) out.chat = chat;
+  return out;
+};
diff --git a/apps/web/src/components/alias-edit/announced-metadata_test.ts b/apps/web/src/components/alias-edit/announced-metadata_test.ts
new file mode 100644
index 000000000..1fa3c7cf3
--- /dev/null
+++ b/apps/web/src/components/alias-edit/announced-metadata_test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+
+import { computeAnnouncedMetadata } from './announced-metadata.ts';
+import { buildRealModel } from '../../api/test-fixtures.ts';
+import type { AliasTarget, ChatAliasRules, ControlPlaneModel } from '../../api/types.ts';
+
+// Mirror of `packages/gateway/src/data-plane/models/alias-listing_test.ts`'s
+// matrix on the frontend's hand-written `intersectChat` / `intersectLimits`.
+// The two have already drifted once (the ||→&& fix landed gateway-side first),
+// so every invariant the gateway test pins lands here too.
+
+const target = (id: string, rules: ChatAliasRules = {}): AliasTarget => ({ target_model_id: id, rules });
+
+const real = (id: string, over: Partial<ControlPlaneModel> = {}): ControlPlaneModel =>
+  buildRealModel({ id, ...over });
+
+describe('computeAnnouncedMetadata', () => {
+  it('returns {} when no target resolves against the live catalog', () => {
+    const result = computeAnnouncedMetadata([target('gone')], 'chat', [real('other')]);
+    expect(result).toEqual({});
+  });
+
+  it('intersects modalities across all available targets', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { chat: { modalities: { input: ['text', 'image'], output: ['text'] } } }),
+        real('b', { chat: { modalities: { input: ['text'], output: ['text'] } } }),
+      ],
+    );
+    expect(result.chat?.modalities).toEqual({ input: ['text'], output: ['text'] });
+  });
+
+  it('omits the modalities block when either half of the intersection collapses', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { chat: { modalities: { input: ['text'], output: ['text'] } } }),
+        real('b', { chat: { modalities: { input: ['text'], output: ['image'] } } }),
+      ],
+    );
+    expect(result.chat?.modalities).toBeUndefined();
+  });
+
+  it('intersects effort supported across targets', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { chat: { reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } } } }),
+        real('b', { chat: { reasoning: { effort: { supported: ['low', 'medium'], default: 'low' } } } }),
+      ],
+    );
+    expect(result.chat?.reasoning?.effort?.supported).toEqual(['low', 'medium']);
+  });
+
+  it('drops the budget_tokens block when one target declares only min and another only max', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { chat: { reasoning: { budget_tokens: { min: 1024 } } } }),
+        real('b', { chat: { reasoning: { budget_tokens: { max: 65536 } } } }),
+      ],
+    );
+    expect(result.chat?.reasoning?.budget_tokens).toBeUndefined();
+  });
+
+  it('takes min across max_context_window_tokens / max_output_tokens / max_prompt_tokens', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { limits: { max_context_window_tokens: 200000, max_output_tokens: 8192 } }),
+        real('b', { limits: { max_context_window_tokens: 128000, max_output_tokens: 4096 } }),
+      ],
+    );
+    expect(result.limits).toEqual({ max_context_window_tokens: 128000, max_output_tokens: 4096 });
+  });
+
+  it('omits a limits leaf when any target leaves it undeclared', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a'), target('b')],
+      'chat',
+      [
+        real('a', { limits: { max_context_window_tokens: 200000 } }),
+        real('b', { limits: {} }),
+      ],
+    );
+    expect(result.limits?.max_context_window_tokens).toBeUndefined();
+  });
+
+  it('drops a sub-field downgraded by a pinned rule (effort: alias fixes the value, so it is not advertised)', () => {
+    const result = computeAnnouncedMetadata(
+      [target('a', { reasoning: { effort: 'low' } })],
+      'chat',
+      [real('a', { chat: { reasoning: { effort: { supported: ['low', 'medium'], default: 'medium' } } } })],
+    );
+    expect(result.chat?.reasoning).toBeUndefined();
+  });
+});
diff --git a/apps/web/src/components/alias-edit/warnings.ts b/apps/web/src/components/alias-edit/warnings.ts
new file mode 100644
index 000000000..e2de491ae
--- /dev/null
+++ b/apps/web/src/components/alias-edit/warnings.ts
@@ -0,0 +1,195 @@
+// Shared catalog lookups + warning computation for the alias dashboard
+// surfaces (Settings row, edit dialog, target row). Centralising these
+// helpers keeps the Settings card and the dialog reading the same view of
+// the live /api/models catalog.
+
+import type { AliasKind, ChatAliasRules, ControlPlaneModel } from '../../api/types.ts';
+
+// Excludes alias rows — target ids never re-enter the alias layer, so the
+// rule-warning lookup runs against the real-model surface only.
+export const findCatalogModel = (
+  models: readonly ControlPlaneModel[] | null | undefined,
+  targetModelId: string,
+): ControlPlaneModel | undefined =>
+  (models ?? []).find(m => m.id === targetModelId && m.aliasedFrom === undefined);
+
+// Real (non-alias) model ids whose kind matches the alias's kind. Used by
+// the target-id combobox suggestion list so an embedding alias only
+// suggests embedding models, etc. Operators can still type any string —
+// the suggestion list is a hint, not a constraint.
+export const realModelIdsOfKind = (
+  models: readonly ControlPlaneModel[] | null | undefined,
+  kind: AliasKind,
+): string[] =>
+  (models ?? []).filter(m => m.aliasedFrom === undefined && m.kind === kind).map(m => m.id);
+
+// One warning attached to a specific chat rule field.
+export interface AliasRuleWarning {
+  field: 'reasoning.effort' | 'reasoning.budget_tokens' | 'reasoning.adaptive' | 'reasoning.summary' | 'verbosity' | 'serviceTier';
+  message: string;
+}
+
+// Rule-level warnings: a configured rule field whose target's chat
+// capability metadata does not advertise the feature. The gateway still
+// forwards the value verbatim; the warning just tells the operator the
+// upstream may ignore it.
+export const computeRuleWarnings = (
+  rules: ChatAliasRules,
+  catalog: ControlPlaneModel | undefined,
+): AliasRuleWarning[] => {
+  const out: AliasRuleWarning[] = [];
+  const chat = catalog?.chat;
+  const reasoning = chat?.reasoning;
+
+  if (rules.reasoning?.effort !== undefined) {
+    const supported = reasoning?.effort?.supported;
+    if (supported === undefined) {
+      out.push({ field: 'reasoning.effort', message: 'Target does not advertise reasoning effort.' });
+    } else if (!supported.includes(rules.reasoning.effort)) {
+      out.push({ field: 'reasoning.effort', message: `Target advertises effort levels: ${supported.join(', ')}.` });
+    }
+  }
+
+  if (rules.reasoning?.budget_tokens !== undefined) {
+    const range = reasoning?.budget_tokens;
+    if (range === undefined) {
+      out.push({ field: 'reasoning.budget_tokens', message: 'Target does not advertise a reasoning budget.' });
+    } else {
+      const n = rules.reasoning.budget_tokens;
+      if (range.min !== undefined && n < range.min) out.push({ field: 'reasoning.budget_tokens', message: `Below target minimum (${range.min}).` });
+      if (range.max !== undefined && n > range.max) out.push({ field: 'reasoning.budget_tokens', message: `Above target maximum (${range.max}).` });
+    }
+  }
+
+  if (rules.reasoning?.adaptive === true && reasoning?.adaptive !== true) {
+    out.push({ field: 'reasoning.adaptive', message: 'Target does not advertise adaptive reasoning.' });
+  }
+
+  // Summary, verbosity, and serviceTier carry no catalog metadata; their
+  // values forward verbatim and never warn here.
+
+  return out;
+};
+
+// Model-level warnings for one target row. Returned as plain strings —
+// the dialog already joins them with newlines for the tooltip.
+//
+// Two triggers:
+// - Unknown target id: nothing in the catalog matches.
+// - Wrong-kind target: the catalog row exists but its `kind` doesn't
+//   match the alias's kind, so a /<aliasKind> request that resolves to
+//   this target would fall through prefix routing's endpoint check.
+export const computeModelWarnings = (
+  targetModelId: string,
+  catalog: ControlPlaneModel | undefined,
+  aliasKind: AliasKind,
+): string[] => {
+  if (targetModelId === '') return [];
+  if (catalog === undefined) {
+    return [`"${targetModelId}" does not currently resolve to any enabled upstream binding.`];
+  }
+  if (catalog.kind !== aliasKind) {
+    return [`"${targetModelId}" is a ${catalog.kind} model; this alias is configured for ${aliasKind}.`];
+  }
+  return [];
+};
+
+// Alias-level warnings: conditions that apply to the alias as a whole
+// rather than to one rule field or one target row. Each entry carries a
+// short tooltip-friendly message plus a discriminator tag the host
+// surface (Settings card, edit dialog) can branch on for icon / copy
+// choice.
+//
+// Today there are two triggers:
+//
+// - `shadow` — the alias name exactly matches a listed real-model id AND
+//   no entry in `targets[].target_model_id` references that id. The
+//   suppression rule keeps the seed pattern (alias names itself as its
+//   own first target) quiet. Addressable-but-not-listed variant ids do
+//   not trigger this — the listing surface is the relevant collision
+//   space.
+// - `no-target` — every configured target falls outside the addressable
+//   surface, so the resolver would 404 on the alias name. The listing
+//   already hides the alias from `/v1/models` in this state; the warning
+//   tells the operator why the alias is invisible.
+export interface AliasShadowWarning {
+  type: 'shadow';
+  shadowedId: string;
+  shadowedDisplayName: string | null;
+  message: string;
+}
+
+export interface AliasNoTargetWarning {
+  type: 'no-target';
+  message: string;
+}
+
+export type AliasLevelWarning = AliasShadowWarning | AliasNoTargetWarning;
+
+const computeShadowWarning = (
+  aliasName: string,
+  targets: readonly { target_model_id: string }[],
+  models: readonly ControlPlaneModel[] | null | undefined,
+): AliasShadowWarning | null => {
+  if (aliasName === '') return null;
+  // Shadowing is scored against the listed surface only — an alias named
+  // after an addressable-but-not-listed variant id is a deliberate
+  // power-user pattern, not a collision worth warning on.
+  const shadowed = (models ?? []).find(m => m.id === aliasName && m.aliasedFrom === undefined && m.unlisted !== true);
+  if (!shadowed) return null;
+  if (targets.some(t => t.target_model_id === aliasName)) return null;
+  const displayName = shadowed.display_name ?? null;
+  const shadowedDisplayName = displayName !== null && displayName !== shadowed.id ? displayName : null;
+  const label = shadowedDisplayName !== null ? `${shadowed.id} (${shadowedDisplayName})` : shadowed.id;
+  return {
+    type: 'shadow',
+    shadowedId: shadowed.id,
+    shadowedDisplayName,
+    message: `Alias name shadows a real model id: ${label}`,
+  };
+};
+
+const computeNoTargetWarning = (
+  alias: AliasView,
+  models: readonly ControlPlaneModel[] | null | undefined,
+): AliasNoTargetWarning | null => {
+  // `useRawModelsStore` fetches with `aliases=false&include_unlisted=true`;
+  // the server returns the gateway-wide surface to admin sessions, so this
+  // `models` array represents every id the data-plane resolver would accept
+  // on the entire gateway — not the admin's per-account view. Loading
+  // state — models is null — should not fire the warning, or the dashboard
+  // flashes a yellow icon on every alias during startup.
+  if (models === null || models === undefined) return null;
+  const addressableIds = new Set(models.filter(m => m.aliasedFrom === undefined).map(m => m.id));
+  const reachable = alias.targets.some(t => addressableIds.has(t.target_model_id));
+  if (reachable) return null;
+  return {
+    type: 'no-target',
+    message: 'No target resolves to any model on this gateway.',
+  };
+};
+
+// Structural view a warning consumer hands in: the persisted
+// `ModelAlias` record from the Settings card and the live editor state in
+// `AliasEditDialog` both project to this shape, so one helper drives both
+// surfaces.
+export interface AliasView {
+  readonly name: string;
+  readonly targets: readonly { target_model_id: string }[];
+}
+
+// Aggregate every alias-level warning that fires for this alias. Returns
+// an empty list when the alias is clean; callers (Settings card row,
+// edit dialog bottom card) render the icon + tooltip directly off the
+// resulting array.
+export const computeAliasLevelWarnings = (
+  alias: AliasView,
+  models: readonly ControlPlaneModel[] | null | undefined,
+): AliasLevelWarning[] => {
+  const out: AliasLevelWarning[] = [];
+  const shadow = computeShadowWarning(alias.name, alias.targets, models);
+  if (shadow !== null) out.push(shadow);
+  const noTarget = computeNoTargetWarning(alias, models);
+  if (noTarget !== null) out.push(noTarget);
+  return out;
+};
diff --git a/apps/web/src/components/alias-edit/warnings_test.ts b/apps/web/src/components/alias-edit/warnings_test.ts
new file mode 100644
index 000000000..9cfd90072
--- /dev/null
+++ b/apps/web/src/components/alias-edit/warnings_test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+
+import { computeAliasLevelWarnings, computeModelWarnings, computeRuleWarnings, findCatalogModel, type AliasView } from './warnings.ts';
+import { buildAliasModel as aliasModel, buildRealModel as realModel, buildUnlistedModel as unlistedModel } from '../../api/test-fixtures.ts';
+import type { ControlPlaneModel } from '../../api/types.ts';
+
+const view = (name: string, ids: readonly string[]): AliasView => ({
+  name,
+  targets: ids.map(id => ({ target_model_id: id })),
+});
+
+describe('findCatalogModel', () => {
+  it('looks up the catalog row by id', () => {
+    const catalog: ControlPlaneModel[] = [realModel({ id: 'gpt-5' }), realModel({ id: 'claude' })];
+    expect(findCatalogModel(catalog, 'claude')?.id).toBe('claude');
+    expect(findCatalogModel(catalog, 'unknown')).toBeUndefined();
+  });
+
+  it('skips alias rows that share an id with a target — they never re-enter the alias layer at runtime', () => {
+    // Both rows share id 'auto-review' (the alias name shadowing nothing
+    // real). findCatalogModel must not return the alias entry — its
+    // capability metadata is the wrong source for a real-model rule
+    // warning. computeModelWarnings should treat the id as unknown
+    // instead.
+    const catalog: ControlPlaneModel[] = [aliasModel({ id: 'auto-review' })];
+    expect(findCatalogModel(catalog, 'auto-review')).toBeUndefined();
+  });
+});
+
+describe('computeModelWarnings', () => {
+  it('returns no warning when the target resolves to a same-kind catalog entry', () => {
+    const catalog = realModel({ id: 'gpt-5', kind: 'chat' });
+    expect(computeModelWarnings('gpt-5', catalog, 'chat')).toEqual([]);
+  });
+
+  it('returns a "does not resolve" warning when the target is unknown', () => {
+    const w = computeModelWarnings('mystery-model', undefined, 'chat');
+    expect(w).toHaveLength(1);
+    expect(w[0]).toContain('mystery-model');
+    expect(w[0]).toContain('does not currently resolve');
+  });
+
+  it('returns a kind-mismatch warning when the catalog row is the wrong kind', () => {
+    const w = computeModelWarnings('text-emb-3', realModel({ id: 'text-emb-3', kind: 'embedding' }), 'chat');
+    expect(w).toHaveLength(1);
+    expect(w[0]).toContain('text-emb-3');
+    expect(w[0]).toContain('embedding');
+    expect(w[0]).toContain('chat');
+  });
+
+  it('emits no warning for an empty id (the row is mid-edit)', () => {
+    expect(computeModelWarnings('', undefined, 'chat')).toEqual([]);
+  });
+});
+
+describe('computeRuleWarnings', () => {
+  const catalogWithReasoning = realModel({
+    id: 'gpt-5',
+    chat: {
+      reasoning: {
+        effort: { supported: ['low', 'medium'], default: 'medium' },
+        budget_tokens: { min: 100, max: 1000 },
+      },
+    },
+  });
+
+  it('flags effort values not in the advertised supported list', () => {
+    const w = computeRuleWarnings({ reasoning: { effort: 'xhigh' } }, catalogWithReasoning);
+    expect(w).toHaveLength(1);
+    expect(w[0].field).toBe('reasoning.effort');
+    expect(w[0].message).toContain('low, medium');
+  });
+
+  it('does not flag effort values that are advertised', () => {
+    const w = computeRuleWarnings({ reasoning: { effort: 'low' } }, catalogWithReasoning);
+    expect(w).toEqual([]);
+  });
+
+  it('flags budgets outside the advertised range', () => {
+    const tooHigh = computeRuleWarnings({ reasoning: { budget_tokens: 5000 } }, catalogWithReasoning);
+    expect(tooHigh[0].field).toBe('reasoning.budget_tokens');
+    expect(tooHigh[0].message).toContain('1000');
+    const tooLow = computeRuleWarnings({ reasoning: { budget_tokens: 10 } }, catalogWithReasoning);
+    expect(tooLow[0].field).toBe('reasoning.budget_tokens');
+    expect(tooLow[0].message).toContain('100');
+  });
+
+  it('flags adaptive=true when the target does not advertise adaptive', () => {
+    const w = computeRuleWarnings({ reasoning: { adaptive: true } }, catalogWithReasoning);
+    expect(w).toHaveLength(1);
+    expect(w[0].field).toBe('reasoning.adaptive');
+  });
+
+  it('flags reasoning at all when the target lacks reasoning metadata', () => {
+    const noReasoning = realModel({ id: 'gpt-5', chat: {} });
+    const w = computeRuleWarnings({ reasoning: { effort: 'low' } }, noReasoning);
+    expect(w[0].field).toBe('reasoning.effort');
+    expect(w[0].message).toContain('does not advertise');
+  });
+});
+
+describe('computeAliasLevelWarnings', () => {
+  const catalog: ControlPlaneModel[] = [
+    realModel({ id: 'gpt-5', display_name: 'GPT 5' }),
+    realModel({ id: 'plain' }),
+    aliasModel({ id: 'auto-review' }),
+  ];
+
+  it('returns no warnings when the alias name is fresh and every target resolves', () => {
+    expect(computeAliasLevelWarnings(view('fresh', ['gpt-5']), catalog)).toEqual([]);
+  });
+
+  it('emits a shadow warning when the alias name collides with a listed real id and no target references it', () => {
+    const warnings = computeAliasLevelWarnings(view('gpt-5', ['plain']), catalog);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toEqual(expect.objectContaining({
+      type: 'shadow',
+      shadowedId: 'gpt-5',
+      shadowedDisplayName: 'GPT 5',
+    }));
+  });
+
+  it('suppresses the shadow warning when one of the targets references the shadowed id (seed pattern)', () => {
+    expect(computeAliasLevelWarnings(view('gpt-5', ['gpt-5', 'plain']), catalog))
+      .toEqual([]);
+  });
+
+  it('ignores collisions with addressable-but-not-listed variant ids (preserves today\'s scope)', () => {
+    const withUnlisted: ControlPlaneModel[] = [
+      ...catalog,
+      unlistedModel({ id: 'claude-opus-4.7-high' }),
+    ];
+    expect(computeAliasLevelWarnings(view('claude-opus-4.7-high', ['gpt-5']), withUnlisted))
+      .toEqual([]);
+  });
+
+  it('emits a no-target warning when every configured target falls outside the addressable surface', () => {
+    const warnings = computeAliasLevelWarnings(view('lonely', ['missing-a', 'missing-b']), catalog);
+    expect(warnings).toEqual([{
+      type: 'no-target',
+      message: 'No target resolves to any model on this gateway.',
+    }]);
+  });
+
+  it('counts addressable-but-not-listed entries as available for the no-target check', () => {
+    const withUnlisted: ControlPlaneModel[] = [
+      ...catalog,
+      unlistedModel({ id: 'claude-opus-4.7-high' }),
+    ];
+    expect(computeAliasLevelWarnings(view('fast-claude', ['claude-opus-4.7-high']), withUnlisted))
+      .toEqual([]);
+  });
+
+  it('returns both warnings when an alias both shadows a listed id and has no reachable target', () => {
+    // Real catalog deliberately drops the shadowed id so the no-target
+    // branch also fires. (`gpt-5` shadowed, target `gpt-5` does not exist
+    // here.)
+    const warnings = computeAliasLevelWarnings(view('gpt-5', ['gone']), [realModel({ id: 'gpt-5' })]);
+    expect(warnings.map(w => w.type).sort()).toEqual(['no-target', 'shadow']);
+  });
+
+  it('skips the no-target warning while the catalog is loading (models is null)', () => {
+    expect(computeAliasLevelWarnings(view('lonely', ['missing']), null)).toEqual([]);
+  });
+});
diff --git a/apps/web/src/components/models/ModelInfoBar.vue b/apps/web/src/components/models/ModelInfoBar.vue
index f8bf98b6e..4b10c0aca 100644
--- a/apps/web/src/components/models/ModelInfoBar.vue
+++ b/apps/web/src/components/models/ModelInfoBar.vue
@@ -1,9 +1,23 @@
 <script setup lang="ts">
+import { computed } from 'vue';
+
 import type { ControlPlaneModel } from '../../api/types.ts';
+import { reachableTargets } from '../../utils/reachability.ts';
 import { providerBadgeClass, providerMeta } from '../upstreams/provider-meta.ts';
+import { type AliasRuleBadgeField, formatAliasRuleBadges } from '@floway-dev/protocols/common';
 
-defineProps<{
+const props = defineProps<{
   model: ControlPlaneModel;
+  // Full catalog the row came from; needed so alias rows can show how
+  // many of their configured targets are actually reachable under the
+  // caller's current cap. Optional because callers outside the
+  // playground may not have a meaningful catalog (e.g. the Models
+  // page's tile renders the row in isolation).
+  catalog?: readonly ControlPlaneModel[];
+  // Effective upstream cap of the playground's current api key choice;
+  // `null` means unrestricted. Drives the alias-reachable-count badge.
+  // Omitted by callers that have no cap to apply.
+  cap?: readonly string[] | null;
 }>();
 
 defineEmits<{ clear: [] }>();
@@ -13,6 +27,97 @@ const formatTokenLimit = (n: number) => {
   if (n >= 1_000) return `${(n / 1_000).toFixed(n % 1_000 === 0 ? 0 : 1)}k`;
   return n.toString();
 };
+
+// Shape used by the alias-of badge AND the selection badge to read the
+// caller-cap-aware reachable subset. `null` when the row is not an alias
+// or no catalog was supplied — both badges then go dormant.
+const aliasReach = computed<{ total: number; reachable: number; sole: ControlPlaneModel | null } | null>(() => {
+  const a = props.model.aliasedFrom;
+  if (!a) return null;
+  if (props.catalog === undefined) {
+    // No catalog → "everything configured is reachable" (the row was
+    // rendered in isolation, no cap context to apply).
+    return { total: a.targets.length, reachable: a.targets.length, sole: null };
+  }
+  const reachable = reachableTargets(props.model, props.catalog, props.cap ?? null);
+  return {
+    total: a.targets.length,
+    reachable: reachable.length,
+    sole: reachable.length === 1 ? reachable[0] : null,
+  };
+});
+
+// `alias of: <id>` when only one reachable target is also a visible
+// catalog row (admin or non-admin under a narrow cap viewing a single-
+// target alias) — use the raw model id, not its display name, so the
+// badge mirrors the value the operator typed into the alias target
+// field and the value a client would put on the wire;
+// `alias of: N models` when every configured target is reachable;
+// `alias of: K / N models` when some are out of cap.
+const aliasOfLabel = computed<string | null>(() => {
+  const r = aliasReach.value;
+  if (r === null) return null;
+  if (r.sole !== null) return `alias of: ${r.sole.id}`;
+  if (r.reachable === r.total) return `alias of: ${r.total} model${r.total === 1 ? '' : 's'}`;
+  return `alias of: ${r.reachable} / ${r.total} models`;
+});
+
+// Single-target chip is enough — drop the parallel `selection: random`
+// label, which only matters for multi-target aliases where the resolver
+// genuinely picks between candidates.
+const selectionLabel = computed<string | null>(() => {
+  const a = props.model.aliasedFrom;
+  if (!a) return null;
+  if (aliasReach.value?.sole !== null) return null;
+  return `selection: ${a.selection}`;
+});
+
+// Provider badges this row renders. Real models advertise their own
+// `upstreams` bindings directly. Alias rows have an empty `upstreams`
+// list on the wire (the server intentionally lifts upstream info to
+// the targets) — compute the de-duped union of the caller-reachable
+// targets' bindings here so the alias surfaces the same provider-badge
+// shape every real-model row does. Each binding is further filtered
+// against the cap: a target may sit on three upstreams of which only
+// one is currently in cap; only the in-cap one is the provider the
+// resolver would actually route to.
+const effectiveUpstreams = computed<readonly { kind: ControlPlaneModel['upstreams'][number]['kind']; id: string; name: string }[]>(() => {
+  if (props.model.aliasedFrom === undefined) return props.model.upstreams;
+  if (props.catalog === undefined) return [];
+  const cap = props.cap ?? null;
+  const seen = new Set<string>();
+  const out: ControlPlaneModel['upstreams'] = [];
+  for (const target of reachableTargets(props.model, props.catalog, cap)) {
+    for (const binding of target.upstreams) {
+      if (cap !== null && !cap.includes(binding.id)) continue;
+      if (seen.has(binding.id)) continue;
+      seen.add(binding.id);
+      out.push(binding);
+    }
+  }
+  return out;
+});
+
+// Single-target aliases render one badge per rule; multi-target aliases
+// collapse to "<field>: varies" for any field whose values disagree across
+// targets. Each badge carries an explicit `field` key so the bucket walk
+// groups by the rule slot directly rather than parsing the label string.
+const ruleBadges = computed<{ label: string }[]>(() => {
+  const a = props.model.aliasedFrom;
+  if (!a) return [];
+  if (a.targets.length === 1) return formatAliasRuleBadges(a.targets[0].rules);
+  const byField = new Map<AliasRuleBadgeField, Set<string>>();
+  for (const t of a.targets) {
+    for (const badge of formatAliasRuleBadges(t.rules)) {
+      const set = byField.get(badge.field) ?? new Set<string>();
+      set.add(badge.label);
+      byField.set(badge.field, set);
+    }
+  }
+  return Array.from(byField.entries()).map(([field, set]) => ({
+    label: set.size === 1 ? [...set][0] : `${field}: varies`,
+  }));
+});
 </script>
 
 <template>
@@ -28,7 +133,7 @@ const formatTokenLimit = (n: number) => {
         </div>
         <div class="flex flex-wrap gap-1.5 mt-2">
           <span
-            v-for="binding in model.upstreams"
+            v-for="binding in effectiveUpstreams"
             :key="binding.id"
             class="text-[10px] font-semibold px-2 py-0.5 rounded-full border"
             :class="providerBadgeClass(binding.kind)"
@@ -43,6 +148,13 @@ const formatTokenLimit = (n: number) => {
           <span v-if="model.limits?.max_output_tokens" class="text-[10px] font-mono px-2 py-0.5 rounded-full bg-surface-600 text-gray-400">
             output: {{ formatTokenLimit(model.limits.max_output_tokens) }}
           </span>
+          <span v-if="aliasOfLabel" class="text-[10px] font-mono px-2 py-0.5 rounded-full border border-white/15 text-gray-400">{{ aliasOfLabel }}</span>
+          <span v-if="selectionLabel" class="text-[10px] font-mono px-2 py-0.5 rounded-full border border-white/15 text-gray-400">{{ selectionLabel }}</span>
+          <span
+            v-for="badge in ruleBadges"
+            :key="badge.label"
+            class="text-[10px] font-mono px-2 py-0.5 rounded-full border border-white/15 text-gray-400"
+          >{{ badge.label }}</span>
         </div>
       </div>
       <button class="btn-ghost text-[11px] flex shrink-0 items-center gap-1" @click="$emit('clear')">
diff --git a/apps/web/src/components/settings/AliasRow.vue b/apps/web/src/components/settings/AliasRow.vue
new file mode 100644
index 000000000..fa3bcbc98
--- /dev/null
+++ b/apps/web/src/components/settings/AliasRow.vue
@@ -0,0 +1,88 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+
+import type { ControlPlaneModel, ModelAlias } from '../../api/types.ts';
+import { computeAliasLevelWarnings } from '../alias-edit/warnings.ts';
+import { Tooltip } from '@floway-dev/ui';
+
+const props = defineProps<{
+  alias: ModelAlias;
+  models: readonly ControlPlaneModel[] | null;
+}>();
+
+defineEmits<{
+  edit: [];
+  delete: [];
+}>();
+
+const title = computed(() => props.alias.display_name ?? props.alias.name);
+
+const KIND_LABELS: Record<ModelAlias['kind'], string> = {
+  chat: 'Chat',
+  embedding: 'Embedding',
+  image: 'Image',
+};
+
+const SELECTION_LABELS: Record<ModelAlias['selection'], string> = {
+  'first-available': 'First available',
+  random: 'Random',
+};
+
+const kindLabel = computed(() => KIND_LABELS[props.alias.kind]);
+const selectionLabel = computed(() => SELECTION_LABELS[props.alias.selection]);
+const targetCountLabel = computed(() => `${props.alias.targets.length} target${props.alias.targets.length === 1 ? '' : 's'}`);
+
+const aliasWarnings = computed(() => computeAliasLevelWarnings(props.alias, props.models));
+const aliasWarningTooltip = computed(() => aliasWarnings.value.map(w => w.message).join('\n'));
+</script>
+
+<template>
+  <div class="rounded-lg border border-white/5 bg-surface-800/80 px-3 py-2.5">
+    <div class="flex items-center gap-3">
+      <div class="min-w-0 flex-1">
+        <div class="flex flex-wrap items-baseline gap-x-2">
+          <h4 class="truncate text-sm font-semibold text-white">{{ title }}</h4>
+          <span class="truncate font-mono text-xs text-gray-500">{{ alias.name }}</span>
+        </div>
+        <p class="mt-0.5 truncate text-xs text-gray-500">
+          {{ kindLabel }} · {{ targetCountLabel }} · {{ selectionLabel }}<template v-if="!alias.visible_in_models_list"> · hidden from <code class="font-mono">/v1/models</code></template>
+        </p>
+      </div>
+
+      <div class="flex shrink-0 items-center gap-1">
+        <Tooltip v-if="aliasWarnings.length > 0" :content="aliasWarningTooltip">
+          <span
+            class="inline-flex h-8 w-8 items-center justify-center rounded-md text-amber-400"
+            aria-label="Alias warning"
+          >
+            <i class="i-lucide-alert-triangle size-4" />
+          </span>
+        </Tooltip>
+        <button
+          type="button"
+          class="inline-flex h-8 w-8 items-center justify-center rounded-md p-1 text-gray-600 transition-colors hover:bg-white/[0.04] hover:text-accent-cyan"
+          aria-label="Edit alias"
+          title="Edit"
+          @click="$emit('edit')"
+        >
+          <svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M17 3a2.83 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z" />
+            <path d="m15 5 4 4" />
+          </svg>
+        </button>
+        <button
+          type="button"
+          class="inline-flex h-8 w-8 items-center justify-center rounded-md p-1 text-gray-600 transition-colors hover:bg-white/[0.04] hover:text-accent-rose"
+          aria-label="Delete alias"
+          title="Delete"
+          @click="$emit('delete')"
+        >
+          <svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <polyline points="3 6 5 6 21 6" />
+            <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web/src/components/settings/AliasRow_test.ts b/apps/web/src/components/settings/AliasRow_test.ts
new file mode 100644
index 000000000..0814ca80c
--- /dev/null
+++ b/apps/web/src/components/settings/AliasRow_test.ts
@@ -0,0 +1,119 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+
+import AliasRow from './AliasRow.vue';
+import { buildAliasModel, buildRealModel } from '../../api/test-fixtures.ts';
+import type { ControlPlaneModel, ModelAlias } from '../../api/types.ts';
+
+const alias = (over: Partial<ModelAlias> & { name: string }): ModelAlias => ({
+  kind: 'chat',
+  selection: 'first-available',
+  display_name: null,
+  visible_in_models_list: true,
+  targets: [{ target_model_id: 'gpt-5', rules: {} }],
+  announced_metadata: null,
+  sort_order: 0,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+  ...over,
+});
+
+const realModel = (id: string, display?: string): ControlPlaneModel =>
+  buildRealModel(display !== undefined ? { id, display_name: display } : { id });
+
+const aliasModel = (id: string): ControlPlaneModel => buildAliasModel({ id });
+
+describe('AliasRow', () => {
+  it('renders display_name when set; otherwise falls back to the alias id', () => {
+    const withDisplay = mount(AliasRow, { props: { alias: alias({ name: 'a', display_name: 'My Friendly Name' }), models: [] } });
+    expect(withDisplay.find('h4').text()).toBe('My Friendly Name');
+
+    // No operator-set display: title shows the alias id verbatim (same string
+    // as the mono pill next to it — the chat-playground idiom).
+    const single = mount(AliasRow, {
+      props: {
+        alias: alias({ name: 'a', display_name: null, targets: [{ target_model_id: 'gpt-5', rules: { reasoning: { effort: 'low' } } }] }),
+        models: [],
+      },
+    });
+    expect(single.find('h4').text()).toBe('a');
+
+    const multi = mount(AliasRow, {
+      props: {
+        alias: alias({
+          name: 'gizmo',
+          display_name: null,
+          targets: [
+            { target_model_id: 'gpt-5', rules: {} },
+            { target_model_id: 'claude', rules: {} },
+          ],
+        }),
+        models: [],
+      },
+    });
+    expect(multi.find('h4').text()).toBe('gizmo');
+  });
+
+  it('formats the caption: Kind · N targets · Selection (and optional hidden suffix); the alias id sits next to the title', () => {
+    const w = mount(AliasRow, {
+      props: {
+        alias: alias({
+          name: 'auto-review',
+          selection: 'random',
+          visible_in_models_list: false,
+          targets: [
+            { target_model_id: 'a', rules: {} },
+            { target_model_id: 'b', rules: {} },
+          ],
+        }),
+        models: [],
+      },
+    });
+    expect(w.find('p').text()).toBe('Chat · 2 targets · Random · hidden from /v1/models');
+    // The alias id stamp sits on the title row, in mono.
+    expect(w.find('div.flex.items-baseline span').text()).toBe('auto-review');
+
+    const sole = mount(AliasRow, {
+      props: { alias: alias({ name: 'one' }), models: [] },
+    });
+    expect(sole.find('p').text()).toBe('Chat · 1 target · First available');
+  });
+
+  it('emits edit on the pencil button and delete on the trash button', async () => {
+    const w = mount(AliasRow, { props: { alias: alias({ name: 'a' }), models: [] } });
+    const edit = w.find('button[aria-label="Edit alias"]');
+    const del = w.find('button[aria-label="Delete alias"]');
+    await edit.trigger('click');
+    await del.trigger('click');
+    expect(w.emitted('edit')).toHaveLength(1);
+    expect(w.emitted('delete')).toHaveLength(1);
+  });
+
+  it('renders the alias-level warning icon only when the shadow warning fires', () => {
+    const catalog = [realModel('gpt-5'), realModel('plain')];
+
+    const noShadow = mount(AliasRow, { props: { alias: alias({ name: 'unique', targets: [{ target_model_id: 'gpt-5', rules: {} }] }), models: catalog } });
+    expect(noShadow.find('span[aria-label="Alias warning"]').exists()).toBe(false);
+
+    const shadow = mount(AliasRow, { props: { alias: alias({ name: 'gpt-5', targets: [{ target_model_id: 'plain', rules: {} }] }), models: catalog } });
+    expect(shadow.find('span[aria-label="Alias warning"]').exists()).toBe(true);
+
+    // Seed pattern (target references shadowed id) suppresses the warning.
+    const seeded = mount(AliasRow, {
+      props: {
+        alias: alias({ name: 'gpt-5', targets: [{ target_model_id: 'gpt-5', rules: {} }, { target_model_id: 'plain', rules: {} }] }),
+        models: catalog,
+      },
+    });
+    expect(seeded.find('span[aria-label="Alias warning"]').exists()).toBe(false);
+
+    // An alias-name collision against another alias doesn't shadow (only real-model collisions do).
+    const aliasCollision = mount(AliasRow, {
+      props: {
+        alias: alias({ name: 'auto-review', targets: [{ target_model_id: 'plain', rules: {} }] }),
+        models: [aliasModel('auto-review'), realModel('plain')],
+      },
+    });
+    expect(aliasCollision.find('span[aria-label="Alias warning"]').exists()).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/settings/AliasesSettingsCard.vue b/apps/web/src/components/settings/AliasesSettingsCard.vue
new file mode 100644
index 000000000..85e35d0f2
--- /dev/null
+++ b/apps/web/src/components/settings/AliasesSettingsCard.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+
+import AliasRow from './AliasRow.vue';
+import { callApi, useApi } from '../../api/client.ts';
+import type { ModelAlias } from '../../api/types.ts';
+import { useModelAliases } from '../../composables/useModelAliases.ts';
+import { useRawModelsStore } from '../../composables/useModels.ts';
+import { Spinner } from '@floway-dev/ui';
+
+const emit = defineEmits<{
+  'add': [];
+  'edit': [record: ModelAlias];
+  'changed': [];
+}>();
+
+const api = useApi();
+const aliasesStore = useModelAliases();
+const modelsStore = useRawModelsStore();
+
+const aliases = computed<ModelAlias[]>(() => aliasesStore.aliases.value ?? []);
+
+const deleteAlias = async (record: ModelAlias) => {
+  if (!window.confirm(`Delete alias "${record.name}"?`)) return;
+  const { error } = await callApi(() => api.api.aliases[':name'].$delete({ param: { name: record.name } }));
+  if (error) {
+    window.alert(`Delete failed: ${error.message}`);
+    return;
+  }
+  emit('changed');
+};
+</script>
+
+<template>
+  <div class="glass-card p-5 sm:p-6 animate-in delay-2">
+    <div class="mb-4 flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+      <div class="min-w-0">
+        <h3 class="text-white font-semibold mb-1">Aliases</h3>
+        <p class="text-sm text-gray-400">
+          Named virtual model ids that resolve to one of N target models, with optional per-target rule overlays.
+        </p>
+      </div>
+      <button class="btn-primary !py-2.5 !px-3 text-xs whitespace-nowrap" @click="emit('add')">Add Alias</button>
+    </div>
+
+    <p v-if="aliasesStore.error.value" class="mb-3 rounded-md border border-accent-rose/40 bg-accent-rose/10 px-3 py-2 text-sm text-accent-rose">
+      Failed to load aliases: {{ aliasesStore.error.value }}
+    </p>
+
+    <p v-if="!aliasesStore.error.value && aliases.length === 0" class="text-sm text-gray-500">
+      No aliases configured. Add one to expose a virtual model id that routes across multiple targets with locked rules.
+    </p>
+
+    <div v-else-if="aliases.length > 0" class="space-y-2">
+      <AliasRow
+        v-for="alias in aliases"
+        :key="alias.name"
+        :alias="alias"
+        :models="modelsStore.models.value"
+        @edit="emit('edit', alias)"
+        @delete="deleteAlias(alias)"
+      />
+    </div>
+
+    <Spinner v-if="aliasesStore.loading.value && aliases.length > 0" class="mt-3 h-4 w-4 text-gray-500" />
+  </div>
+</template>
diff --git a/apps/web/src/components/settings/AliasesSettingsCard_test.ts b/apps/web/src/components/settings/AliasesSettingsCard_test.ts
new file mode 100644
index 000000000..0a5cf7683
--- /dev/null
+++ b/apps/web/src/components/settings/AliasesSettingsCard_test.ts
@@ -0,0 +1,112 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { nextTick, ref } from 'vue';
+
+import { buildRealModel } from '../../api/test-fixtures.ts';
+import type { ControlPlaneModel, ModelAlias } from '../../api/types.ts';
+
+const aliasesRef = ref<ModelAlias[]>([]);
+const modelsRef = ref<ControlPlaneModel[]>([]);
+const aliasErrorRef = ref<string | null>(null);
+const deleteSpy = vi.fn(async (_arg: unknown) => new Response(null, { status: 204 }));
+
+vi.mock('../../composables/useModelAliases.ts', () => ({
+  useModelAliases: () => ({ aliases: aliasesRef, loading: ref(false), error: aliasErrorRef, load: async () => {} }),
+}));
+vi.mock('../../composables/useModels.ts', () => ({
+  useRawModelsStore: () => ({ models: modelsRef, loading: ref(false), error: ref<string | null>(null), load: async () => {} }),
+}));
+vi.mock('../../api/client.ts', () => ({
+  useApi: () => ({
+    api: {
+      aliases: {
+        ':name': { $delete: (arg: unknown) => deleteSpy(arg) },
+      },
+    },
+  }),
+  callApi: async <T>(fn: () => Promise<Response>) => {
+    const res = await fn();
+    if (!res.ok && res.status !== 204) return { error: { status: res.status, message: 'mock-error' } };
+    return { data: undefined as T };
+  },
+  authFetch: vi.fn(),
+}));
+
+const { default: AliasesSettingsCard } = await import('./AliasesSettingsCard.vue');
+
+const baseAlias = (over: Partial<ModelAlias> & { name: string }): ModelAlias => ({
+  kind: 'chat',
+  selection: 'first-available',
+  display_name: null,
+  visible_in_models_list: true,
+  targets: [{ target_model_id: 'gpt-5', rules: {} }],
+  announced_metadata: null,
+  sort_order: 0,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+  ...over,
+});
+
+beforeEach(() => {
+  aliasesRef.value = [];
+  // Seed the catalog with the alias fixtures' target ids so the
+  // no-target alias-level warning stays quiet by default — every test
+  // that wants the warning sets `modelsRef.value = []` itself.
+  modelsRef.value = [
+    buildRealModel({ id: 'gpt-5' }),
+  ];
+  aliasErrorRef.value = null;
+  deleteSpy.mockClear();
+  vi.restoreAllMocks();
+  // happy-dom does not stub window.confirm / window.alert by default; install
+  // a no-op pair every test overrides per-case via reassignment.
+  window.confirm = () => true;
+  window.alert = () => {};
+});
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('AliasesSettingsCard', () => {
+  it('renders the empty-state copy when no aliases are configured', () => {
+    const w = mount(AliasesSettingsCard);
+    expect(w.text()).toContain('No aliases configured');
+  });
+
+  it('renders one row per alias', () => {
+    aliasesRef.value = [
+      baseAlias({ name: 'a' }),
+      baseAlias({ name: 'b' }),
+    ];
+    const w = mount(AliasesSettingsCard);
+    expect(w.findAll('button[aria-label="Edit alias"]')).toHaveLength(2);
+  });
+
+  it('emits add when the "Add Alias" button is clicked', async () => {
+    const w = mount(AliasesSettingsCard);
+    const addBtn = w.findAll('button').find(b => b.text() === 'Add Alias')!;
+    await addBtn.trigger('click');
+    expect(w.emitted('add')).toHaveLength(1);
+  });
+
+  it('prompts confirm and calls DELETE, then emits changed when the trash button fires and the user confirms', async () => {
+    aliasesRef.value = [baseAlias({ name: 'doomed' })];
+    window.confirm = () => true;
+    const w = mount(AliasesSettingsCard);
+    await w.find('button[aria-label="Delete alias"]').trigger('click');
+    await nextTick();
+    expect(deleteSpy).toHaveBeenCalledTimes(1);
+    expect(w.emitted('changed')).toHaveLength(1);
+  });
+
+  it('skips the DELETE call when the user cancels the confirm prompt', async () => {
+    aliasesRef.value = [baseAlias({ name: 'doomed' })];
+    window.confirm = () => false;
+    const w = mount(AliasesSettingsCard);
+    await w.find('button[aria-label="Delete alias"]').trigger('click');
+    await nextTick();
+    expect(deleteSpy).not.toHaveBeenCalled();
+    expect(w.emitted('changed')).toBeUndefined();
+  });
+});
diff --git a/apps/web/src/components/shared/ChatMetadataEditor.vue b/apps/web/src/components/shared/ChatMetadataEditor.vue
new file mode 100644
index 000000000..d3539af8f
--- /dev/null
+++ b/apps/web/src/components/shared/ChatMetadataEditor.vue
@@ -0,0 +1,475 @@
+<script setup lang="ts">
+// Shared editor for a chat/embedding model's `limits` + `chat` metadata.
+// Hosts the Limits + Modalities + Reasoning sub-blocks consumed by both
+// `ModelEditor.vue` (a real catalog row's editor) and
+// `AliasEditDialog.vue` (the alias's announced-metadata override).
+//
+// Controlled component: the parent owns the `mode` flip.
+//   - `mode === 'manual'` → every field is editable; interactions emit.
+//   - `mode === 'auto'`   → every field renders read-only; interactions
+//     are no-ops. The parent passes in the computed snapshot via
+//     `modelValue` so the operator still sees the live values.
+//
+// Kind-gated sub-blocks:
+//   - `chat`      → Limits + Modalities + Reasoning.
+//   - `embedding` → Limits only.
+//   - `image`     → renders nothing (callers should not mount this).
+
+import { computed, ref, watch } from 'vue';
+
+import type { AnnouncedMetadata, ChatModelInfo, ModelKind } from '../../api/types.ts';
+import { parseOptionalNumber } from '../../utils/parse-optional-number.ts';
+import { Button, Input, Switch, Tooltip } from '@floway-dev/ui';
+
+const props = defineProps<{
+  modelValue: AnnouncedMetadata | undefined;
+  kind: ModelKind;
+  mode: 'auto' | 'manual';
+}>();
+
+const emit = defineEmits<{
+  'update:modelValue': [next: AnnouncedMetadata | undefined];
+}>();
+
+const value = computed<AnnouncedMetadata>(() => props.modelValue ?? {});
+const editable = computed(() => props.mode === 'manual');
+const showChatBlocks = computed(() => props.kind === 'chat');
+const renderAnything = computed(() => props.kind !== 'image');
+
+// Known Codex CLI effort presets as of v0.137. Codex's wire type is open
+// (ReasoningEffort::Custom(String)) so any string is accepted upstream;
+// these are just the convenient quick-adds. See:
+// https://github.com/openai/codex/blob/main/codex-rs/protocol/src/openai_models.rs
+const REASONING_LEVELS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+
+// Strip empty sub-blocks so the wire payload stays minimal — the alias
+// listing fallback only kicks in for absent fields; the upstream model
+// config likewise treats a missing key as "inherit".
+const patch = (next: AnnouncedMetadata) => {
+  if (!editable.value) return;
+  const out: AnnouncedMetadata = {};
+  if (next.limits && Object.keys(next.limits).length > 0) out.limits = next.limits;
+  if (next.chat && (next.chat.modalities !== undefined || next.chat.reasoning !== undefined)) out.chat = next.chat;
+  emit('update:modelValue', Object.keys(out).length > 0 ? out : undefined);
+};
+
+// ── Limits ────────────────────────────────────────────────────────────
+
+const updateLimit = (
+  key: 'max_context_window_tokens' | 'max_prompt_tokens' | 'max_output_tokens',
+  raw: string | number | null | undefined,
+) => {
+  if (!editable.value) return;
+  const limits = { ...(value.value.limits ?? {}) };
+  const num = parseOptionalNumber(raw);
+  if (num === undefined) delete limits[key];
+  else limits[key] = num;
+  patch({ ...value.value, limits: Object.keys(limits).length > 0 ? limits : undefined });
+};
+
+// ── Chat builder helpers ──────────────────────────────────────────────
+
+const buildNextChat = (partial: Partial<ChatModelInfo>): ChatModelInfo | undefined => {
+  const base = value.value.chat ?? {};
+  const next: ChatModelInfo = { ...base, ...partial };
+
+  // Normalise: omit modalities when it would only carry the default
+  // (text-only) shape.
+  const hasImageInput = next.modalities?.input.includes('image') === true;
+  next.modalities = hasImageInput
+    ? { input: ['text', 'image'], output: ['text'] }
+    : undefined;
+
+  if (!next.modalities && !next.reasoning) return undefined;
+  return next;
+};
+
+const buildNextReasoning = (
+  update: Partial<NonNullable<ChatModelInfo['reasoning']>>,
+): ChatModelInfo['reasoning'] => {
+  const base = value.value.chat?.reasoning ?? {};
+  const merged = { ...base, ...update };
+  const cleaned = Object.fromEntries(
+    Object.entries(merged).filter(([, v]) => v !== undefined),
+  ) as NonNullable<ChatModelInfo['reasoning']>;
+  return Object.keys(cleaned).length > 0 ? cleaned : undefined;
+};
+
+const setChat = (chat: ChatModelInfo | undefined) => {
+  patch({ ...value.value, chat });
+};
+
+// ── Modalities ────────────────────────────────────────────────────────
+
+const chatImageInput = computed<boolean>(
+  () => value.value.chat?.modalities?.input.includes('image') ?? false,
+);
+
+const toggleImageInput = (on: boolean) => {
+  if (!editable.value) return;
+  setChat(buildNextChat({ modalities: on ? { input: ['text', 'image'], output: ['text'] } : undefined }));
+};
+
+// ── Reasoning sub-block enabled states ────────────────────────────────
+
+const effortEnabled = computed(() => value.value.chat?.reasoning?.effort !== undefined);
+const budgetTokensEnabled = computed(() => value.value.chat?.reasoning?.budget_tokens !== undefined);
+const adaptiveEnabled = computed(() => value.value.chat?.reasoning?.adaptive === true);
+const mandatoryEnabled = computed(() => value.value.chat?.reasoning?.mandatory === true);
+
+// Mandatory is exclusive: when on, the three operator-controlled toggles
+// lock off. When any of those is on, Mandatory locks off. UI-only
+// constraint (the schema would technically accept any subset).
+const anyControlledEnabled = computed(() => effortEnabled.value || budgetTokensEnabled.value || adaptiveEnabled.value);
+const controlledDisabled = computed(() => !editable.value || mandatoryEnabled.value);
+const mandatoryDisabled = computed(() => !editable.value || anyControlledEnabled.value);
+
+const supportedEfforts = computed<readonly string[]>(
+  () => value.value.chat?.reasoning?.effort?.supported ?? [],
+);
+const presetEffortLevels = computed(() => REASONING_LEVELS.filter(level => !supportedEfforts.value.includes(level)));
+
+// Free-typing input for adding a custom reasoning level not in the quick-add list.
+const reasoningLevelInput = ref('');
+
+// Resync input buffer when the active kind changes (parent may swap the
+// hosted record under us).
+watch(() => props.kind, () => { reasoningLevelInput.value = ''; });
+
+// ── Effort sub-block ──────────────────────────────────────────────────
+
+const toggleEffort = (on: boolean) => {
+  if (!editable.value) return;
+  const reasoning = on
+    ? buildNextReasoning({ effort: { supported: ['low', 'medium', 'high'], default: 'medium' } })
+    : buildNextReasoning({ effort: undefined });
+  setChat(buildNextChat({ reasoning }));
+};
+
+const addReasoningLevel = (level: string) => {
+  if (!editable.value) return;
+  const trimmed = level.trim();
+  if (trimmed === '') return;
+  const current = supportedEfforts.value;
+  if (current.includes(trimmed)) return;
+  const updated = [...current, trimmed];
+  const existing = value.value.chat?.reasoning?.effort;
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: updated, default: existing?.default ?? '' } }) }));
+};
+
+const removeReasoningLevel = (level: string) => {
+  if (!editable.value) return;
+  const current = supportedEfforts.value;
+  const removedIndex = current.indexOf(level);
+  const updated = current.filter(e => e !== level);
+  const existingEffort = value.value.chat?.reasoning?.effort;
+  // The default must always be one of the supported levels (or empty
+  // when the list itself is empty). When the operator deletes the
+  // current default, pick the neighbor that slides into the same index
+  // slot — falling back to the new tail when the removed entry was the
+  // last one.
+  let nextDefault = existingEffort?.default ?? '';
+  if (existingEffort?.default === level) {
+    if (updated.length === 0) nextDefault = '';
+    else if (removedIndex < updated.length) nextDefault = updated[removedIndex]!;
+    else nextDefault = updated[updated.length - 1]!;
+  }
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: updated, default: nextDefault } }) }));
+};
+
+const commitReasoningInput = () => {
+  const trimmed = reasoningLevelInput.value.trim();
+  if (trimmed === '') return;
+  addReasoningLevel(trimmed);
+  reasoningLevelInput.value = '';
+};
+
+const setDefaultEffort = (level: string) => {
+  if (!editable.value) return;
+  const current = supportedEfforts.value;
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: current, default: level } }) }));
+};
+
+// ── Effort tag drag-to-reorder ────────────────────────────────────────
+//
+// HTML5 DnD distinguishes drag from click via a built-in pointer-distance
+// threshold: a mousedown+mouseup with no movement still fires `click`
+// (and sets the default), while a mousedown+drag+drop suppresses click
+// entirely. So the two affordances coexist on the same button element.
+const draggedEffortIndex = ref<number | null>(null);
+const dragOverEffortIndex = ref<number | null>(null);
+
+const onEffortDragStart = (index: number, e: DragEvent) => {
+  if (!editable.value) return;
+  draggedEffortIndex.value = index;
+  if (e.dataTransfer) {
+    e.dataTransfer.effectAllowed = 'move';
+    // Firefox requires setData to actually initiate the drag.
+    e.dataTransfer.setData('text/plain', String(index));
+  }
+};
+
+const onEffortDragOver = (index: number, e: DragEvent) => {
+  if (draggedEffortIndex.value === null) return;
+  e.preventDefault();
+  if (e.dataTransfer) e.dataTransfer.dropEffect = 'move';
+  dragOverEffortIndex.value = index;
+};
+
+const onEffortDragLeave = (index: number) => {
+  if (dragOverEffortIndex.value === index) dragOverEffortIndex.value = null;
+};
+
+const onEffortDrop = (index: number, e: DragEvent) => {
+  e.preventDefault();
+  const from = draggedEffortIndex.value;
+  draggedEffortIndex.value = null;
+  dragOverEffortIndex.value = null;
+  if (from === null || from === index || !editable.value) return;
+  const current = [...supportedEfforts.value];
+  const [moved] = current.splice(from, 1);
+  if (moved === undefined) return;
+  current.splice(index, 0, moved);
+  const existing = value.value.chat?.reasoning?.effort;
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: current, default: existing?.default ?? '' } }) }));
+};
+
+const onEffortDragEnd = () => {
+  draggedEffortIndex.value = null;
+  dragOverEffortIndex.value = null;
+};
+
+// ── Budget tokens sub-block ───────────────────────────────────────────
+
+const toggleBudgetTokens = (on: boolean) => {
+  if (!editable.value) return;
+  const reasoning = on
+    ? buildNextReasoning({ budget_tokens: {} })
+    : buildNextReasoning({ budget_tokens: undefined });
+  setChat(buildNextChat({ reasoning }));
+};
+
+const updateBudgetTokensMin = (raw: string | number | null | undefined) => {
+  if (!editable.value) return;
+  const num = parseOptionalNumber(raw);
+  const current = value.value.chat?.reasoning?.budget_tokens ?? {};
+  const next = { ...current };
+  if (num === undefined) delete next.min; else next.min = num;
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ budget_tokens: next }) }));
+};
+
+const updateBudgetTokensMax = (raw: string | number | null | undefined) => {
+  if (!editable.value) return;
+  const num = parseOptionalNumber(raw);
+  const current = value.value.chat?.reasoning?.budget_tokens ?? {};
+  const next = { ...current };
+  if (num === undefined) delete next.max; else next.max = num;
+  setChat(buildNextChat({ reasoning: buildNextReasoning({ budget_tokens: next }) }));
+};
+
+// ── Adaptive / Mandatory toggles ──────────────────────────────────────
+
+const toggleAdaptive = (on: boolean) => {
+  if (!editable.value) return;
+  const reasoning = on
+    ? buildNextReasoning({ adaptive: true })
+    : buildNextReasoning({ adaptive: undefined });
+  setChat(buildNextChat({ reasoning }));
+};
+
+const toggleMandatory = (on: boolean) => {
+  if (!editable.value) return;
+  const reasoning = on
+    ? buildNextReasoning({ mandatory: true })
+    : buildNextReasoning({ mandatory: undefined });
+  setChat(buildNextChat({ reasoning }));
+};
+</script>
+
+<template>
+  <div v-if="renderAnything" class="space-y-6">
+    <section>
+      <div class="mb-3 flex items-baseline gap-3">
+        <h4 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Limits</h4>
+        <span class="text-[11px] text-gray-500">tokens</span>
+      </div>
+      <div class="grid gap-3 sm:grid-cols-3">
+        <label class="block space-y-1.5">
+          <span class="block text-xs font-medium text-gray-500">Context Window</span>
+          <Input
+            type="number"
+            :model-value="value.limits?.max_context_window_tokens"
+            :readonly="!editable"
+            placeholder="e.g. 1050000"
+            class="font-mono"
+            @update:model-value="v => updateLimit('max_context_window_tokens', v)"
+          />
+        </label>
+        <label class="block space-y-1.5">
+          <span class="block text-xs font-medium text-gray-500">Prompt Tokens</span>
+          <Input
+            type="number"
+            :model-value="value.limits?.max_prompt_tokens"
+            :readonly="!editable"
+            placeholder="e.g. 922000"
+            class="font-mono"
+            @update:model-value="v => updateLimit('max_prompt_tokens', v)"
+          />
+        </label>
+        <label class="block space-y-1.5">
+          <span class="block text-xs font-medium text-gray-500">Output Tokens</span>
+          <Input
+            type="number"
+            :model-value="value.limits?.max_output_tokens"
+            :readonly="!editable"
+            placeholder="e.g. 128000"
+            class="font-mono"
+            @update:model-value="v => updateLimit('max_output_tokens', v)"
+          />
+        </label>
+      </div>
+    </section>
+
+    <section v-if="showChatBlocks">
+      <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
+        <h4 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Modalities</h4>
+        <label class="flex items-center gap-2" :class="editable ? 'cursor-pointer' : 'cursor-not-allowed'">
+          <Switch
+            :model-value="chatImageInput"
+            :disabled="!editable"
+            @update:model-value="v => toggleImageInput(v === true)"
+          />
+          <span class="text-xs" :class="chatImageInput ? 'text-white' : 'text-gray-500'">Image input</span>
+        </label>
+      </div>
+    </section>
+
+    <section v-if="showChatBlocks">
+      <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
+        <h4 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Reasoning</h4>
+        <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
+          <Switch :model-value="effortEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleEffort(v === true)" />
+          <span class="text-xs" :class="effortEnabled ? 'text-white' : 'text-gray-500'">Effort levels</span>
+        </label>
+        <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
+          <Switch :model-value="budgetTokensEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleBudgetTokens(v === true)" />
+          <span class="text-xs" :class="budgetTokensEnabled ? 'text-white' : 'text-gray-500'">Budget tokens</span>
+        </label>
+        <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
+          <Switch :model-value="adaptiveEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleAdaptive(v === true)" />
+          <span class="text-xs" :class="adaptiveEnabled ? 'text-white' : 'text-gray-500'">Adaptive</span>
+          <Tooltip content="Model self-selects reasoning effort"><span class="text-[10px] text-gray-600">?</span></Tooltip>
+        </label>
+        <label class="flex items-center gap-2" :class="mandatoryDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
+          <Switch :model-value="mandatoryEnabled" :disabled="mandatoryDisabled" @update:model-value="v => toggleMandatory(v === true)" />
+          <span class="text-xs" :class="mandatoryEnabled ? 'text-white' : 'text-gray-500'">Mandatory</span>
+          <Tooltip content="Reasoning is always applied; caller cannot opt out"><span class="text-[10px] text-gray-600">?</span></Tooltip>
+        </label>
+      </div>
+
+      <div v-if="effortEnabled" class="mt-3 space-y-1.5 border-l-2 border-white/[0.08] pl-3">
+        <div class="flex min-h-[1.625rem] flex-wrap items-center gap-x-3 gap-y-1.5">
+          <span class="text-xs font-semibold text-gray-300">Effort levels</span>
+          <span v-if="editable" class="text-[11px] text-gray-500">(click to set default)</span>
+          <template v-if="supportedEfforts.length > 0">
+            <button
+              v-for="(level, index) in supportedEfforts"
+              :key="level"
+              type="button"
+              class="inline-flex items-center gap-1 rounded border px-2 py-0.5 font-mono text-[11px] transition-colors"
+              :class="[
+                value.chat?.reasoning?.effort?.default === level
+                  ? 'border-accent-cyan/50 bg-accent-cyan/10 text-accent-cyan font-semibold'
+                  : 'border-white/15 bg-white/[0.07] text-gray-300 hover:border-white/30 hover:text-white',
+                editable ? 'cursor-grab active:cursor-grabbing' : 'cursor-not-allowed',
+                draggedEffortIndex === index && 'opacity-40',
+                dragOverEffortIndex === index && draggedEffortIndex !== index && 'ring-1 ring-accent-cyan',
+              ]"
+              :disabled="!editable"
+              :draggable="editable"
+              :title="value.chat?.reasoning?.effort?.default === level ? 'Default — click another to switch, drag to reorder' : 'Click to set as default, drag to reorder'"
+              @click="setDefaultEffort(level)"
+              @dragstart="e => onEffortDragStart(index, e)"
+              @dragover="e => onEffortDragOver(index, e)"
+              @dragleave="onEffortDragLeave(index)"
+              @drop="e => onEffortDrop(index, e)"
+              @dragend="onEffortDragEnd"
+            >
+              {{ level }}
+              <span
+                v-if="editable"
+                role="button"
+                tabindex="0"
+                class="ml-0.5 cursor-pointer text-gray-500 transition-colors hover:text-accent-rose"
+                :aria-label="`Remove ${level}`"
+                @click.stop="removeReasoningLevel(level)"
+                @keydown.enter.stop.prevent="removeReasoningLevel(level)"
+              >
+                <svg class="h-2.5 w-2.5" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2">
+                  <path d="M9 3 3 9M3 3l6 6" />
+                </svg>
+              </span>
+            </button>
+          </template>
+          <p v-else-if="editable" class="whitespace-nowrap text-[11px] text-accent-amber">Add at least one effort level — click a preset on the right.</p>
+          <p v-else class="whitespace-nowrap text-[11px] text-gray-500">—</p>
+        </div>
+        <div v-if="editable" class="flex flex-wrap items-center gap-1.5">
+          <button
+            v-for="level in presetEffortLevels"
+            :key="level"
+            type="button"
+            class="rounded border border-white/15 px-2 py-0.5 font-mono text-[11px] text-gray-400 transition-colors hover:border-accent-cyan/40 hover:text-accent-cyan"
+            @click="addReasoningLevel(level)"
+          >+ {{ level }}</button>
+          <Input
+            v-model="reasoningLevelInput"
+            size="sm"
+            placeholder="custom…"
+            class="!h-6 !w-28 !py-0 !text-[11px] font-mono"
+            @keydown.enter.prevent="commitReasoningInput"
+          />
+          <Button variant="secondary" size="sm" class="!h-6 !px-2 !py-0 !text-[11px]" @click="commitReasoningInput">Add</Button>
+        </div>
+      </div>
+
+      <div v-if="budgetTokensEnabled" class="mt-3 flex flex-wrap items-center gap-3 border-l-2 border-white/[0.08] pl-3">
+        <span class="text-xs font-semibold text-gray-300">Budget tokens</span>
+        <label class="flex items-center gap-1.5">
+          <span class="text-[11px] text-gray-500">Min</span>
+          <Input
+            type="number"
+            min="0"
+            size="sm"
+            :model-value="value.chat?.reasoning?.budget_tokens?.min"
+            :readonly="!editable"
+            placeholder="—"
+            class="!h-6 !w-24 !py-0 !text-[11px] font-mono"
+            @update:model-value="v => updateBudgetTokensMin(v)"
+          />
+        </label>
+        <label class="flex items-center gap-1.5">
+          <span class="text-[11px] text-gray-500">Max</span>
+          <Input
+            type="number"
+            min="0"
+            size="sm"
+            :model-value="value.chat?.reasoning?.budget_tokens?.max"
+            :readonly="!editable"
+            placeholder="—"
+            class="!h-6 !w-24 !py-0 !text-[11px] font-mono"
+            @update:model-value="v => updateBudgetTokensMax(v)"
+          />
+        </label>
+        <p
+          v-if="value.chat?.reasoning?.budget_tokens?.min !== undefined
+            && value.chat?.reasoning?.budget_tokens?.max !== undefined
+            && value.chat.reasoning.budget_tokens.max < value.chat.reasoning.budget_tokens.min"
+          class="text-[11px] text-accent-amber"
+        >
+          Max must be ≥ min.
+        </p>
+      </div>
+    </section>
+  </div>
+</template>
diff --git a/apps/web/src/components/shared/ChatMetadataEditor_test.ts b/apps/web/src/components/shared/ChatMetadataEditor_test.ts
new file mode 100644
index 000000000..7e7a3d293
--- /dev/null
+++ b/apps/web/src/components/shared/ChatMetadataEditor_test.ts
@@ -0,0 +1,111 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { nextTick } from 'vue';
+
+import ChatMetadataEditor from './ChatMetadataEditor.vue';
+import type { AnnouncedMetadata } from '../../api/types.ts';
+
+const baseValue = (): AnnouncedMetadata => ({
+  limits: { max_context_window_tokens: 100_000, max_output_tokens: 4096 },
+  chat: { reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } } },
+});
+
+describe('ChatMetadataEditor', () => {
+  it('renders nothing when kind="image"', () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: baseValue(), kind: 'image', mode: 'manual' },
+    });
+    expect(w.html().trim()).toBe('<!--v-if-->');
+  });
+
+  it('kind="embedding" renders only the Limits section — no Modalities, no Reasoning', () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: baseValue(), kind: 'embedding', mode: 'manual' },
+    });
+    expect(w.text()).toContain('Limits');
+    expect(w.text()).not.toContain('Modalities');
+    expect(w.text()).not.toContain('Reasoning');
+  });
+
+  it('kind="chat" renders Limits + Modalities + Reasoning', () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: baseValue(), kind: 'chat', mode: 'manual' },
+    });
+    const txt = w.text();
+    expect(txt).toContain('Limits');
+    expect(txt).toContain('Modalities');
+    expect(txt).toContain('Reasoning');
+    expect(txt).toContain('Effort levels');
+  });
+
+  it('mode="auto" renders the values, but Switches are disabled and Inputs are readonly', () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: baseValue(), kind: 'chat', mode: 'auto' },
+    });
+    // Operator can still read every limit value.
+    const numberInputs = w.findAll('input[type="number"]');
+    const limitValues = numberInputs.slice(0, 3).map(i => (i.element as HTMLInputElement).value);
+    expect(limitValues).toContain('100000');
+    expect(limitValues).toContain('4096');
+    // Every limit input is readonly.
+    for (const inp of numberInputs.slice(0, 3)) {
+      expect((inp.element as HTMLInputElement).readOnly).toBe(true);
+    }
+    // Every Switch (Reka-UI renders as button[role="switch"]) is disabled.
+    const switches = w.findAll('button[role="switch"]');
+    expect(switches.length).toBeGreaterThan(0);
+    for (const s of switches) {
+      expect((s.element as HTMLButtonElement).disabled).toBe(true);
+    }
+  });
+
+  it('mode="auto": clicking a Switch is a no-op (no update:modelValue emit)', async () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: { chat: {} } as AnnouncedMetadata, kind: 'chat', mode: 'auto' },
+    });
+    // The Modalities image-input Switch is the first Switch under the Modalities section.
+    const switches = w.findAll('button[role="switch"]');
+    expect(switches.length).toBeGreaterThan(0);
+    await switches[0].trigger('click');
+    await nextTick();
+    expect(w.emitted('update:modelValue')).toBeUndefined();
+  });
+
+  it('mode="manual": editing a limit emits update:modelValue with the patched payload', async () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: undefined, kind: 'chat', mode: 'manual' },
+    });
+    const numberInputs = w.findAll('input[type="number"]');
+    const contextInput = numberInputs[0]!.element as HTMLInputElement;
+    contextInput.value = '64000';
+    await numberInputs[0]!.trigger('input');
+    await nextTick();
+    const emitted = w.emitted('update:modelValue');
+    expect(emitted).toBeDefined();
+    const last = emitted![emitted!.length - 1]![0] as AnnouncedMetadata;
+    expect(last.limits?.max_context_window_tokens).toBe(64_000);
+  });
+
+  it('mode="manual": toggling the Effort levels switch on emits a reasoning seed', async () => {
+    const w = mount(ChatMetadataEditor, {
+      props: { modelValue: undefined, kind: 'chat', mode: 'manual' },
+    });
+    // The Effort levels Switch is the second Switch (Modalities image is first).
+    const switches = w.findAll('button[role="switch"]');
+    // Find the one labelled "Effort levels".
+    const labels = w.findAll('label');
+    const effortLabel = labels.find(l => (l.text() ?? '').includes('Effort levels'))!;
+    const effortSwitch = effortLabel.find('button[role="switch"]');
+    expect(effortSwitch.exists()).toBe(true);
+    expect((effortSwitch.element as HTMLButtonElement).disabled).toBe(false);
+    expect(switches.length).toBeGreaterThan(1);
+
+    await effortSwitch.trigger('click');
+    await nextTick();
+    const emitted = w.emitted('update:modelValue');
+    expect(emitted).toBeDefined();
+    const last = emitted![emitted!.length - 1]![0] as AnnouncedMetadata;
+    expect(last.chat?.reasoning?.effort?.supported).toEqual(['low', 'medium', 'high']);
+    expect(last.chat?.reasoning?.effort?.default).toBe('medium');
+  });
+});
diff --git a/apps/web/src/components/upstream-edit/ModelEditor.vue b/apps/web/src/components/upstream-edit/ModelEditor.vue
index 44c5ec8e8..429dfac59 100644
--- a/apps/web/src/components/upstream-edit/ModelEditor.vue
+++ b/apps/web/src/components/upstream-edit/ModelEditor.vue
@@ -4,7 +4,9 @@ import { computed, ref, watch } from 'vue';
 import EndpointsField from './EndpointsField.vue';
 import FlagOverridesEditor from './FlagOverridesEditor.vue';
 import { configOf, defaultEndpointsForKind, publicIdOf, titleFor, type Row } from './modelRows.ts';
-import type { BillingDimension, FlagDef, ModelKind, ModelPricing, UpstreamChatConfig, UpstreamModelConfig, UpstreamProviderKind } from '../../api/types.ts';
+import type { AnnouncedMetadata, BillingDimension, FlagDef, ModelKind, ModelPricing, UpstreamChatConfig, UpstreamModelConfig, UpstreamProviderKind } from '../../api/types.ts';
+import { parseOptionalNumber } from '../../utils/parse-optional-number.ts';
+import ChatMetadataEditor from '../shared/ChatMetadataEditor.vue';
 import { Button, Input, Select, Switch, Tooltip } from '@floway-dev/ui';
 
 const props = defineProps<{
@@ -65,27 +67,6 @@ const setKind = (k: ModelKind) => {
   patch({ kind: k, endpoints: defaultEndpointsForKind(k, config.value.endpoints) });
 };
 
-const parseOptionalNumber = (raw: string | number | null | undefined): number | undefined => {
-  if (raw === '' || raw === null || raw === undefined) return undefined;
-  const num = Number(raw);
-  // Backend pricing validators reject negatives (see `nonNegativeNumberField`
-  // in packages/provider/src/model-config.ts); drop them at the form boundary
-  // so a typo doesn't stage data the next PUT will 400 on.
-  return Number.isFinite(num) && num >= 0 ? num : undefined;
-};
-
-const updateLimit = (
-  key: 'max_context_window_tokens' | 'max_prompt_tokens' | 'max_output_tokens',
-  raw: string | number | null | undefined,
-) => {
-  if (!config.value) return;
-  const limits = { ...(config.value.limits ?? {}) };
-  const num = parseOptionalNumber(raw);
-  if (num === undefined) delete limits[key];
-  else limits[key] = num;
-  patch({ limits: Object.keys(limits).length > 0 ? limits : undefined });
-};
-
 const updateCost = (key: BillingDimension, raw: string | number | null | undefined) => {
   if (!config.value) return;
   const cost = { ...(config.value.cost ?? {}) } as ModelPricing;
@@ -255,44 +236,23 @@ const updateFlagOverrides = (values: Record<string, boolean>) => {
 
 // ── Chat metadata ──────────────────────────────────────────────────────────
 
-// Known Codex CLI effort presets as of v0.137. Codex's wire type is open
-// (ReasoningEffort::Custom(String)) so any string is accepted upstream;
-// these are just the convenient quick-adds. See:
-// https://github.com/openai/codex/blob/main/codex-rs/protocol/src/openai_models.rs
-const REASONING_LEVELS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
-
-// Free-typing input for adding a custom reasoning level not in the quick-add list.
-const reasoningLevelInput = ref('');
-
-// Resync input buffer when the active row changes.
-watch(() => props.row?.uiId, () => {
-  reasoningLevelInput.value = '';
+// Mirror the shared editor's value shape: pull the model's `limits` +
+// `chat` block out of the row config, hand it to ChatMetadataEditor,
+// and forward edits back through `patch()`.
+const chatMetadataValue = computed<AnnouncedMetadata | undefined>(() => {
+  if (!config.value) return undefined;
+  const out: AnnouncedMetadata = {};
+  if (config.value.limits) out.limits = config.value.limits;
+  if (config.value.chat) out.chat = config.value.chat;
+  return out;
 });
 
-const chatImageInput = computed<boolean>(
-  () => config.value?.chat?.modalities?.input.includes('image') ?? false,
-);
-
-// ── Reasoning sub-block enabled states ────────────────────────────────────
-
-const effortEnabled = computed(() => config.value?.chat?.reasoning?.effort !== undefined);
-const budgetTokensEnabled = computed(() => config.value?.chat?.reasoning?.budget_tokens !== undefined);
-const adaptiveEnabled = computed(() => config.value?.chat?.reasoning?.adaptive === true);
-const mandatoryEnabled = computed(() => config.value?.chat?.reasoning?.mandatory === true);
-
-// Mandatory is exclusive: when enabled it dominates and the three operator-
-// controlled toggles disappear. When any of those is on, Mandatory is locked
-// off. UI-only constraint (the schema would technically accept any subset).
-const anyControlledEnabled = computed(() => effortEnabled.value || budgetTokensEnabled.value || adaptiveEnabled.value);
-const controlledDisabled = computed(() => !editable.value || mandatoryEnabled.value);
-const mandatoryDisabled = computed(() => !editable.value || anyControlledEnabled.value);
-
-const supportedEfforts = computed<string[]>(
-  () => config.value?.chat?.reasoning?.effort?.supported ?? [],
-);
-const presetEffortLevels = computed(() => REASONING_LEVELS.filter(level => !supportedEfforts.value.includes(level)));
-
-// ── Validity ───────────────────────────────────────────────────────────────
+const onChatMetadataChange = (next: AnnouncedMetadata | undefined) => {
+  // The editor builds `chat` through fresh object literals — its
+  // `readonly` modality arrays are nominally typed, never frozen, so the
+  // mutable `UpstreamChatConfig` shape held in `config` accepts them.
+  patch({ limits: next?.limits, chat: next?.chat as UpstreamChatConfig | undefined });
+};
 
 // A chat row is invalid when:
 // - effort is enabled but supported list is empty
@@ -300,209 +260,23 @@ const presetEffortLevels = computed(() => REASONING_LEVELS.filter(level => !supp
 // - budget_tokens is enabled but max < min (when both are set)
 const isReasoningValid = computed<boolean>(() => {
   const reasoning = config.value?.chat?.reasoning;
+  if (reasoning === undefined) return true;
 
-  if (effortEnabled.value) {
-    const effort = reasoning?.effort;
-    if (!effort || effort.supported.length === 0) return false;
+  if (reasoning.effort !== undefined) {
+    const effort = reasoning.effort;
+    if (effort.supported.length === 0) return false;
     if (effort.default === '' || !effort.supported.includes(effort.default)) return false;
   }
 
-  if (budgetTokensEnabled.value) {
-    const bt = reasoning?.budget_tokens;
-    if (bt?.min !== undefined && bt?.max !== undefined && bt.max < bt.min) return false;
+  if (reasoning.budget_tokens !== undefined) {
+    const bt = reasoning.budget_tokens;
+    if (bt.min !== undefined && bt.max !== undefined && bt.max < bt.min) return false;
   }
 
   return true;
 });
 
 watch(isReasoningValid, valid => { emit('validity-change', valid); }, { immediate: true });
-
-// ── Chat state builder ─────────────────────────────────────────────────────
-
-const buildNextChat = (partial: Partial<UpstreamChatConfig>): UpstreamChatConfig | undefined => {
-  const base = config.value?.chat ?? {};
-  const next: UpstreamChatConfig = { ...base, ...partial };
-
-  // Normalise: omit modalities when it would only carry the default (text-only) shape.
-  const hasImageInput = next.modalities?.input.includes('image') === true;
-  next.modalities = hasImageInput
-    ? { input: ['text', 'image'], output: ['text'] }
-    : undefined;
-
-  // Return undefined (omit chat key entirely) when nothing is configured.
-  if (!next.modalities && !next.reasoning) return undefined;
-  return next;
-};
-
-// Build a reasoning object with a single key updated, dropping undefined keys.
-const buildNextReasoning = (
-  update: Partial<NonNullable<UpstreamChatConfig['reasoning']>>,
-): UpstreamChatConfig['reasoning'] => {
-  const base = config.value?.chat?.reasoning ?? {};
-  const merged = { ...base, ...update };
-  // Drop keys explicitly set to undefined.
-  const cleaned = Object.fromEntries(
-    Object.entries(merged).filter(([, v]) => v !== undefined),
-  ) as NonNullable<UpstreamChatConfig['reasoning']>;
-  return Object.keys(cleaned).length > 0 ? cleaned : undefined;
-};
-
-const toggleImageInput = (on: boolean) => {
-  if (!editable.value) return;
-  patch({ chat: buildNextChat({ modalities: on ? { input: ['text', 'image'], output: ['text'] } : undefined }) });
-};
-
-// ── Effort sub-block ───────────────────────────────────────────────────────
-
-const toggleEffort = (on: boolean) => {
-  if (!editable.value) return;
-  const reasoning = on
-    ? buildNextReasoning({ effort: { supported: ['low', 'medium', 'high'], default: 'medium' } })
-    : buildNextReasoning({ effort: undefined });
-  patch({ chat: buildNextChat({ reasoning }) });
-};
-
-const addReasoningLevel = (level: string) => {
-  if (!editable.value || !config.value) return;
-  const trimmed = level.trim();
-  if (!trimmed) return;
-  const current = supportedEfforts.value;
-  if (current.includes(trimmed)) return;
-  const updated = [...current, trimmed];
-  const existing = config.value.chat?.reasoning?.effort;
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: updated, default: existing?.default ?? '' } }) }) });
-};
-
-const removeReasoningLevel = (level: string) => {
-  if (!editable.value || !config.value) return;
-  const current = supportedEfforts.value;
-  const removedIndex = current.indexOf(level);
-  const updated = current.filter(e => e !== level);
-  const existingEffort = config.value.chat?.reasoning?.effort;
-  // The default must always be one of the supported levels (or empty when the
-  // list itself is empty). When the operator deletes the current default, pick
-  // the neighbor that slides into the same index slot — falling back to the
-  // new tail when the removed entry was the last one.
-  let nextDefault = existingEffort?.default ?? '';
-  if (existingEffort?.default === level) {
-    if (updated.length === 0) nextDefault = '';
-    else if (removedIndex < updated.length) nextDefault = updated[removedIndex]!;
-    else nextDefault = updated[updated.length - 1]!;
-  }
-  // Keep the effort sub-block even when no levels remain — the empty-list
-  // warning replaces the tag row in-place so the user sees what's needed
-  // without the toggle silently flipping off.
-  const nextEffort = { supported: updated, default: nextDefault };
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ effort: nextEffort }) }) });
-};
-
-const commitReasoningInput = () => {
-  const trimmed = reasoningLevelInput.value.trim();
-  if (!trimmed) return;
-  addReasoningLevel(trimmed);
-  reasoningLevelInput.value = '';
-};
-
-const setDefaultEffort = (value: string) => {
-  if (!editable.value || !config.value) return;
-  const current = supportedEfforts.value;
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: current, default: value } }) }) });
-};
-
-// ── Effort tag drag-to-reorder ─────────────────────────────────────────────
-//
-// HTML5 DnD distinguishes drag from click via a built-in pointer-distance
-// threshold: a mousedown+mouseup with no movement still fires `click` (and
-// sets the default), while a mousedown+drag+drop suppresses click entirely.
-// So the two affordances coexist on the same button element.
-const draggedEffortIndex = ref<number | null>(null);
-const dragOverEffortIndex = ref<number | null>(null);
-
-const onEffortDragStart = (index: number, e: DragEvent) => {
-  if (!editable.value) return;
-  draggedEffortIndex.value = index;
-  if (e.dataTransfer) {
-    e.dataTransfer.effectAllowed = 'move';
-    // Firefox requires setData to actually initiate the drag.
-    e.dataTransfer.setData('text/plain', String(index));
-  }
-};
-
-const onEffortDragOver = (index: number, e: DragEvent) => {
-  if (draggedEffortIndex.value === null) return;
-  e.preventDefault();
-  if (e.dataTransfer) e.dataTransfer.dropEffect = 'move';
-  dragOverEffortIndex.value = index;
-};
-
-const onEffortDragLeave = (index: number) => {
-  if (dragOverEffortIndex.value === index) dragOverEffortIndex.value = null;
-};
-
-const onEffortDrop = (index: number, e: DragEvent) => {
-  e.preventDefault();
-  const from = draggedEffortIndex.value;
-  draggedEffortIndex.value = null;
-  dragOverEffortIndex.value = null;
-  if (from === null || from === index || !config.value) return;
-  const current = [...supportedEfforts.value];
-  const [moved] = current.splice(from, 1);
-  if (moved === undefined) return;
-  current.splice(index, 0, moved);
-  const existing = config.value.chat?.reasoning?.effort;
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ effort: { supported: current, default: existing?.default ?? '' } }) }) });
-};
-
-const onEffortDragEnd = () => {
-  draggedEffortIndex.value = null;
-  dragOverEffortIndex.value = null;
-};
-
-// ── Budget tokens sub-block ────────────────────────────────────────────────
-
-const toggleBudgetTokens = (on: boolean) => {
-  if (!editable.value) return;
-  const reasoning = on
-    ? buildNextReasoning({ budget_tokens: {} })
-    : buildNextReasoning({ budget_tokens: undefined });
-  patch({ chat: buildNextChat({ reasoning }) });
-};
-
-const updateBudgetTokensMin = (raw: string | number | null | undefined) => {
-  if (!editable.value || !config.value) return;
-  const num = parseOptionalNumber(raw);
-  const current = config.value.chat?.reasoning?.budget_tokens ?? {};
-  const next = { ...current };
-  if (num === undefined) delete next.min; else next.min = num;
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ budget_tokens: next }) }) });
-};
-
-const updateBudgetTokensMax = (raw: string | number | null | undefined) => {
-  if (!editable.value || !config.value) return;
-  const num = parseOptionalNumber(raw);
-  const current = config.value.chat?.reasoning?.budget_tokens ?? {};
-  const next = { ...current };
-  if (num === undefined) delete next.max; else next.max = num;
-  patch({ chat: buildNextChat({ reasoning: buildNextReasoning({ budget_tokens: next }) }) });
-};
-
-// ── Adaptive / Mandatory toggles ───────────────────────────────────────────
-
-const toggleAdaptive = (on: boolean) => {
-  if (!editable.value) return;
-  const reasoning = on
-    ? buildNextReasoning({ adaptive: true })
-    : buildNextReasoning({ adaptive: undefined });
-  patch({ chat: buildNextChat({ reasoning }) });
-};
-
-const toggleMandatory = (on: boolean) => {
-  if (!editable.value) return;
-  const reasoning = on
-    ? buildNextReasoning({ mandatory: true })
-    : buildNextReasoning({ mandatory: undefined });
-  patch({ chat: buildNextChat({ reasoning }) });
-};
 </script>
 
 <template>
@@ -608,47 +382,13 @@ const toggleMandatory = (on: boolean) => {
           />
         </section>
 
-        <section v-if="rowKind === 'chat'">
-          <div class="mb-3 flex items-baseline gap-3">
-            <h3 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Context Limits</h3>
-            <span class="text-[11px] text-gray-500">tokens — leave blank to inherit upstream defaults</span>
-          </div>
-          <div class="grid gap-3 sm:grid-cols-3">
-            <label class="block space-y-1.5">
-              <span class="block text-xs font-medium text-gray-500">Context Window</span>
-              <Input
-                type="number"
-                :model-value="config.limits?.max_context_window_tokens"
-                :readonly="!editable"
-                placeholder="e.g. 1050000"
-                class="font-mono"
-                @update:model-value="v => updateLimit('max_context_window_tokens', v)"
-              />
-            </label>
-            <label class="block space-y-1.5">
-              <span class="block text-xs font-medium text-gray-500">Prompt Tokens</span>
-              <Input
-                type="number"
-                :model-value="config.limits?.max_prompt_tokens"
-                :readonly="!editable"
-                placeholder="e.g. 922000"
-                class="font-mono"
-                @update:model-value="v => updateLimit('max_prompt_tokens', v)"
-              />
-            </label>
-            <label class="block space-y-1.5">
-              <span class="block text-xs font-medium text-gray-500">Output Tokens</span>
-              <Input
-                type="number"
-                :model-value="config.limits?.max_output_tokens"
-                :readonly="!editable"
-                placeholder="e.g. 128000"
-                class="font-mono"
-                @update:model-value="v => updateLimit('max_output_tokens', v)"
-              />
-            </label>
-          </div>
-        </section>
+        <ChatMetadataEditor
+          v-if="rowKind !== 'image'"
+          :model-value="chatMetadataValue"
+          :kind="rowKind"
+          :mode="editable ? 'manual' : 'auto'"
+          @update:model-value="onChatMetadataChange"
+        />
 
         <section>
           <div class="mb-3 flex items-baseline gap-3">
@@ -786,147 +526,6 @@ const toggleMandatory = (on: boolean) => {
           </div>
         </section>
 
-        <section v-if="rowKind === 'chat'">
-          <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
-            <h3 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Modalities</h3>
-            <label class="flex items-center gap-2" :class="editable ? 'cursor-pointer' : 'cursor-not-allowed'">
-              <Switch
-                :model-value="chatImageInput"
-                :disabled="!editable"
-                @update:model-value="v => toggleImageInput(v === true)"
-              />
-              <span class="text-xs" :class="chatImageInput ? 'text-white' : 'text-gray-500'">Image input</span>
-            </label>
-          </div>
-        </section>
-
-        <section v-if="rowKind === 'chat'">
-          <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
-            <h3 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Reasoning</h3>
-            <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
-              <Switch :model-value="effortEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleEffort(v === true)" />
-              <span class="text-xs" :class="effortEnabled ? 'text-white' : 'text-gray-500'">Effort levels</span>
-            </label>
-            <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
-              <Switch :model-value="budgetTokensEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleBudgetTokens(v === true)" />
-              <span class="text-xs" :class="budgetTokensEnabled ? 'text-white' : 'text-gray-500'">Budget tokens</span>
-            </label>
-            <label class="flex items-center gap-2" :class="controlledDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
-              <Switch :model-value="adaptiveEnabled" :disabled="controlledDisabled" @update:model-value="v => toggleAdaptive(v === true)" />
-              <span class="text-xs" :class="adaptiveEnabled ? 'text-white' : 'text-gray-500'">Adaptive</span>
-              <Tooltip content="Model self-selects reasoning effort"><span class="text-[10px] text-gray-600">?</span></Tooltip>
-            </label>
-            <label class="flex items-center gap-2" :class="mandatoryDisabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer'">
-              <Switch :model-value="mandatoryEnabled" :disabled="mandatoryDisabled" @update:model-value="v => toggleMandatory(v === true)" />
-              <span class="text-xs" :class="mandatoryEnabled ? 'text-white' : 'text-gray-500'">Mandatory</span>
-              <Tooltip content="Reasoning is always applied; caller cannot opt out"><span class="text-[10px] text-gray-600">?</span></Tooltip>
-            </label>
-          </div>
-
-          <div v-if="effortEnabled" class="mt-3 space-y-1.5 border-l-2 border-white/[0.08] pl-3">
-            <div class="flex min-h-[1.625rem] flex-wrap items-center gap-x-3 gap-y-1.5">
-              <span class="text-xs font-semibold text-gray-300">Effort levels</span>
-              <span class="text-[11px] text-gray-500">(click to set default)</span>
-              <template v-if="supportedEfforts.length > 0">
-                <button
-                  v-for="(level, index) in supportedEfforts"
-                  :key="level"
-                  type="button"
-                  class="inline-flex items-center gap-1 rounded border px-2 py-0.5 font-mono text-[11px] transition-colors"
-                  :class="[
-                    config.chat?.reasoning?.effort?.default === level
-                      ? 'border-accent-cyan/50 bg-accent-cyan/10 text-accent-cyan font-semibold'
-                      : 'border-white/15 bg-white/[0.07] text-gray-300 hover:border-white/30 hover:text-white',
-                    editable ? 'cursor-grab active:cursor-grabbing' : 'cursor-not-allowed',
-                    draggedEffortIndex === index && 'opacity-40',
-                    dragOverEffortIndex === index && draggedEffortIndex !== index && 'ring-1 ring-accent-cyan',
-                  ]"
-                  :disabled="!editable"
-                  :draggable="editable"
-                  :title="config.chat?.reasoning?.effort?.default === level ? 'Default — click another to switch, drag to reorder' : 'Click to set as default, drag to reorder'"
-                  @click="setDefaultEffort(level)"
-                  @dragstart="e => onEffortDragStart(index, e)"
-                  @dragover="e => onEffortDragOver(index, e)"
-                  @dragleave="onEffortDragLeave(index)"
-                  @drop="e => onEffortDrop(index, e)"
-                  @dragend="onEffortDragEnd"
-                >
-                  {{ level }}
-                  <span
-                    v-if="editable"
-                    role="button"
-                    tabindex="0"
-                    class="ml-0.5 cursor-pointer text-gray-500 transition-colors hover:text-accent-rose"
-                    :aria-label="`Remove ${level}`"
-                    @click.stop="removeReasoningLevel(level)"
-                    @keydown.enter.stop.prevent="removeReasoningLevel(level)"
-                  >
-                    <svg class="h-2.5 w-2.5" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2">
-                      <path d="M9 3 3 9M3 3l6 6" />
-                    </svg>
-                  </span>
-                </button>
-              </template>
-              <p v-else class="whitespace-nowrap text-[11px] text-accent-amber">Add at least one effort level — click a preset on the right.</p>
-            </div>
-            <div v-if="editable" class="flex flex-wrap items-center gap-1.5">
-              <button
-                v-for="level in presetEffortLevels"
-                :key="level"
-                type="button"
-                class="rounded border border-white/15 px-2 py-0.5 font-mono text-[11px] text-gray-400 transition-colors hover:border-accent-cyan/40 hover:text-accent-cyan"
-                @click="addReasoningLevel(level)"
-              >+ {{ level }}</button>
-              <Input
-                v-model="reasoningLevelInput"
-                size="sm"
-                placeholder="custom…"
-                class="!h-6 !w-28 !py-0 !text-[11px] font-mono"
-                @keydown.enter.prevent="commitReasoningInput"
-              />
-              <Button variant="secondary" size="sm" class="!h-6 !px-2 !py-0 !text-[11px]" @click="commitReasoningInput">Add</Button>
-            </div>
-          </div>
-
-          <div v-if="budgetTokensEnabled" class="mt-3 flex flex-wrap items-center gap-3 border-l-2 border-white/[0.08] pl-3">
-            <span class="text-xs font-semibold text-gray-300">Budget tokens</span>
-            <label class="flex items-center gap-1.5">
-              <span class="text-[11px] text-gray-500">Min</span>
-              <Input
-                type="number"
-                min="0"
-                size="sm"
-                :model-value="config.chat?.reasoning?.budget_tokens?.min"
-                :readonly="!editable"
-                placeholder="—"
-                class="!h-6 !w-24 !py-0 !text-[11px] font-mono"
-                @update:model-value="v => updateBudgetTokensMin(v)"
-              />
-            </label>
-            <label class="flex items-center gap-1.5">
-              <span class="text-[11px] text-gray-500">Max</span>
-              <Input
-                type="number"
-                min="0"
-                size="sm"
-                :model-value="config.chat?.reasoning?.budget_tokens?.max"
-                :readonly="!editable"
-                placeholder="—"
-                class="!h-6 !w-24 !py-0 !text-[11px] font-mono"
-                @update:model-value="v => updateBudgetTokensMax(v)"
-              />
-            </label>
-            <p
-              v-if="config.chat?.reasoning?.budget_tokens?.min !== undefined
-                && config.chat?.reasoning?.budget_tokens?.max !== undefined
-                && config.chat.reasoning.budget_tokens.max < config.chat.reasoning.budget_tokens.min"
-              class="text-[11px] text-accent-amber"
-            >
-              Max must be ≥ min.
-            </p>
-          </div>
-        </section>
-
         <section>
           <div class="mb-3 flex items-baseline gap-3">
             <h3 class="text-[11px] font-semibold uppercase tracking-wider text-gray-500">Override Feature Flags</h3>
diff --git a/apps/web/src/composables/useModelAliases.ts b/apps/web/src/composables/useModelAliases.ts
new file mode 100644
index 000000000..020f226de
--- /dev/null
+++ b/apps/web/src/composables/useModelAliases.ts
@@ -0,0 +1,28 @@
+import { ref, shallowRef } from 'vue';
+
+import { callApi, useApi } from '../api/client.ts';
+import type { ModelAlias } from '../api/types.ts';
+
+// Module-scoped cache so concurrent callers share one fetch and edits in
+// the Settings card reflect on the Models page without a reload.
+const aliases = shallowRef<ModelAlias[] | null>(null);
+const loading = ref(false);
+const error = ref<string | null>(null);
+
+export const useModelAliases = () => {
+  const api = useApi();
+
+  const load = async () => {
+    loading.value = true;
+    error.value = null;
+    const { data, error: err } = await callApi<ModelAlias[]>(() => api.api.aliases.$get());
+    loading.value = false;
+    if (err) {
+      error.value = err.message;
+      return;
+    }
+    aliases.value = data;
+  };
+
+  return { aliases, loading, error, load };
+};
diff --git a/apps/web/src/composables/useModels.ts b/apps/web/src/composables/useModels.ts
index 002506ccf..d665994c3 100644
--- a/apps/web/src/composables/useModels.ts
+++ b/apps/web/src/composables/useModels.ts
@@ -3,29 +3,45 @@ import { ref } from 'vue';
 import { callApi, useApi } from '../api/client.ts';
 import type { ControlPlaneModel } from '../api/types.ts';
 
-const models = ref<ControlPlaneModel[] | null>(null);
-const loading = ref(false);
-const error = ref<string | null>(null);
-
 interface ModelsResponse {
   object: string;
   data: ControlPlaneModel[];
 }
 
-export const useModelsStore = () => {
-  const api = useApi();
+// Two stores share this core. The server returns gateway-wide rows for
+// admin sessions and scoped rows for non-admin sessions, so every surface
+// that mounts under `requiresAdmin` (alias edit dialog, settings card,
+// Models playground) gets the full catalog and filters client-side as
+// needed. `useModelsStore` includes synthesised alias entries (the
+// default `/v1/models` view); `useRawModelsStore` drops alias merging
+// and adds `include_unlisted=true` so the alias editor's combobox sees
+// every id the data-plane resolver would accept.
+const makeStore = (params: { includeAliases: boolean; includeUnlisted?: boolean }) => {
+  const models = ref<ControlPlaneModel[] | null>(null);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
 
-  const load = async () => {
-    loading.value = true;
-    error.value = null;
-    const { data, error: err } = await callApi<ModelsResponse>(() => api.api.models.$get());
-    loading.value = false;
-    if (err) {
-      error.value = err.message;
-      return;
-    }
-    models.value = data?.data ?? [];
-  };
+  return () => {
+    const api = useApi();
+
+    const load = async () => {
+      loading.value = true;
+      error.value = null;
+      const query: { aliases?: 'false'; include_unlisted?: 'true' } = {};
+      if (!params.includeAliases) query.aliases = 'false';
+      if (params.includeUnlisted) query.include_unlisted = 'true';
+      const { data, error: err } = await callApi<ModelsResponse>(() => api.api.models.$get({ query }));
+      loading.value = false;
+      if (err) {
+        error.value = err.message;
+        return;
+      }
+      models.value = data?.data ?? [];
+    };
 
-  return { models, loading, error, load };
+    return { models, loading, error, load };
+  };
 };
+
+export const useModelsStore = makeStore({ includeAliases: true });
+export const useRawModelsStore = makeStore({ includeAliases: false, includeUnlisted: true });
diff --git a/apps/web/src/pages/dashboard/models.vue b/apps/web/src/pages/dashboard/models.vue
index ff1954efa..fbaa848a3 100644
--- a/apps/web/src/pages/dashboard/models.vue
+++ b/apps/web/src/pages/dashboard/models.vue
@@ -7,6 +7,8 @@ import type { ApiKey, ControlPlaneModel } from '../../api/types.ts';
 import ChatPanel from '../../components/models/ChatPanel.vue';
 import ModelInfoBar from '../../components/models/ModelInfoBar.vue';
 import { useModelsStore } from '../../composables/useModels.ts';
+import { useAuthStore } from '../../stores/auth.ts';
+import { effectiveUpstreamCap, isReachableUnderCap } from '../../utils/reachability.ts';
 import { Input, OverlayScrollbars } from '@floway-dev/ui';
 
 export const useModelsPageData = defineBasicLoader(async () => {
@@ -22,6 +24,7 @@ export const useModelsPageData = defineBasicLoader(async () => {
 <script setup lang="ts">
 const initialData = useModelsPageData();
 const { models, error: modelsError } = useModelsStore();
+const auth = useAuthStore();
 
 // Reactivity is intentionally dropped: the loader never refetches keys here.
 const keys = initialData.data.value.keys;
@@ -30,11 +33,32 @@ const modelsSearch = ref('');
 const chatModelId = ref<string>('');
 const chatPanelRef = useTemplateRef<InstanceType<typeof ChatPanel>>('chatPanel');
 
+// Playground requires a real per-user API key, not the admin key.
+const selectedKeyId = ref<string | null>(keys[0]?.id ?? null);
+
+const selectedKey = computed<ApiKey | null>(() => {
+  const id = selectedKeyId.value;
+  if (!id) return null;
+  return keys.find(k => k.id === id) ?? null;
+});
+
+const selectedApiKey = computed(() => selectedKey.value?.key ?? null);
+
+// Server returns gateway-wide for admin sessions, so we filter client-side
+// here by the effective cap of (selected api key, owner user). Mirrors the
+// gateway's `effectiveUpstreamIdsFromContext`: the key's whitelist wins
+// when set; otherwise the user's cap applies. Without a selected key (no
+// keys created yet) the cap collapses to the admin's own user.upstreamIds.
+const effectiveCap = computed<readonly string[] | null>(
+  () => effectiveUpstreamCap(selectedKey.value?.upstream_ids ?? null, auth.currentUser?.upstreamIds ?? null),
+);
+
 const filteredChatModels = computed(() => {
-  const list = (models.value ?? []).filter(m => m.kind === 'chat');
+  const catalog = models.value ?? [];
+  const reachable = catalog.filter(m => m.kind === 'chat' && isReachableUnderCap(m, catalog, effectiveCap.value));
   const needle = modelsSearch.value.trim().toLowerCase();
-  if (!needle) return list;
-  return list.filter(m => m.id.toLowerCase().includes(needle) || (m.display_name?.toLowerCase().includes(needle) ?? false));
+  if (!needle) return reachable;
+  return reachable.filter(m => m.id.toLowerCase().includes(needle) || (m.display_name?.toLowerCase().includes(needle) ?? false));
 });
 
 const chatModelInfo = computed<ControlPlaneModel | undefined>(
@@ -43,15 +67,6 @@ const chatModelInfo = computed<ControlPlaneModel | undefined>(
 
 if (!chatModelId.value && filteredChatModels.value[0]) chatModelId.value = filteredChatModels.value[0].id;
 
-// Playground requires a real per-user API key, not the admin key.
-const selectedKeyId = ref<string | null>(keys[0]?.id ?? null);
-
-const selectedApiKey = computed(() => {
-  const id = selectedKeyId.value;
-  if (!id) return null;
-  return keys.find(k => k.id === id)!.key;
-});
-
 const banner = computed(() => modelsError.value ?? initialData.data.value.keysError);
 </script>
 
@@ -113,7 +128,7 @@ const banner = computed(() => modelsError.value ?? initialData.data.value.keysEr
 
       <div class="flex-1 flex flex-col min-w-0 min-h-0">
         <template v-if="chatModelInfo">
-          <ModelInfoBar :model="chatModelInfo" @clear="chatPanelRef?.clear()" />
+          <ModelInfoBar :model="chatModelInfo" :catalog="models ?? []" :cap="effectiveCap" @clear="chatPanelRef?.clear()" />
           <ChatPanel v-if="selectedApiKey" ref="chatPanel" :model-id="chatModelInfo.id" :api-key="selectedApiKey" />
           <div v-else class="flex-1 flex items-center justify-center px-6 text-center text-gray-600 text-sm">
             Create an API key in the Keys tab to chat with models.
diff --git a/apps/web/src/pages/dashboard/settings.vue b/apps/web/src/pages/dashboard/settings.vue
index 83fedc993..3b5321c81 100644
--- a/apps/web/src/pages/dashboard/settings.vue
+++ b/apps/web/src/pages/dashboard/settings.vue
@@ -4,15 +4,18 @@ import { ref, watch } from 'vue';
 import { useRouter } from 'vue-router';
 
 import { callApi, useApi } from '../../api/client.ts';
-import type { ProxyRecord, SearchConfig, UpstreamProviderKind, UpstreamRecord } from '../../api/types.ts';
+import type { ModelAlias, ProxyRecord, SearchConfig, UpstreamProviderKind, UpstreamRecord } from '../../api/types.ts';
+import AliasEditDialog from '../../components/alias-edit/AliasEditDialog.vue';
 import ProxyEditDialog from '../../components/proxy-edit/ProxyEditDialog.vue';
+import AliasesSettingsCard from '../../components/settings/AliasesSettingsCard.vue';
 import ApiEndpointsSection from '../../components/settings/ApiEndpointsSection.vue';
 import ExportSection from '../../components/settings/ExportSection.vue';
 import ImportSection from '../../components/settings/ImportSection.vue';
 import ProxiesSettingsCard from '../../components/settings/ProxiesSettingsCard.vue';
 import SearchConfigSection from '../../components/settings/SearchConfigSection.vue';
 import UpstreamsSettingsCard from '../../components/settings/UpstreamsSettingsCard.vue';
-import { useModelsStore } from '../../composables/useModels.ts';
+import { useModelAliases } from '../../composables/useModelAliases.ts';
+import { useRawModelsStore } from '../../composables/useModels.ts';
 import { useProxiesStore } from '../../composables/useProxies.ts';
 import { useRuntimeInfo } from '../../composables/useRuntimeInfo.ts';
 import { useUpstreamsStore } from '../../composables/useUpstreams.ts';
@@ -29,8 +32,9 @@ export const useSettingsPageData = defineBasicLoader(async () => {
   const [searchRes] = await Promise.all([
     callApi<SearchConfig>(() => api.api['search-config'].$get()),
     useUpstreamsStore().load(),
-    useModelsStore().load(),
+    useRawModelsStore().load(),
     useProxiesStore().load(),
+    useModelAliases().load(),
     useRuntimeInfo().load(),
   ]);
   return {
@@ -46,9 +50,11 @@ definePage({ meta: { requiresAdmin: true } });
 
 const router = useRouter();
 const { upstreams, loading: storeLoading, load } = useUpstreamsStore();
-const modelsStore = useModelsStore();
+const modelsStore = useRawModelsStore();
 const proxiesStore = useProxiesStore();
+const aliasesStore = useModelAliases();
 const { load: loadProxies } = proxiesStore;
+const { load: loadAliases } = aliasesStore;
 const settingsData = useSettingsPageData();
 
 // Local working copy the child reorders via v-model:ordered; reloadAll
@@ -59,17 +65,24 @@ watch(upstreams, list => {
 }, { immediate: true });
 
 const reloadAll = async () => {
-  await Promise.all([load(), modelsStore.load(), loadProxies()]);
+  await Promise.all([load(), modelsStore.load(), loadProxies(), loadAliases()]);
 };
 
-// Proxy editor is hosted as a modal — v-if drives the unmount on close
-// so the next open boots from a fresh script setup (no manual reset).
+// Proxy editor is hosted as a modal — v-if drives the unmount on close so the
+// next open boots from a fresh script setup (no manual reset).
 const proxyDialogOpen = ref(false);
 const proxyDialogRecord = ref<ProxyRecord | null>(null);
 const openProxyDialog = (record: ProxyRecord | null): void => {
   proxyDialogRecord.value = record;
   proxyDialogOpen.value = true;
 };
+
+const aliasDialogOpen = ref(false);
+const aliasDialogRecord = ref<ModelAlias | null>(null);
+const openAliasDialog = (record: ModelAlias | null): void => {
+  aliasDialogRecord.value = record;
+  aliasDialogOpen.value = true;
+};
 </script>
 
 <template>
@@ -89,6 +102,11 @@ const openProxyDialog = (record: ProxyRecord | null): void => {
           @edit="(record: ProxyRecord) => openProxyDialog(record)"
           @changed="reloadAll"
         />
+        <AliasesSettingsCard
+          @add="() => openAliasDialog(null)"
+          @edit="(record: ModelAlias) => openAliasDialog(record)"
+          @changed="reloadAll"
+        />
         <SearchConfigSection
           :initial-config="settingsData.data.value.searchConfig"
           :initial-error="settingsData.data.value.searchConfigError"
@@ -111,5 +129,12 @@ const openProxyDialog = (record: ProxyRecord | null): void => {
       :record="proxyDialogRecord"
       @saved="reloadAll"
     />
+
+    <AliasEditDialog
+      v-if="aliasDialogOpen"
+      v-model:open="aliasDialogOpen"
+      :record="aliasDialogRecord"
+      @saved="reloadAll"
+    />
   </div>
 </template>
diff --git a/apps/web/src/utils/parse-optional-number.ts b/apps/web/src/utils/parse-optional-number.ts
new file mode 100644
index 000000000..25eae2811
--- /dev/null
+++ b/apps/web/src/utils/parse-optional-number.ts
@@ -0,0 +1,12 @@
+// Form-input parser shared by the chat-metadata and model editors. Both
+// editors feed nonnegative integer counts (token caps, budget bounds,
+// pricing factors); the backend validators reject negatives, so the form
+// boundary drops them before staging data the next PUT would 400 on.
+// Blank input, null, and undefined all collapse to `undefined` — the
+// "leave blank to inherit" semantic the editors render for optional
+// fields.
+export const parseOptionalNumber = (raw: string | number | null | undefined): number | undefined => {
+  if (raw === '' || raw === null || raw === undefined) return undefined;
+  const num = Number(raw);
+  return Number.isFinite(num) && num >= 0 ? num : undefined;
+};
diff --git a/apps/web/src/utils/reachability.ts b/apps/web/src/utils/reachability.ts
new file mode 100644
index 000000000..17924418d
--- /dev/null
+++ b/apps/web/src/utils/reachability.ts
@@ -0,0 +1,67 @@
+// Frontend reachability check: given a `ControlPlaneModel` row and the
+// catalog it lives in, decide whether the caller can route to it under an
+// upstream-id cap. The server always returns the gateway-wide catalog for
+// admin sessions (and the caller-scoped catalog for non-admin); the
+// dashboard's Models page + playground then filter client-side by the
+// effective cap of the selected api key (which itself inherits from the
+// owner user's `upstreamIds` when the key has no whitelist of its own).
+//
+// `cap === null` means "no restriction" (every upstream is reachable).
+// `cap` is a freshly-resolved array of upstream ids the caller is allowed
+// to route to right now.
+
+import type { ControlPlaneModel } from '../api/types.ts';
+
+// Resolve the effective per-request cap. Mirrors the gateway's
+// `effectiveUpstreamIdsFromContext`: the api key's `upstream_ids` win when
+// set; otherwise the cap falls back to the owner user's `upstreamIds`.
+// Both null means unrestricted.
+export const effectiveUpstreamCap = (
+  keyUpstreamIds: readonly string[] | null,
+  userUpstreamIds: readonly string[] | null,
+): readonly string[] | null => keyUpstreamIds ?? userUpstreamIds;
+
+// True when any of the model's upstream bindings is in the cap (or the
+// cap is unrestricted). For an alias row this is always false — the
+// alias's bindings list is empty and reachability runs through its
+// targets instead.
+const realModelReachable = (
+  model: ControlPlaneModel,
+  cap: readonly string[] | null,
+): boolean => {
+  if (cap === null) return true;
+  return model.upstreams.some(binding => cap.includes(binding.id));
+};
+
+// Returns whether the alias has at least one configured target whose
+// resolved real model is reachable under the cap. A target whose
+// `target_model_id` does not appear in the catalog at all (e.g. operator
+// typo, model removed) is treated as unreachable. Addressable-but-not-
+// listed entries (Copilot variant ids, prefix alternates) carry their
+// canonical real model's `upstreams`, so they count as reachable through
+// the same predicate.
+export const reachableTargets = (
+  alias: ControlPlaneModel,
+  catalog: readonly ControlPlaneModel[],
+  cap: readonly string[] | null,
+): readonly ControlPlaneModel[] => {
+  if (alias.aliasedFrom === undefined) return [];
+  const out: ControlPlaneModel[] = [];
+  for (const t of alias.aliasedFrom.targets) {
+    const target = catalog.find(row => row.id === t.target_model_id && row.aliasedFrom === undefined);
+    if (target && realModelReachable(target, cap)) out.push(target);
+  }
+  return out;
+};
+
+// True for a real model with at least one in-cap binding; true for an
+// alias with at least one reachable target. Hides a row from a listing
+// when the caller would 404 on it.
+export const isReachableUnderCap = (
+  model: ControlPlaneModel,
+  catalog: readonly ControlPlaneModel[],
+  cap: readonly string[] | null,
+): boolean => {
+  if (model.aliasedFrom === undefined) return realModelReachable(model, cap);
+  return reachableTargets(model, catalog, cap).length > 0;
+};
diff --git a/apps/web/src/utils/reachability_test.ts b/apps/web/src/utils/reachability_test.ts
new file mode 100644
index 000000000..bf1bac2a4
--- /dev/null
+++ b/apps/web/src/utils/reachability_test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+
+import { effectiveUpstreamCap, isReachableUnderCap, reachableTargets } from './reachability.ts';
+import { buildAliasModel, buildRealModel, buildUnlistedModel } from '../api/test-fixtures.ts';
+import type { ControlPlaneModel } from '../api/types.ts';
+
+const realWithUpstreams = (id: string, upstreams: { id: string }[]): ControlPlaneModel => buildRealModel({
+  id,
+  upstreams: upstreams.map(u => ({ id: u.id, name: u.id.toUpperCase(), kind: 'custom' })),
+});
+
+const aliasWithTargets = (id: string, targetIds: string[]): ControlPlaneModel => buildAliasModel({
+  id,
+  aliasedFrom: {
+    name: id, kind: 'chat', selection: 'first-available',
+    targets: targetIds.map(tid => ({ target_model_id: tid, rules: {} })),
+  },
+});
+
+describe('effectiveUpstreamCap', () => {
+  it('prefers the api key cap when set', () => {
+    expect(effectiveUpstreamCap(['up_a'], ['up_a', 'up_b'])).toEqual(['up_a']);
+  });
+
+  it('falls back to the user cap when the key has no whitelist', () => {
+    expect(effectiveUpstreamCap(null, ['up_a', 'up_b'])).toEqual(['up_a', 'up_b']);
+  });
+
+  it('returns null (unrestricted) when both are null', () => {
+    expect(effectiveUpstreamCap(null, null)).toBeNull();
+  });
+});
+
+describe('isReachableUnderCap — real models', () => {
+  const a = realWithUpstreams('a', [{ id: 'up_1' }]);
+
+  it('returns true when the cap is null', () => {
+    expect(isReachableUnderCap(a, [a], null)).toBe(true);
+  });
+
+  it('returns true when any binding is in the cap', () => {
+    expect(isReachableUnderCap(a, [a], ['up_1', 'up_2'])).toBe(true);
+  });
+
+  it('returns false when no binding is in the cap', () => {
+    expect(isReachableUnderCap(a, [a], ['up_2'])).toBe(false);
+  });
+});
+
+describe('isReachableUnderCap — aliases', () => {
+  it('returns true when at least one target is reachable', () => {
+    const target = realWithUpstreams('gpt-5', [{ id: 'up_1' }]);
+    const otherTarget = realWithUpstreams('claude', [{ id: 'up_2' }]);
+    const alias = aliasWithTargets('smart', ['gpt-5', 'claude']);
+    const catalog = [target, otherTarget, alias];
+    expect(isReachableUnderCap(alias, catalog, ['up_1'])).toBe(true);
+  });
+
+  it('returns false when every target is out of cap', () => {
+    const target = realWithUpstreams('gpt-5', [{ id: 'up_1' }]);
+    const alias = aliasWithTargets('smart', ['gpt-5']);
+    expect(isReachableUnderCap(alias, [target, alias], ['up_2'])).toBe(false);
+  });
+
+  it('returns false when the alias has no targets at all', () => {
+    const alias = aliasWithTargets('orphan', []);
+    expect(isReachableUnderCap(alias, [alias], ['up_1'])).toBe(false);
+  });
+
+  it('drops a target whose id resolves to no real-model row in the catalog', () => {
+    // Operator typo or removed model — the resolver would 404 at request
+    // time, the frontend filter treats the same way.
+    const alias = aliasWithTargets('smart', ['missing']);
+    expect(isReachableUnderCap(alias, [alias], null)).toBe(false);
+  });
+});
+
+describe('reachableTargets', () => {
+  it('returns every target whose real-model row is in cap', () => {
+    const gpt = realWithUpstreams('gpt-5', [{ id: 'up_1' }]);
+    const claude = realWithUpstreams('claude', [{ id: 'up_2' }]);
+    const alias = aliasWithTargets('smart', ['gpt-5', 'claude']);
+    const reachable = reachableTargets(alias, [gpt, claude, alias], ['up_1']);
+    expect(reachable.map(m => m.id)).toEqual(['gpt-5']);
+  });
+
+  it('matches addressable-but-not-listed entries against the real-model surface', () => {
+    // `buildUnlistedModel` carries `aliasedFrom === undefined` (it represents
+    // a real model's variant id), so the alias's target_model_id pointing
+    // at the variant id still matches the real-model lookup.
+    const opus = buildUnlistedModel({
+      id: 'claude-opus-4.7',
+      upstreams: [{ id: 'up_1', name: 'UP1', kind: 'copilot' }],
+    });
+    const alias = aliasWithTargets('opus-fast', ['claude-opus-4.7']);
+    const reachable = reachableTargets(alias, [opus, alias], ['up_1']);
+    expect(reachable.map(m => m.id)).toEqual(['claude-opus-4.7']);
+  });
+
+  it('returns empty for a non-alias row', () => {
+    const a = realWithUpstreams('a', [{ id: 'up_1' }]);
+    expect(reachableTargets(a, [a], null)).toEqual([]);
+  });
+});
diff --git a/apps/web/vitest.config.ts b/apps/web/vitest.config.ts
index 4b522bfd9..4f478ad04 100644
--- a/apps/web/vitest.config.ts
+++ b/apps/web/vitest.config.ts
@@ -1,6 +1,11 @@
+import Vue from '@vitejs/plugin-vue';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+  // The Vue plugin is required for any test that mounts an SFC; logic-only
+  // tests don't need it, but adding it here is cheap and lets component
+  // tests live next to the rest.
+  plugins: [Vue()],
   test: {
     // happy-dom provides DOM + EventSource for the dump-subscription
     // composable's tests. Node-env worked while the composable accepted
diff --git a/packages/gateway/migrations/0046_model_aliases.sql b/packages/gateway/migrations/0046_model_aliases.sql
new file mode 100644
index 000000000..fea35c093
--- /dev/null
+++ b/packages/gateway/migrations/0046_model_aliases.sql
@@ -0,0 +1,42 @@
+CREATE TABLE model_aliases (
+  name TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('chat', 'embedding', 'image')),
+  selection TEXT NOT NULL CHECK (selection IN ('random', 'first-available')),
+  display_name TEXT,
+  visible_in_models_list INTEGER NOT NULL DEFAULT 1 CHECK (visible_in_models_list IN (0, 1)),
+  targets TEXT NOT NULL,
+  -- Operator-set override for the `limits` + `chat.*` block surfaced on
+  -- /v1/models. NULL keeps the automatic, rule-aware intersection across
+  -- the alias's targets; a non-null value is a JSON-encoded
+  -- AnnouncedMetadata. Fallback is at the top-level sub-block boundary
+  -- (`limits` / `chat`), not per-leaf.
+  announced_metadata_json TEXT,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX idx_model_aliases_sort ON model_aliases (sort_order, created_at);
+
+INSERT INTO model_aliases (
+  name,
+  kind,
+  selection,
+  display_name,
+  visible_in_models_list,
+  targets,
+  sort_order,
+  created_at,
+  updated_at
+)
+VALUES (
+  'codex-auto-review',
+  'chat',
+  'first-available',
+  'Codex Auto Review',
+  1,
+  json('[{"target_model_id":"codex-auto-review","rules":{}},{"target_model_id":"gpt-5.4","rules":{"reasoning":{"effort":"low"}}}]'),
+  0,
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+  strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+);
diff --git a/packages/gateway/src/control-plane/model-aliases/repo_test.ts b/packages/gateway/src/control-plane/model-aliases/repo_test.ts
new file mode 100644
index 000000000..5bd380b95
--- /dev/null
+++ b/packages/gateway/src/control-plane/model-aliases/repo_test.ts
@@ -0,0 +1,170 @@
+// Cross-backend tests for the model aliases repo. Memory drives the unit
+// scenarios by default; the SQL backend (sql.js applying every migration)
+// catches schema drift, JSON-column round-trips, and rename atomicity.
+
+import { test } from 'vitest';
+
+import { InMemoryRepo } from '../../repo/memory.ts';
+import { SqlRepo } from '../../repo/sql.ts';
+import { createSqliteTestDb } from '../../repo/test-sqlite.ts';
+import type { ModelAliasRecord, Repo } from '../../repo/types.ts';
+import { assertEquals, assertExists, assertRejects } from '@floway-dev/test-utils';
+
+const REPO_BACKENDS: Array<readonly [string, () => Promise<Repo>]> = [
+  ['memory', async () => new InMemoryRepo()],
+  ['sql', async () => new SqlRepo(await createSqliteTestDb())],
+];
+
+const aliasFixture = (overrides: Partial<ModelAliasRecord> = {}): ModelAliasRecord => ({
+  name: 'gpt-fast',
+  kind: 'chat',
+  selection: 'first-available',
+  displayName: null,
+  visibleInModelsList: true,
+  targets: [
+    { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } },
+  ],
+  announcedMetadata: null,
+  sortOrder: 0,
+  createdAt: '2026-06-26T00:00:00.000Z',
+  updatedAt: '2026-06-26T00:00:00.000Z',
+  ...overrides,
+});
+
+for (const [backend, makeRepo] of REPO_BACKENDS) {
+  // The 0046 migration seeds `codex-auto-review`; every test starts from a
+  // known-empty state so assertions on row counts and ordering stay stable.
+  const freshRepo = async (): Promise<Repo> => {
+    const repo = await makeRepo();
+    await repo.modelAliases.deleteAll();
+    return repo;
+  };
+
+  test(`[${backend}] insert then list returns the row`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture());
+    const list = await repo.modelAliases.list();
+    assertEquals(list.length, 1);
+    assertEquals(list[0].name, 'gpt-fast');
+    assertEquals(list[0].targets[0].target_model_id, 'gpt-5.4');
+  });
+
+  test(`[${backend}] insert collision throws`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture());
+    await assertRejects(() => repo.modelAliases.insert(aliasFixture()));
+  });
+
+  test(`[${backend}] getByName returns null when no row matches`, async () => {
+    const repo = await freshRepo();
+    assertEquals(await repo.modelAliases.getByName('nope'), null);
+  });
+
+  test(`[${backend}] update with same name preserves createdAt and refreshes updatedAt`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z' }));
+    await repo.modelAliases.update('gpt-fast', aliasFixture({
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-06-26T12:00:00.000Z',
+      displayName: 'GPT Fast',
+    }));
+    const after = await repo.modelAliases.getByName('gpt-fast');
+    assertExists(after);
+    assertEquals(after.createdAt, '2026-01-01T00:00:00.000Z');
+    assertEquals(after.updatedAt, '2026-06-26T12:00:00.000Z');
+    assertEquals(after.displayName, 'GPT Fast');
+  });
+
+  test(`[${backend}] update with different name (rename) moves the row`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ createdAt: '2026-01-01T00:00:00.000Z' }));
+    await repo.modelAliases.update('gpt-fast', aliasFixture({
+      name: 'gpt-fastest',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-06-26T12:00:00.000Z',
+    }));
+    assertEquals(await repo.modelAliases.getByName('gpt-fast'), null);
+    const renamed = await repo.modelAliases.getByName('gpt-fastest');
+    assertExists(renamed);
+    assertEquals(renamed.createdAt, '2026-01-01T00:00:00.000Z');
+  });
+
+  test(`[${backend}] rename to an existing name throws and leaves both rows intact`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ name: 'gpt-fast' }));
+    await repo.modelAliases.insert(aliasFixture({ name: 'gpt-slow' }));
+    await assertRejects(() => repo.modelAliases.update('gpt-fast', aliasFixture({ name: 'gpt-slow' })));
+    assertExists(await repo.modelAliases.getByName('gpt-fast'));
+    assertExists(await repo.modelAliases.getByName('gpt-slow'));
+  });
+
+  test(`[${backend}] update on a missing name throws`, async () => {
+    const repo = await freshRepo();
+    await assertRejects(() => repo.modelAliases.update('nope', aliasFixture({ name: 'nope' })));
+  });
+
+  test(`[${backend}] delete returns true when present, false when absent`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture());
+    assertEquals(await repo.modelAliases.delete('gpt-fast'), true);
+    assertEquals(await repo.modelAliases.delete('gpt-fast'), false);
+  });
+
+  test(`[${backend}] list orders by (sortOrder, createdAt)`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ name: 'a', sortOrder: 1, createdAt: '2026-01-01T00:00:00.000Z' }));
+    await repo.modelAliases.insert(aliasFixture({ name: 'b', sortOrder: 0, createdAt: '2026-02-01T00:00:00.000Z' }));
+    await repo.modelAliases.insert(aliasFixture({ name: 'c', sortOrder: 0, createdAt: '2026-01-15T00:00:00.000Z' }));
+    const list = await repo.modelAliases.list();
+    assertEquals(list.map(r => r.name), ['c', 'b', 'a']);
+  });
+
+  test(`[${backend}] targets JSON round-trips multi-target chat rules`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({
+      name: 'multi',
+      targets: [
+        { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'high', adaptive: true } } },
+        { target_model_id: 'gpt-4.1', rules: { verbosity: 'low', serviceTier: 'priority' } },
+        { target_model_id: 'gpt-3.5', rules: {} },
+      ],
+    }));
+    const row = await repo.modelAliases.getByName('multi');
+    assertExists(row);
+    assertEquals(row.targets.length, 3);
+    assertEquals(row.targets[0].rules, { reasoning: { effort: 'high', adaptive: true } });
+    assertEquals(row.targets[1].rules, { verbosity: 'low', serviceTier: 'priority' });
+    assertEquals(row.targets[2].rules, {});
+  });
+
+  test(`[${backend}] visibleInModelsList=false round-trips`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ visibleInModelsList: false }));
+    const row = await repo.modelAliases.getByName('gpt-fast');
+    assertEquals(row?.visibleInModelsList, false);
+  });
+
+  test(`[${backend}] announcedMetadata round-trips through JSON column`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({
+      name: 'overridden',
+      announcedMetadata: {
+        limits: { max_output_tokens: 8192 },
+        chat: { modalities: { input: ['text'], output: ['text'] } },
+      },
+    }));
+    const row = await repo.modelAliases.getByName('overridden');
+    assertEquals(row?.announcedMetadata, {
+      limits: { max_output_tokens: 8192 },
+      chat: { modalities: { input: ['text'], output: ['text'] } },
+    });
+  });
+
+  test(`[${backend}] deleteAll wipes every row`, async () => {
+    const repo = await freshRepo();
+    await repo.modelAliases.insert(aliasFixture({ name: 'a' }));
+    await repo.modelAliases.insert(aliasFixture({ name: 'b' }));
+    await repo.modelAliases.deleteAll();
+    assertEquals((await repo.modelAliases.list()).length, 0);
+  });
+}
diff --git a/packages/gateway/src/control-plane/model-aliases/routes.ts b/packages/gateway/src/control-plane/model-aliases/routes.ts
new file mode 100644
index 000000000..e42fc0d46
--- /dev/null
+++ b/packages/gateway/src/control-plane/model-aliases/routes.ts
@@ -0,0 +1,71 @@
+// Admin-only CRUD for model aliases. Wire shape (snake_case) is in
+// `@floway-dev/protocols/common`; this layer maps to the camelCase
+// `ModelAliasRecord` the repo stores.
+
+import type { Context } from 'hono';
+
+import { recordToWire, wireToRecord } from './serialize.ts';
+import { type CtxWithJson } from '../../middleware/zod-validator.ts';
+import { getRepo } from '../../repo/index.ts';
+import type { ModelAliasRecord } from '../../repo/types.ts';
+import type { createAliasBody, updateAliasBody } from '../schemas.ts';
+
+const nextSortOrder = (existing: readonly ModelAliasRecord[]): number =>
+  existing.reduce((acc, record) => Math.max(acc, record.sortOrder), -1) + 1;
+
+export const listAliases = async (c: Context) => {
+  const records = await getRepo().modelAliases.list();
+  return c.json(records.map(recordToWire));
+};
+
+export const createAlias = async (c: CtxWithJson<typeof createAliasBody>) => {
+  const body = c.req.valid('json');
+  const repo = getRepo();
+
+  const collision = await repo.modelAliases.getByName(body.name);
+  if (collision) {
+    return c.json({ error: `Alias ${body.name} already exists` }, 409);
+  }
+
+  const existing = await repo.modelAliases.list();
+  const now = new Date().toISOString();
+  const record = wireToRecord(body, {
+    sortOrder: body.sort_order ?? nextSortOrder(existing),
+    createdAt: now,
+    updatedAt: now,
+  });
+  await repo.modelAliases.insert(record);
+  return c.json(recordToWire(record), 201);
+};
+
+export const updateAlias = async (c: CtxWithJson<typeof updateAliasBody>) => {
+  const oldName = c.req.param('name')!;
+  const body = c.req.valid('json');
+  const repo = getRepo();
+
+  const existing = await repo.modelAliases.getByName(oldName);
+  if (!existing) return c.json({ error: 'Alias not found' }, 404);
+
+  if (body.name !== oldName) {
+    const collision = await repo.modelAliases.getByName(body.name);
+    if (collision) return c.json({ error: `Alias ${body.name} already exists` }, 409);
+  }
+
+  const next = wireToRecord(body, {
+    // Preserve the original sortOrder unless the client explicitly overrides
+    // it; createdAt belongs to the row's first-seen instant and never moves.
+    sortOrder: body.sort_order ?? existing.sortOrder,
+    createdAt: existing.createdAt,
+    updatedAt: new Date().toISOString(),
+  });
+  await repo.modelAliases.update(oldName, next);
+  return c.json(recordToWire(next));
+};
+
+export const deleteAlias = async (c: Context) => {
+  const name = c.req.param('name')!;
+  // Idempotent — success whether or not a row existed. 204 keeps verb-shape
+  // parity with DELETE /api/proxies/:id.
+  await getRepo().modelAliases.delete(name);
+  return c.body(null, 204);
+};
diff --git a/packages/gateway/src/control-plane/model-aliases/routes_test.ts b/packages/gateway/src/control-plane/model-aliases/routes_test.ts
new file mode 100644
index 000000000..9122344eb
--- /dev/null
+++ b/packages/gateway/src/control-plane/model-aliases/routes_test.ts
@@ -0,0 +1,216 @@
+import { test } from 'vitest';
+
+import { requestApp, setupAppTest } from '../../test-helpers.ts';
+import type { ModelAlias } from '@floway-dev/protocols/common';
+import { assertEquals, assertExists } from '@floway-dev/test-utils';
+
+const authed = (adminSession: string, body?: unknown, method?: string): RequestInit => ({
+  method: method ?? (body === undefined ? 'GET' : 'POST'),
+  headers: {
+    'content-type': 'application/json',
+    'x-floway-session': adminSession,
+  },
+  ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+});
+
+const putAuthed = (adminSession: string, body: unknown): RequestInit => authed(adminSession, body, 'PUT');
+const deleteAuthed = (adminSession: string): RequestInit => ({
+  method: 'DELETE',
+  headers: { 'x-floway-session': adminSession },
+});
+
+const baseBody = (overrides: Record<string, unknown> = {}) => ({
+  name: 'gpt-fast',
+  kind: 'chat',
+  selection: 'first-available',
+  display_name: null,
+  visible_in_models_list: true,
+  targets: [
+    { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } },
+  ],
+  announced_metadata: null,
+  ...overrides,
+});
+
+test('GET /api/aliases lists every row in sort order', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await repo.modelAliases.insert({
+    name: 'b', kind: 'chat', selection: 'random', displayName: null, visibleInModelsList: true,
+    targets: [{ target_model_id: 'm1', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 1, createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
+  });
+  await repo.modelAliases.insert({
+    name: 'a', kind: 'chat', selection: 'random', displayName: null, visibleInModelsList: true,
+    targets: [{ target_model_id: 'm2', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 0, createdAt: '2026-01-02T00:00:00.000Z', updatedAt: '2026-01-02T00:00:00.000Z',
+  });
+
+  const resp = await requestApp('/api/aliases', authed(adminSession));
+  assertEquals(resp.status, 200);
+  const list = (await resp.json()) as ModelAlias[];
+  assertEquals(list.map(r => r.name), ['a', 'b']);
+});
+
+test('POST /api/aliases creates an alias and returns the snake_case wire shape', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp('/api/aliases', authed(adminSession, baseBody()));
+  assertEquals(resp.status, 201);
+  const created = (await resp.json()) as ModelAlias;
+  assertEquals(created.name, 'gpt-fast');
+  assertEquals(created.visible_in_models_list, true);
+  assertEquals(created.targets[0].target_model_id, 'gpt-5.4');
+
+  const stored = await repo.modelAliases.getByName('gpt-fast');
+  assertExists(stored);
+  assertEquals(stored.visibleInModelsList, true);
+});
+
+test('POST /api/aliases rejects a name collision with 409', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await requestApp('/api/aliases', authed(adminSession, baseBody()));
+
+  const resp = await requestApp('/api/aliases', authed(adminSession, baseBody()));
+  assertEquals(resp.status, 409);
+  const body = (await resp.json()) as { error?: string };
+  assertEquals(body.error?.includes('already exists'), true);
+});
+
+test('PUT /api/aliases/:name updates rules and refreshes updated_at', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await requestApp('/api/aliases', authed(adminSession, baseBody()));
+  const before = await repo.modelAliases.getByName('gpt-fast');
+  assertExists(before);
+  await new Promise(resolve => setTimeout(resolve, 5));
+
+  const resp = await requestApp(
+    '/api/aliases/gpt-fast',
+    putAuthed(adminSession, baseBody({ display_name: 'GPT Fast', targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'high' } } }] })),
+  );
+  assertEquals(resp.status, 200);
+  const updated = (await resp.json()) as ModelAlias;
+  assertEquals(updated.display_name, 'GPT Fast');
+  assertEquals(updated.targets[0].rules, { reasoning: { effort: 'high' } });
+  // createdAt is preserved; updatedAt is fresh.
+  assertEquals(updated.created_at, before.createdAt);
+  if (updated.updated_at === before.updatedAt) throw new Error('updated_at did not refresh');
+});
+
+test('PUT /api/aliases/:name with a different body.name renames the row', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await requestApp('/api/aliases', authed(adminSession, baseBody()));
+
+  const resp = await requestApp(
+    '/api/aliases/gpt-fast',
+    putAuthed(adminSession, baseBody({ name: 'gpt-fastest' })),
+  );
+  assertEquals(resp.status, 200);
+  assertEquals(await repo.modelAliases.getByName('gpt-fast'), null);
+  assertExists(await repo.modelAliases.getByName('gpt-fastest'));
+});
+
+test('PUT /api/aliases/:name rename collision returns 409', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await requestApp('/api/aliases', authed(adminSession, baseBody({ name: 'gpt-fast' })));
+  await requestApp('/api/aliases', authed(adminSession, baseBody({ name: 'gpt-slow' })));
+
+  const resp = await requestApp(
+    '/api/aliases/gpt-fast',
+    putAuthed(adminSession, baseBody({ name: 'gpt-slow' })),
+  );
+  assertEquals(resp.status, 409);
+});
+
+test('PUT /api/aliases/:name on a missing alias returns 404', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp('/api/aliases/nope', putAuthed(adminSession, baseBody({ name: 'nope' })));
+  assertEquals(resp.status, 404);
+});
+
+test('DELETE /api/aliases/:name returns 204 when present', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await requestApp('/api/aliases', authed(adminSession, baseBody()));
+
+  const resp = await requestApp('/api/aliases/gpt-fast', deleteAuthed(adminSession));
+  assertEquals(resp.status, 204);
+  assertEquals(await repo.modelAliases.getByName('gpt-fast'), null);
+});
+
+test('DELETE /api/aliases/:name is idempotent — 204 even when the row is absent', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp('/api/aliases/missing', deleteAuthed(adminSession));
+  assertEquals(resp.status, 204);
+});
+
+test('POST /api/aliases rejects an empty targets array with 400', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp('/api/aliases', authed(adminSession, baseBody({ targets: [] })));
+  assertEquals(resp.status, 400);
+});
+
+test('POST /api/aliases rejects an empty target_model_id with 400', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp(
+    '/api/aliases',
+    authed(adminSession, baseBody({ targets: [{ target_model_id: '', rules: {} }] })),
+  );
+  assertEquals(resp.status, 400);
+});
+
+test('POST /api/aliases rejects non-empty rules on kind=embedding with 400', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp(
+    '/api/aliases',
+    authed(adminSession, baseBody({
+      kind: 'embedding',
+      targets: [{ target_model_id: 'text-embedding-3', rules: { verbosity: 'low' } }],
+    })),
+  );
+  assertEquals(resp.status, 400);
+});
+
+test('POST /api/aliases accepts kind=embedding with empty rules', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp(
+    '/api/aliases',
+    authed(adminSession, baseBody({
+      kind: 'embedding',
+      targets: [{ target_model_id: 'text-embedding-3', rules: {} }],
+    })),
+  );
+  assertEquals(resp.status, 201);
+});
+
+test('POST /api/aliases rejects unknown reasoning fields on a chat target with 400', async () => {
+  const { repo, adminSession } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+
+  const resp = await requestApp(
+    '/api/aliases',
+    authed(adminSession, baseBody({
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { bogus: 1 } } }],
+    })),
+  );
+  assertEquals(resp.status, 400);
+});
diff --git a/packages/gateway/src/control-plane/model-aliases/serialize.ts b/packages/gateway/src/control-plane/model-aliases/serialize.ts
new file mode 100644
index 000000000..cd83de649
--- /dev/null
+++ b/packages/gateway/src/control-plane/model-aliases/serialize.ts
@@ -0,0 +1,43 @@
+// Snake_case wire ↔ camelCase record conversion for model aliases. The wire
+// shape (`ModelAlias`) lives in `@floway-dev/protocols/common`.
+
+import type { ModelAliasRecord } from '../../repo/types.ts';
+import type { ModelAlias } from '@floway-dev/protocols/common';
+
+export const recordToWire = (record: ModelAliasRecord): ModelAlias => ({
+  name: record.name,
+  kind: record.kind,
+  selection: record.selection,
+  display_name: record.displayName,
+  visible_in_models_list: record.visibleInModelsList,
+  targets: record.targets,
+  announced_metadata: record.announcedMetadata,
+  sort_order: record.sortOrder,
+  created_at: record.createdAt,
+  updated_at: record.updatedAt,
+});
+
+// Server-managed fields (`created_at` / `updated_at` are stamped by the repo;
+// `sort_order` defaults to `nextSortOrder` when omitted) are stripped here so
+// the create/update bodies cannot dictate them. The remaining required-field
+// list rides entirely on `ModelAlias` — a new column in the wire DTO only
+// requires editing one place.
+export type ModelAliasWireInput =
+  & Omit<ModelAlias, 'sort_order' | 'created_at' | 'updated_at'>
+  & { sort_order?: number };
+
+export const wireToRecord = (
+  wire: ModelAliasWireInput,
+  meta: { sortOrder: number; createdAt: string; updatedAt: string },
+): ModelAliasRecord => ({
+  name: wire.name,
+  kind: wire.kind,
+  selection: wire.selection,
+  displayName: wire.display_name,
+  visibleInModelsList: wire.visible_in_models_list,
+  targets: wire.targets,
+  announcedMetadata: wire.announced_metadata,
+  sortOrder: meta.sortOrder,
+  createdAt: meta.createdAt,
+  updatedAt: meta.updatedAt,
+});
diff --git a/packages/gateway/src/control-plane/model-aliases/serialize_test.ts b/packages/gateway/src/control-plane/model-aliases/serialize_test.ts
new file mode 100644
index 000000000..561af2fcd
--- /dev/null
+++ b/packages/gateway/src/control-plane/model-aliases/serialize_test.ts
@@ -0,0 +1,84 @@
+import { test } from 'vitest';
+
+import { recordToWire, wireToRecord } from './serialize.ts';
+import type { ModelAliasRecord } from '../../repo/types.ts';
+import { assertEquals } from '@floway-dev/test-utils';
+
+const record: ModelAliasRecord = {
+  name: 'codex-auto-review',
+  kind: 'chat',
+  selection: 'first-available',
+  displayName: 'Codex Auto Review',
+  visibleInModelsList: true,
+  targets: [
+    { target_model_id: 'codex-auto-review', rules: {} },
+    { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } },
+  ],
+  announcedMetadata: null,
+  sortOrder: 3,
+  createdAt: '2026-06-26T00:00:00.000Z',
+  updatedAt: '2026-06-26T12:00:00.000Z',
+};
+
+test('recordToWire flips camelCase fields to snake_case', () => {
+  const wire = recordToWire(record);
+  assertEquals(wire.name, 'codex-auto-review');
+  assertEquals(wire.kind, 'chat');
+  assertEquals(wire.selection, 'first-available');
+  assertEquals(wire.display_name, 'Codex Auto Review');
+  assertEquals(wire.visible_in_models_list, true);
+  assertEquals(wire.sort_order, 3);
+  assertEquals(wire.created_at, '2026-06-26T00:00:00.000Z');
+  assertEquals(wire.updated_at, '2026-06-26T12:00:00.000Z');
+  assertEquals(wire.targets, record.targets);
+});
+
+test('wireToRecord roundtrips back to the original record', () => {
+  const wire = recordToWire(record);
+  const roundTripped = wireToRecord(wire, {
+    sortOrder: wire.sort_order,
+    createdAt: wire.created_at,
+    updatedAt: wire.updated_at,
+  });
+  assertEquals(roundTripped, record);
+});
+
+test('wireToRecord uses meta sortOrder when the wire payload omits it', () => {
+  const { sort_order: _drop, ...partial } = recordToWire(record);
+  const built = wireToRecord(partial, {
+    sortOrder: 7,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-06-26T12:00:00.000Z',
+  });
+  assertEquals(built.sortOrder, 7);
+  assertEquals(built.createdAt, '2026-01-01T00:00:00.000Z');
+});
+
+test('wireToRecord preserves a null display_name', () => {
+  const built = wireToRecord(
+    { ...recordToWire(record), display_name: null },
+    { sortOrder: 0, createdAt: 'x', updatedAt: 'y' },
+  );
+  assertEquals(built.displayName, null);
+});
+
+test('announced_metadata round-trips a populated override', () => {
+  const withOverride: ModelAliasRecord = {
+    ...record,
+    announcedMetadata: {
+      limits: { max_output_tokens: 8192 },
+      chat: { modalities: { input: ['text'], output: ['text'] } },
+    },
+  };
+  const wire = recordToWire(withOverride);
+  assertEquals(wire.announced_metadata, {
+    limits: { max_output_tokens: 8192 },
+    chat: { modalities: { input: ['text'], output: ['text'] } },
+  });
+  const roundTripped = wireToRecord(wire, {
+    sortOrder: wire.sort_order,
+    createdAt: wire.created_at,
+    updatedAt: wire.updated_at,
+  });
+  assertEquals(roundTripped, withOverride);
+});
diff --git a/packages/gateway/src/control-plane/models/routes.ts b/packages/gateway/src/control-plane/models/routes.ts
index 3146a3edc..bdce45a48 100644
--- a/packages/gateway/src/control-plane/models/routes.ts
+++ b/packages/gateway/src/control-plane/models/routes.ts
@@ -1,10 +1,12 @@
 import type { Context } from 'hono';
 
+import { mergeAliasesIntoModels } from '../../data-plane/models/alias-listing.ts';
 import { toPublicModel } from '../../data-plane/models/load.ts';
 import { MODEL_LISTING_FAILURE_MESSAGE } from '../../data-plane/models/shared.ts';
-import { getModels } from '../../data-plane/providers/registry.ts';
+import { enumerateAddressableModelIds, listedRealModels } from '../../data-plane/providers/addressable.ts';
 import { createPerRequestFetcher } from '../../dial/per-request.ts';
-import { effectiveUpstreamIdsFromContext } from '../../middleware/auth.ts';
+import { effectiveUpstreamIdsFromContext, userFromContext } from '../../middleware/auth.ts';
+import { getRepo } from '../../repo/index.ts';
 import { backgroundSchedulerFromContext } from '../../runtime/background.ts';
 import { getCurrentColo } from '../../runtime/runtime-info.ts';
 import type { PublicModel, PublicModelsResponse } from '@floway-dev/protocols/common';
@@ -15,7 +17,9 @@ import type { ResolvedModel, UpstreamProviderKind } from '@floway-dev/provider';
 // `upstreams` lists every provider binding for this model as { kind, id, name }
 // triples. A single model id can be served by mixed provider kinds (e.g. one
 // azure deployment + one custom upstream both expose `gpt-5.5`), so a flat
-// `provider`/`upstream_ids` split would misrepresent that.
+// `provider`/`upstream_ids` split would misrepresent that. Alias-synthesized
+// rows carry an empty list — they do not bind to an upstream directly; their
+// targets live under `aliasedFrom`.
 interface ControlPlaneModel extends PublicModel {
   upstreams: { kind: UpstreamProviderKind; id: string; name: string }[];
 }
@@ -29,15 +33,75 @@ const toControlPlaneModel = (model: ResolvedModel): ControlPlaneModel => ({
   upstreams: model.providers.map(binding => ({ kind: binding.providerKind, id: binding.upstream, name: binding.upstreamName })),
 });
 
+// Wrap an addressable-but-not-listed entry as a control-plane row. The
+// canonical metadata (`limits`, `chat`, `endpoints`, `upstreams`) reads
+// off the real model the addressable id resolves to; only `id` and
+// `display_name` swap in the addressable form so the alias dialog
+// combobox renders the actual id the operator can type. `unlisted: true`
+// carries the addressability tag through to the dashboard so a future UI
+// badge does not need a second registry call.
+const toUnlistedControlPlaneModel = (id: string, model: ResolvedModel): ControlPlaneModel => ({
+  ...toControlPlaneModel(model),
+  id,
+  display_name: model.display_name ?? id,
+  unlisted: true,
+});
+
 export const controlPlaneModels = async (c: Context) => {
   try {
-    // Scope the dashboard catalog to the caller's effective upstreams, exactly
-    // like the data-plane /models endpoint. On a session request there is no
-    // API key, so this resolves to the user's per-user upstream cap: a user who
-    // has had an upstream removed must not see its models in the Models tab.
+    const includeAliases = c.req.query('aliases') !== 'false';
+    const includeUnlisted = c.req.query('include_unlisted') === 'true';
+    // Admin sessions see the entire gateway: editor surfaces (alias edit,
+    // upstream edit) need to configure models on upstreams the admin may
+    // have self-restricted out of their own data-plane access, and the
+    // dashboard filters the result client-side for surfaces that should
+    // respect the restriction (Models page, playground). Non-admin
+    // sessions stay scoped to their effective upstream cap so the
+    // dashboard cannot leak models from upstreams their account has no
+    // data-plane access to.
+    const isAdmin = userFromContext(c).isAdmin;
+    const upstreamScope = isAdmin ? null : effectiveUpstreamIdsFromContext(c);
     const fetcherForUpstream = await createPerRequestFetcher(getCurrentColo(c.req.raw));
-    const models = await getModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c));
-    const data = models.map(toControlPlaneModel);
+    // Two addressable surfaces: caller-scoped (drives visibility +
+    // `aliasedFrom.targets` narrowing for non-admin) and gateway-wide
+    // (drives the alias's metadata + endpoints + cost — every caller
+    // sees the same numbers for the same alias). For admin the two are
+    // the same, so skip the second fetch.
+    const [callerAddressable, gatewayAddressable, aliases] = await Promise.all([
+      enumerateAddressableModelIds(upstreamScope, fetcherForUpstream, backgroundSchedulerFromContext(c)),
+      isAdmin
+        ? Promise.resolve(null)
+        : enumerateAddressableModelIds(null, fetcherForUpstream, backgroundSchedulerFromContext(c)),
+      includeAliases ? getRepo().modelAliases.list() : Promise.resolve([]),
+    ]);
+    const gatewayAddressableModelIds = gatewayAddressable ?? callerAddressable;
+    const realModels = listedRealModels(callerAddressable);
+    const listedRows = includeAliases
+      ? mergeAliasesIntoModels({
+          realModels,
+          gatewayAddressableModelIds,
+          callerAddressableModelIds: callerAddressable,
+          aliases,
+          // Admin sees raw configured targets (including typos / out-of-
+          // cap models) so the alias-edit dialog can render the full
+          // configuration; non-admin sessions get the narrowed projection.
+          narrowTargets: !isAdmin,
+          mapReal: toControlPlaneModel,
+          wrapAlias: entry => ({ ...entry, upstreams: [] }),
+        })
+      : realModels.map(toControlPlaneModel);
+    // Dedupe the unlisted half against the listed half on `id` — an alias
+    // whose name coincides with an addressable-but-not-listed id (e.g. a
+    // Copilot variant) would otherwise emit two rows with the same id but
+    // different `unlisted` flags. /v1/models already collapses this kind
+    // of collision; the dashboard must agree.
+    const listedIds = new Set(listedRows.map(row => row.id));
+    const unlistedRows = includeUnlisted
+      ? callerAddressable
+          .filter(entry => entry.unlisted === true && !listedIds.has(entry.id))
+          .map(entry => toUnlistedControlPlaneModel(entry.id, entry.model))
+      : [];
+    const data = [...listedRows, ...unlistedRows];
     const response: ControlPlaneModelsResponse = {
       object: 'list',
       has_more: false,
@@ -47,11 +111,10 @@ export const controlPlaneModels = async (c: Context) => {
     };
     return c.json(response);
   } catch (e: unknown) {
-    // Empty-upstreams is a domain state, not an error, on the dashboard. The
-    // public /v1/models endpoint still surfaces it as a 502 to remote clients
-    // because they need to know the gateway is unconfigured — but the
-    // dashboard's Models tab should render an empty grid + the operator
-    // guidance message inline instead of flashing a 502 in devtools.
+    // Empty-upstreams is a domain state, not an error, on the dashboard:
+    // /v1/models still surfaces it as a 502 (remote clients need to know
+    // the gateway is unconfigured), but the Models tab renders an empty
+    // grid inline.
     if (e instanceof Error && e.message.startsWith('No upstream provider configured')) {
       return c.json({ object: 'list', has_more: false, first_id: null, last_id: null, data: [] });
     }
diff --git a/packages/gateway/src/control-plane/models/routes_test.ts b/packages/gateway/src/control-plane/models/routes_test.ts
index 7c611c31a..10349e327 100644
--- a/packages/gateway/src/control-plane/models/routes_test.ts
+++ b/packages/gateway/src/control-plane/models/routes_test.ts
@@ -2,7 +2,7 @@ import { test } from 'vitest';
 
 import { buildCustomUpstreamRecord, copilotModels, requestApp, setupAppTest } from '../../test-helpers.ts';
 import type { UpstreamRecord } from '@floway-dev/provider';
-import { assertEquals, jsonResponse, withMockedFetch } from '@floway-dev/test-utils';
+import { assert, assertEquals, jsonResponse, withMockedFetch } from '@floway-dev/test-utils';
 
 const azureUpstream = (): UpstreamRecord => ({
   id: 'up_azure_models',
@@ -113,3 +113,276 @@ test('/api/models is scoped to the caller\'s effective upstreams — a removed u
     assertEquals(ids.includes('azure-public'), false);
   });
 });
+
+test('/api/models appends visible alias entries with aliasedFrom alongside real catalog rows', async () => {
+  const { apiKey, repo } = await setupAppTest();
+  await repo.upstreams.save(buildCustomUpstreamRecord({ id: 'up_custom_models', sortOrder: 100 }));
+
+  await withMockedFetch(modelsFetchHandler, async () => {
+    const response = await requestApp('/api/models', { headers: { 'x-api-key': apiKey.key } });
+    assertEquals(response.status, 200);
+    const body = (await response.json()) as { data: Array<{ id: string; display_name: string; upstreams: Array<{ kind: string; id: string; name: string }> }> };
+    assertEquals(body.data.some(model => model.id === 'custom-model'), true);
+  });
+});
+
+test('/api/models?include_unlisted=true appends addressable-but-not-listed rows marked with `unlisted: true`', async () => {
+  const { apiKey } = await setupAppTest();
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+      if (url.pathname === '/copilot_internal/v2/token') {
+        return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+      }
+      if (url.hostname === 'api.individual.githubcopilot.com' && url.pathname === '/models') {
+        // Two variants of one model — Copilot publishes the dotted-version
+        // ids as raw upstream entries, but the public id collapses the
+        // dots and any `-high`/`-xhigh` suffix. The raw forms become
+        // addressable-but-not-listed entries.
+        return jsonResponse(copilotModels([
+          { id: 'claude-opus-4.7', display_name: 'Claude Opus 4.7', supported_endpoints: ['/v1/messages'] },
+          { id: 'claude-opus-4.7-high', supported_endpoints: ['/v1/messages'] },
+        ]));
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const listed = await requestApp('/api/models?aliases=false', { headers: { 'x-api-key': apiKey.key } });
+      const listedBody = (await listed.json()) as { data: Array<{ id: string; unlisted?: true }> };
+      assertEquals(listedBody.data.map(m => m.id), ['claude-opus-4-7']);
+      // The default response carries no `unlisted` field on any row.
+      assertEquals(listedBody.data.every(m => m.unlisted === undefined), true);
+
+      const full = await requestApp('/api/models?aliases=false&include_unlisted=true', { headers: { 'x-api-key': apiKey.key } });
+      const fullBody = (await full.json()) as { data: Array<{ id: string; unlisted?: true; upstreams: unknown[] }> };
+      const ids = fullBody.data.map(m => m.id);
+      assertEquals(ids.includes('claude-opus-4-7'), true);
+      assertEquals(ids.includes('claude-opus-4.7'), true);
+      assertEquals(ids.includes('claude-opus-4.7-high'), true);
+      // Only the addressable-but-not-listed rows carry the sidecar tag.
+      const tagged = new Set(fullBody.data.filter(m => m.unlisted === true).map(m => m.id));
+      assertEquals(tagged.has('claude-opus-4-7'), false);
+      assertEquals(tagged.has('claude-opus-4.7'), true);
+      assertEquals(tagged.has('claude-opus-4.7-high'), true);
+      // Each addressable row keeps the canonical model's upstreams metadata
+      // verbatim so the dashboard renders the real binding without a second
+      // call.
+      const variant = fullBody.data.find(m => m.id === 'claude-opus-4.7')!;
+      assertEquals(variant.upstreams.length > 0, true);
+    },
+  );
+});
+
+test('/api/models?include_unlisted=true: alias whose name collides with an unlisted addressable id emits only the listed row', async () => {
+  // Operator-side trap: an alias name accidentally matching a Copilot
+  // variant id (e.g. `claude-opus-4.7`). Both the listed alias row and
+  // the unlisted addressable row carry the same `id`, so emitting both
+  // would break OpenAI-client deduplication and contradict /v1/models's
+  // alias-vs-real collision rule (alias wins, real is dropped).
+  const { apiKey, repo } = await setupAppTest();
+  await repo.modelAliases.insert({
+    name: 'claude-opus-4.7',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: 'Alias colliding with the unlisted Copilot variant',
+    visibleInModelsList: true,
+    targets: [{ target_model_id: 'claude-opus-4-7', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  });
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+      if (url.pathname === '/copilot_internal/v2/token') {
+        return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+      }
+      if (url.hostname === 'api.individual.githubcopilot.com' && url.pathname === '/models') {
+        return jsonResponse(copilotModels([
+          { id: 'claude-opus-4.7', display_name: 'Claude Opus 4.7', supported_endpoints: ['/v1/messages'] },
+        ]));
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const full = await requestApp('/api/models?include_unlisted=true', { headers: { 'x-api-key': apiKey.key } });
+      const fullBody = (await full.json()) as { data: Array<{ id: string; unlisted?: true; aliasedFrom?: unknown }> };
+      const collisions = fullBody.data.filter(m => m.id === 'claude-opus-4.7');
+      assertEquals(collisions.length, 1);
+      // The surviving row is the alias-side one (aliasedFrom set, no
+      // `unlisted` tag), matching /v1/models's alias-wins rule.
+      assertEquals(collisions[0].aliasedFrom !== undefined, true);
+      assertEquals(collisions[0].unlisted, undefined);
+    },
+  );
+});
+
+test('/api/models for an admin session returns the gateway-wide catalog, bypassing the admin\'s own user.upstreamIds cap', async () => {
+  const { adminSession, repo } = await setupAppTest();
+  await repo.upstreams.save(buildCustomUpstreamRecord({ id: 'up_custom_models', sortOrder: 100 }));
+  await repo.upstreams.save(azureUpstream());
+
+  // Admin self-restricts. The dashboard's editor surfaces (alias edit,
+  // upstream edit) need to see "what exists on the entire gateway", and
+  // the Models page + playground filter the gateway-wide payload
+  // client-side for surfaces that should respect the restriction.
+  // Server-side gateway-wide for admin is the foundation that lets the
+  // dashboard do that filtering.
+  await repo.users.save({
+    id: 1,
+    username: 'admin',
+    passwordHash: null,
+    isAdmin: true,
+    upstreamIds: ['up_copilot', 'up_custom_models'],
+    canViewGlobalTelemetry: true,
+    createdAt: '2026-03-15T00:00:00.000Z',
+    deletedAt: null,
+  });
+
+  await withMockedFetch(modelsFetchHandler, async () => {
+    const response = await requestApp('/api/models', { headers: { 'x-floway-session': adminSession } });
+    assertEquals(response.status, 200);
+    const ids = ((await response.json()) as { data: Array<{ id: string }> }).data.map(m => m.id).sort();
+    assertEquals(ids.includes('azure-public'), true);
+    assertEquals(ids.includes('custom-model'), true);
+  });
+});
+
+test('/api/models — admin sees raw alias.targets; non-admin sees the caller-narrowed projection', async () => {
+  // Wire an alias with a typo target + one real target. Admin must see
+  // the typo (so the alias-edit dialog can render it for fixing); a
+  // non-admin who can reach the real target must see only that target
+  // — never the typo, never out-of-cap target ids.
+  const { adminSession, repo } = await setupAppTest();
+  await repo.upstreams.save(buildCustomUpstreamRecord({ id: 'up_custom_models', sortOrder: 100 }));
+  await repo.modelAliases.insert({
+    name: 'mix',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: null,
+    visibleInModelsList: true,
+    targets: [
+      { target_model_id: 'custom-model', rules: {} },
+      { target_model_id: 'typo-no-such-model', rules: {} },
+    ],
+    announcedMetadata: null,
+    sortOrder: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  });
+
+  // Non-admin user with access to the same upstream.
+  await repo.users.save({
+    id: 2,
+    username: 'tester',
+    passwordHash: null,
+    isAdmin: false,
+    upstreamIds: null,
+    canViewGlobalTelemetry: false,
+    createdAt: '2026-03-15T00:00:00.000Z',
+    deletedAt: null,
+  });
+  const nonAdminSession = (await repo.sessions.create(2)).id;
+
+  await withMockedFetch(modelsFetchHandler, async () => {
+    const adminResponse = await requestApp('/api/models', { headers: { 'x-floway-session': adminSession } });
+    assertEquals(adminResponse.status, 200);
+    const adminBody = (await adminResponse.json()) as { data: Array<{ id: string; aliasedFrom?: { targets: Array<{ target_model_id: string }> } }> };
+    const adminMix = adminBody.data.find(m => m.id === 'mix');
+    assert(adminMix !== undefined);
+    assertEquals(
+      adminMix!.aliasedFrom?.targets.map(t => t.target_model_id),
+      ['custom-model', 'typo-no-such-model'],
+    );
+
+    const nonAdminResponse = await requestApp('/api/models', { headers: { 'x-floway-session': nonAdminSession } });
+    assertEquals(nonAdminResponse.status, 200);
+    const nonAdminBody = (await nonAdminResponse.json()) as { data: Array<{ id: string; aliasedFrom?: { targets: Array<{ target_model_id: string }> } }> };
+    const nonAdminMix = nonAdminBody.data.find(m => m.id === 'mix');
+    assert(nonAdminMix !== undefined);
+    // Typo `typo-no-such-model` is hidden; only the reachable target is exposed.
+    assertEquals(
+      nonAdminMix!.aliasedFrom?.targets.map(t => t.target_model_id),
+      ['custom-model'],
+    );
+  });
+});
+
+test('/api/models — admin self-restriction does NOT leak per-alias metadata variation; non-admin and admin see identical limits/endpoints for the same alias', async () => {
+  // Two upstreams advertising the same alias's targets, but with
+  // different windows. Admin sees gateway-wide (limit = min over all).
+  // Non-admin restricted to the larger-window upstream should still see
+  // the same lower limit — metadata is a stable property of the alias,
+  // not a per-caller derivation.
+  const { adminSession, repo } = await setupAppTest();
+  await repo.upstreams.deleteAll();
+  await repo.upstreams.save(buildCustomUpstreamRecord({
+    id: 'up_small',
+    name: 'Small',
+    sortOrder: 100,
+    config: {
+      baseUrl: 'https://small.example.com',
+      authStyle: 'bearer',
+      apiKey: 'sk-small',
+      endpoints: { chatCompletions: {} },
+      models: [{ upstreamModelId: 'shared', publicModelId: 'shared', kind: 'chat', endpoints: { chatCompletions: {} }, limits: { max_context_window_tokens: 100_000 } }],
+      modelsFetch: { enabled: false },
+    },
+  }));
+  await repo.upstreams.save(buildCustomUpstreamRecord({
+    id: 'up_big',
+    name: 'Big',
+    sortOrder: 200,
+    config: {
+      baseUrl: 'https://big.example.com',
+      authStyle: 'bearer',
+      apiKey: 'sk-big',
+      endpoints: { chatCompletions: {} },
+      models: [{ upstreamModelId: 'shared', publicModelId: 'shared', kind: 'chat', endpoints: { chatCompletions: {} }, limits: { max_context_window_tokens: 200_000 } }],
+      modelsFetch: { enabled: false },
+    },
+  }));
+  await repo.modelAliases.insert({
+    name: 'shared-alias',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: null,
+    visibleInModelsList: true,
+    targets: [{ target_model_id: 'shared', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  });
+
+  // Non-admin user scoped to ONLY the big-window upstream.
+  await repo.users.save({
+    id: 2, username: 'tester', passwordHash: null, isAdmin: false,
+    upstreamIds: ['up_big'], canViewGlobalTelemetry: false,
+    createdAt: '2026-03-15T00:00:00.000Z', deletedAt: null,
+  });
+  const nonAdminSession = (await repo.sessions.create(2)).id;
+
+  await withMockedFetch(() => { throw new Error('unexpected outbound fetch'); }, async () => {
+    const [adminRes, nonAdminRes] = await Promise.all([
+      requestApp('/api/models', { headers: { 'x-floway-session': adminSession } }),
+      requestApp('/api/models', { headers: { 'x-floway-session': nonAdminSession } }),
+    ]);
+    const adminBody = (await adminRes.json()) as { data: Array<{ id: string; limits?: { max_context_window_tokens?: number } }> };
+    const nonAdminBody = (await nonAdminRes.json()) as { data: Array<{ id: string; limits?: { max_context_window_tokens?: number } }> };
+    const adminAlias = adminBody.data.find(m => m.id === 'shared-alias');
+    const nonAdminAlias = nonAdminBody.data.find(m => m.id === 'shared-alias');
+    assert(adminAlias !== undefined);
+    assert(nonAdminAlias !== undefined);
+    // Both callers see the safe-lower-bound window — even though the
+    // non-admin's resolver would only ever pick the big-window
+    // upstream's binding.
+    assertEquals(adminAlias!.limits?.max_context_window_tokens, 100_000);
+    assertEquals(nonAdminAlias!.limits?.max_context_window_tokens, 100_000);
+  });
+});
diff --git a/packages/gateway/src/control-plane/routes.ts b/packages/gateway/src/control-plane/routes.ts
index 94b5f06ff..60fb9404c 100644
--- a/packages/gateway/src/control-plane/routes.ts
+++ b/packages/gateway/src/control-plane/routes.ts
@@ -5,10 +5,11 @@ import { authLogin, authLogout, authMe } from './auth/routes.ts';
 import { copilotQuota } from './copilot-quota/routes.ts';
 import { exportData, importData } from './data-transfer/routes.ts';
 import { dumpRoutes } from './dump.ts';
+import { createAlias, deleteAlias, listAliases, updateAlias } from './model-aliases/routes.ts';
 import { controlPlaneModels } from './models/routes.ts';
 import { performanceOverview, performanceTelemetry } from './performance/routes.ts';
 import { createProxy, deleteProxy, listAllBackoffs, listProxies, listProxyBackoffs, resetProxyBackoffs, testProxy, updateProxy } from './proxies/routes.ts';
-import { authLoginBody, changeOwnPasswordBody, claudeCodeAuthorizeUrlBody, claudeCodeImportBody, claudeCodeProbeQuotaBody, claudeCodeRefreshNowBody, claudeCodeReimportBody, claudeCodeSetupTokenImportBody, claudeCodeSetupTokenReimportBody, codexAuthorizeUrlBody, codexImportBody, codexRefreshNowBody, codexReimportBody, copilotAuthPollBody, createKeyBody, createProxyBody, createUpstreamBody, createUserBody, exportQuery, fetchModelsBody, importBody, performanceQuery, resetBackoffBody, searchConfigSchema, searchUsageQuery, testProxyBody, tokenUsageQuery, updateKeyBody, updateProxyBody, updateUpstreamBody, updateUserBody } from './schemas.ts';
+import { authLoginBody, changeOwnPasswordBody, claudeCodeAuthorizeUrlBody, claudeCodeImportBody, claudeCodeProbeQuotaBody, claudeCodeRefreshNowBody, claudeCodeReimportBody, claudeCodeSetupTokenImportBody, claudeCodeSetupTokenReimportBody, codexAuthorizeUrlBody, codexImportBody, codexRefreshNowBody, codexReimportBody, copilotAuthPollBody, createAliasBody, createKeyBody, createProxyBody, createUpstreamBody, createUserBody, exportQuery, fetchModelsBody, importBody, modelsQuery, performanceQuery, resetBackoffBody, searchConfigSchema, searchUsageQuery, testProxyBody, tokenUsageQuery, updateAliasBody, updateKeyBody, updateProxyBody, updateUpstreamBody, updateUserBody } from './schemas.ts';
 import { getSearchConfigRoute, putSearchConfigRoute, testSearchConfigRoute } from './search-config/routes.ts';
 import { searchUsage } from './search-usage/routes.ts';
 import { tokenUsage } from './token-usage/routes.ts';
@@ -48,7 +49,7 @@ export const controlPlaneRoutes = new Hono<{ Variables: AuthVars }>()
   .get('/api/search-usage', zValidator('query', searchUsageQuery), searchUsage)
   .get('/api/performance', zValidator('query', performanceQuery), performanceTelemetry)
   .get('/api/performance/overview', zValidator('query', performanceQuery), performanceOverview)
-  .get('/api/models', controlPlaneModels)
+  .get('/api/models', zValidator('query', modelsQuery), controlPlaneModels)
   // Minimal upstream picker exposed to non-admin users so they can scope a key
   // to specific upstreams. Returns id/name/provider/enabled only — no config,
   // no flag overrides, no model lists. Server-side validation (api-keys'
@@ -97,6 +98,12 @@ export const controlPlaneRoutes = new Hono<{ Variables: AuthVars }>()
     .get('/proxies/:id/backoffs', listProxyBackoffs)
     .patch('/proxies/:id', zValidator('json', updateProxyBody), updateProxy)
     .delete('/proxies/:id', deleteProxy)
+    // Model aliases. Admin-only — alias config is gateway-wide tenant state,
+    // and the data-plane resolver runs above prefix routing for every request.
+    .get('/aliases', listAliases)
+    .post('/aliases', zValidator('json', createAliasBody), createAlias)
+    .put('/aliases/:name', zValidator('json', updateAliasBody), updateAlias)
+    .delete('/aliases/:name', deleteAlias)
     .get('/search-config', getSearchConfigRoute)
     .put('/search-config', zValidator('json', searchConfigSchema), putSearchConfigRoute)
     .post('/search-config/test', zValidator('json', searchConfigSchema), testSearchConfigRoute)
diff --git a/packages/gateway/src/control-plane/schemas.ts b/packages/gateway/src/control-plane/schemas.ts
index f718539ee..ae8c43a93 100644
--- a/packages/gateway/src/control-plane/schemas.ts
+++ b/packages/gateway/src/control-plane/schemas.ts
@@ -122,6 +122,14 @@ const chatSchema = z.object({
   reasoning: reasoningSchema.optional(),
 });
 
+// Shared limits shape used by both the upstream-model schema and the
+// alias's announced-metadata override.
+const limitsSchema = z.object({
+  max_context_window_tokens: z.number().optional(),
+  max_prompt_tokens: z.number().optional(),
+  max_output_tokens: z.number().optional(),
+});
+
 // Mirrors the runtime UpstreamModelConfig in @floway-dev/provider.
 // Azure and custom upstreams share this per-model entry; the canonical
 // per-model endpoint validation lives in the runtime validator.
@@ -146,11 +154,7 @@ const upstreamModelSchema = z.object({
     enabled: z.boolean(),
     values: flagOverrideValuesSchema,
   }).optional(),
-  limits: z.object({
-    max_context_window_tokens: z.number().optional(),
-    max_prompt_tokens: z.number().optional(),
-    max_output_tokens: z.number().optional(),
-  }).optional(),
+  limits: limitsSchema.optional(),
   chat: chatSchema.optional(),
 }).refine(
   m => m.chat === undefined || m.kind === undefined || m.kind === 'chat',
@@ -593,6 +597,103 @@ export const searchConfigSchema = z.object({
   jina: z.object({ apiKey: z.string() }),
 });
 
+// --- model aliases ---
+
+// Per-target chat rules. Field names mirror the IR slot each value overlays.
+// Values forward verbatim — no capability narrowing here, so an operator
+// can drive a feature the catalog hasn't advertised yet. The four value
+// fields below (`effort`, `summary`, `verbosity`, `serviceTier`) accept
+// any string for the same reason; the dashboard pins canonical presets as
+// combobox suggestions.
+const chatAliasReasoningSchema = z.object({
+  effort: z.string().min(1).optional(),
+  budget_tokens: z.number().int().nonnegative().optional(),
+  adaptive: z.boolean().optional(),
+  summary: z.string().min(1).optional(),
+}).strict();
+
+const chatAliasRulesSchema = z.object({
+  reasoning: chatAliasReasoningSchema.optional(),
+  verbosity: z.string().min(1).optional(),
+  serviceTier: z.string().min(1).optional(),
+}).strict();
+
+// Rules are validated against the alias-level kind in the superRefine pass
+// below — chat-kind aliases accept ChatAliasRules; other kinds require an
+// empty object. Each target_model_id is opaque (no `/` semantics in the
+// alias layer), so the only structural check is non-emptiness.
+const aliasTargetSchema = z.object({
+  target_model_id: z.string().min(1),
+  rules: z.record(z.string(), z.unknown()),
+});
+
+// Operator override for an alias's announced /v1/models payload. Both
+// sub-fields are independently optional, and the alias-listing pipeline
+// falls back to the rule-aware automatic computation for any TOP-LEVEL
+// sub-block (`limits` / `chat`) the operator did not provide — a present
+// sub-block replaces the computed counterpart wholesale, not per-leaf.
+// `chatSchema` and `limitsSchema` are the same shapes the upstream-model
+// surface validates, so the override carries the catalog's full
+// vocabulary.
+const announcedMetadataSchema = z.object({
+  limits: limitsSchema.optional(),
+  chat: chatSchema.optional(),
+});
+
+const aliasBaseShape = {
+  name: z.string().min(1),
+  kind: z.enum(['chat', 'embedding', 'image']),
+  selection: z.enum(['random', 'first-available']),
+  display_name: z.string().min(1).nullable(),
+  visible_in_models_list: z.boolean(),
+  targets: z.array(aliasTargetSchema).min(1),
+  announced_metadata: announcedMetadataSchema.nullable(),
+  sort_order: z.number().int().optional(),
+};
+
+const aliasBodyCore = z.object(aliasBaseShape);
+
+// superRefine cross-validates each target's `rules` against the alias-level
+// kind. Chat: parse through `chatAliasRulesSchema` and surface the inner
+// issue verbatim. Embedding / image: the slot must be `{}` until a future
+// schema lands.
+const aliasBodyRulesRefinement = (
+  value: z.infer<typeof aliasBodyCore>,
+  ctx: z.core.$RefinementCtx,
+): void => {
+  value.targets.forEach((target, index) => {
+    if (value.kind === 'chat') {
+      const parsed = chatAliasRulesSchema.safeParse(target.rules);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          ctx.issues.push({
+            code: 'custom',
+            message: issue.message,
+            path: ['targets', index, 'rules', ...issue.path],
+            input: target.rules,
+          });
+        }
+      }
+      return;
+    }
+    if (Object.keys(target.rules).length !== 0) {
+      ctx.issues.push({
+        code: 'custom',
+        message: `rules must be empty for kind=${value.kind}`,
+        path: ['targets', index, 'rules'],
+        input: target.rules,
+      });
+    }
+  });
+};
+
+// Create and update share the same body shape — the difference is operational:
+// create rejects PK collisions, update reads the path `:name` as the old name
+// and treats a different `body.name` as a rename. Splitting them keeps the
+// type names self-documenting at the RPC-client surface.
+export const createAliasBody = aliasBodyCore.superRefine(aliasBodyRulesRefinement);
+export const updateAliasBody = aliasBodyCore.superRefine(aliasBodyRulesRefinement);
+
 // --- data transfer ---
 
 export const importBody = z.object({
@@ -623,6 +724,18 @@ const usageBaseQuery = {
 };
 
 export const tokenUsageQuery = z.object(usageBaseQuery);
+
+// Dashboard `/api/models` accepts two query knobs. `aliases=false` skips the
+// alias-merge pass — the alias edit dialog and shadow detection need the
+// raw real-model set. `include_unlisted=true` extends the payload with the
+// addressable-but-not-listed surface (prefix-form alternates, Copilot
+// variant ids, provider-side redirects), so the alias dialog combobox sees
+// every id the data-plane resolver would accept.
+export const modelsQuery = z.object({
+  aliases: z.enum(['true', 'false']).optional(),
+  include_unlisted: z.enum(['true', 'false']).optional(),
+});
+
 export const searchUsageQuery = z.object({
   ...usageBaseQuery,
   provider: z.string().optional(),
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/attempt.ts b/packages/gateway/src/data-plane/chat/chat-completions/attempt.ts
index a2ed75bf5..b10737abd 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/attempt.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/attempt.ts
@@ -5,15 +5,15 @@ import { responsesAttempt } from '../responses/attempt.ts';
 import { rewriteStoredResponsesItemsForCandidate } from '../responses/items/rewrite.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
 import { providerStreamResultToExecuteResult, buildUpstreamCallOptions } from '../shared/attempt-helpers.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import { tryCatchChatServeFailure } from '../shared/errors.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createSanitizeTraceCtx, sanitizeForChatCompletionsUpstream } from '../shared/sanitize.ts';
 import { traverseTranslation } from '../shared/translate-traverse.ts';
 import { createUpstreamLatencyRecorder } from '../shared/upstream-telemetry.ts';
 import { runInterceptors } from '@floway-dev/interceptor';
 import type { ChatCompletionsMessage, ChatCompletionsPayload, ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
-import { type ExecuteResult } from '@floway-dev/provider';
+import { type ExecuteResult, type ProviderCandidate } from '@floway-dev/provider';
 import { translateChatCompletionsViaMessages, translateChatCompletionsViaResponses } from '@floway-dev/translate';
 import { chatCompletionsViaResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
@@ -102,6 +102,7 @@ const callChatCompletionsAsExecuteResult = async (
   headers: Headers,
 ): Promise<ExecuteResult<ProtocolFrame<ChatCompletionsStreamEvent>>> => {
   const { model: _model, ...body } = payload;
+  sanitizeForChatCompletionsUpstream(body as Record<string, unknown>, createSanitizeTraceCtx());
   const recorder = createUpstreamLatencyRecorder();
   const providerResult = await candidate.binding.provider.callChatCompletions(
     candidate.binding.upstreamModel,
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/attempt_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/attempt_test.ts
index b98bb97c7..c8c322a46 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/attempt_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/attempt_test.ts
@@ -4,13 +4,12 @@ import { chatCompletionsAttempt } from './attempt.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsPayload, ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_chat_completions_attempt_test';
@@ -22,6 +21,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/errors.ts b/packages/gateway/src/data-plane/chat/chat-completions/errors.ts
index 9d7c12a5f..f2ca73a4c 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/errors.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/errors.ts
@@ -34,5 +34,7 @@ export const renderChatCompletionsFailure = (
     return openAiErrorResult(404, appendFailedUpstreams(`Model ${failure.model} is not available on any configured upstream.`, failure.failedUpstreams));
   case 'model-unsupported':
     return openAiErrorResult(400, appendFailedUpstreams(`Model ${failure.model} does not support the /chat/completions endpoint.`, failure.failedUpstreams));
+  case 'alias-no-target-available':
+    return openAiErrorResult(404, failure.message);
   }
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/http.ts b/packages/gateway/src/data-plane/chat/chat-completions/http.ts
index a46d537ed..a22a86543 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/http.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/http.ts
@@ -3,7 +3,7 @@ import { chatCompletionsServe } from './serve.ts';
 import type { AuthedContext } from '../../../middleware/auth.ts';
 import { inboundHeadersForUpstream } from '../../shared/inbound-headers.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import { createGatewayCtxFromHono, type GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse, type GatewayCtx } from '../shared/gateway-ctx.ts';
 import { readRequestBody, type RequestBody } from '../shared/request-body.ts';
 import { providerModelsUnavailableResponse } from '../shared/upstream-models-error.ts';
 import type { ChatCompletionsPayload } from '@floway-dev/protocols/chat-completions';
@@ -24,7 +24,7 @@ const respondWithInternalError = async (c: AuthedContext, error: unknown, reques
   const effectiveCtx = ctx ?? createGatewayCtxFromHono(c, { wantsStream: false, requestBody });
   const result = internalErrorResult(502, toInternalDebugError(error));
   const { response } = await respondChatCompletions(c, result, false, false, effectiveCtx);
-  return (effectiveCtx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(effectiveCtx, response);
 };
 
 export const chatCompletionsHttp = {
@@ -44,7 +44,7 @@ export const chatCompletionsHttp = {
       const store = createNonResponsesSourceStore(ctx.apiKeyId);
       const result = await chatCompletionsServe.generate({ payload, ctx, store, headers: inboundHeadersForUpstream(c) });
       const { response } = await respondChatCompletions(c, result, wantsStream, includeUsageChunk, ctx);
-      return (ctx.dump?.finalize(response) ?? response);
+      return finalizeGatewayResponse(ctx, response);
     } catch (error) {
       return await respondWithInternalError(c, error, requestBody, ctx);
     }
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/http_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/http_test.ts
index 720fb53ac..20e3cd539 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/http_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/http_test.ts
@@ -5,21 +5,20 @@ import type { AuthVars } from '../../../middleware/auth.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { ApiKey, User } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
-import { directFetcher, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async () => {
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('http_test: no candidates enqueued');
-      return next;
+      return { ...next, failedUpstreams: [], aliasResolution: null };
     }),
   };
 });
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-developer-to-system_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-developer-to-system_test.ts
index 1d3c8252e..8b9c9f8c5 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-developer-to-system_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-developer-to-system_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-interleaved-system-to-user_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-interleaved-system-to-user_test.ts
index c7f560cb3..eee0403d9 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-interleaved-system-to-user_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/demote-interleaved-system-to-user_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/disable-reasoning-on-forced-tool-choice_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
index 7ba1962fd..bb715b2d0 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/include-usage-stream-options_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/include-usage-stream-options_test.ts
index 1a28fef4a..90e27b8fa 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/include-usage-stream-options_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/include-usage-stream-options_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/normalize-usage_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/normalize-usage_test.ts
index 0969e8d8e..746ff2e83 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/normalize-usage_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/normalize-usage_test.ts
@@ -15,6 +15,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-deepseek-normalize_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-deepseek-normalize_test.ts
index d72f890f5..dd5bc69ce 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-deepseek-normalize_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-deepseek-normalize_test.ts
@@ -19,6 +19,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-kimi-normalize_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-kimi-normalize_test.ts
index 74de17c38..e598b6f14 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-kimi-normalize_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-kimi-normalize_test.ts
@@ -15,6 +15,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-qwen-normalize_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-qwen-normalize_test.ts
index 4f7197da8..189545eec 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-qwen-normalize_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/interceptors/vendor-qwen-normalize_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/routing.ts b/packages/gateway/src/data-plane/chat/chat-completions/routing.ts
index 381feaea9..e2f771830 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/routing.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/routing.ts
@@ -1,8 +1,8 @@
 import { classifyResponsesItemAffinity } from '../responses/items/affinity.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { RoutingDecision } from '../shared/routing.ts';
 import type { ChatCompletionsPayload } from '@floway-dev/protocols/chat-completions';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import { chatCompletionsViaResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 export const planChatCompletionsRouting = async (input: {
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/routing_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/routing_test.ts
index 60cf54096..f81f0c11a 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/routing_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/routing_test.ts
@@ -5,9 +5,8 @@ import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createStoredResponsesItemId } from '../responses/items/format.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { ChatCompletionsPayload } from '@floway-dev/protocols/chat-completions';
-import { directFetcher } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate } from '@floway-dev/provider';
 import { stubProvider, stubUpstreamModel, assertEquals } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_chat_completions_routing_test';
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/serve.ts b/packages/gateway/src/data-plane/chat/chat-completions/serve.ts
index 73e8c1afd..b6337516b 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/serve.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/serve.ts
@@ -1,8 +1,9 @@
 import { chatCompletionsAttempt } from './attempt.ts';
 import { renderChatCompletionsFailure } from './errors.ts';
 import { planChatCompletionsRouting } from './routing.ts';
+import { applyChatRulesToChatCompletions } from '../../model-aliases/apply.ts';
+import { resolveCandidatesAndApplyAlias } from '../../model-aliases/prelude.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import { enumerateProviderCandidates } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsPayload, ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
@@ -18,17 +19,22 @@ export interface ChatCompletionsServeGenerateArgs {
 export const chatCompletionsServe = {
   generate: async (args: ChatCompletionsServeGenerateArgs): Promise<ExecuteResult<ProtocolFrame<ChatCompletionsStreamEvent>>> => {
     const { payload, ctx, store, headers } = args;
-    const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-      upstreamIds: ctx.upstreamIds,
-      model: payload.model,
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: payload.model,
       pickTarget: endpoints =>
         endpoints.chatCompletions ? 'chat-completions'
           : endpoints.messages ? 'messages'
             : endpoints.responses ? 'responses'
               : null,
-      scheduler: ctx.backgroundScheduler,
-      currentColo: ctx.currentColo,
+      applyAlias: resolution => {
+        payload.model = resolution.targetModelId;
+        applyChatRulesToChatCompletions(payload, resolution.rules);
+      },
+      renderAliasFailure: renderChatCompletionsFailure,
     });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams } = resolved;
     const decision = await planChatCompletionsRouting({ payload, candidates, store });
     if (decision.kind === 'failure') return renderChatCompletionsFailure(decision.failure);
 
diff --git a/packages/gateway/src/data-plane/chat/chat-completions/serve_test.ts b/packages/gateway/src/data-plane/chat/chat-completions/serve_test.ts
index 7549a3e3f..e7af46a8a 100644
--- a/packages/gateway/src/data-plane/chat/chat-completions/serve_test.ts
+++ b/packages/gateway/src/data-plane/chat/chat-completions/serve_test.ts
@@ -3,25 +3,53 @@ import { test, vi } from 'vitest';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsPayload, ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 // Mock the candidates seam so each test hands the serve exactly the
 // provider candidates it wants.
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+const lastCandidatesCall: { model?: string } = {};
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
+  const { resolveAlias } = await import('../../model-aliases/resolve.ts');
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async (args: { modelName: string; upstreamIds: readonly string[] | null; scheduler: () => void }) => {
+      // Pull the queued alias resolution so the serve sees a resolved target id and overlays rules from `aliasResolution`.
+      const aliasResolution = await resolveAlias({
+        modelName: args.modelName,
+        providers: [],
+        fetcherForUpstream: () => directFetcher,
+        scheduler: args.scheduler,
+        endpointAccepts: () => true,
+        repo: { getByName: () => Promise.resolve(null) } as never,
+      });
+      const effectiveModel = aliasResolution?.targetModelId ?? args.modelName;
+      lastCandidatesCall.model = effectiveModel;
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('serve_test: no candidates enqueued');
+      return { ...next, failedUpstreams: [], aliasResolution };
+    }),
+  };
+});
+
+// Mock the alias resolver so the integration test can inject a resolution
+// without standing up the full per-request fetcher + registry stack.
+const aliasResolutionQueue: ({ targetModelId: string; rules: Record<string, unknown>; aliasName: string } | null | Error)[] = [];
+vi.mock('../../model-aliases/resolve.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../model-aliases/resolve.ts')>();
+  return {
+    ...original,
+    resolveAlias: vi.fn(async () => {
+      if (aliasResolutionQueue.length === 0) return null;
+      const next = aliasResolutionQueue.shift()!;
+      if (next instanceof Error) throw next;
       return next;
     }),
   };
@@ -48,6 +76,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
@@ -279,3 +308,66 @@ test('generate renders model-missing when no candidates are available', async ()
   assertEquals(body.error.type, 'invalid_request_error');
   assertEquals(body.error.message, 'Model unknown-model is not available on any configured upstream.');
 });
+
+test('alias resolution swaps the inbound model id for the target and overlays rules onto the IR', async () => {
+  installRepo();
+  aliasResolutionQueue.push({
+    targetModelId: 'gpt-5.4',
+    rules: { reasoning: { effort: 'low' }, verbosity: 'low' },
+    aliasName: 'gpt-fast',
+  });
+  const capturedBodies: ChatCompletionsPayload[] = [];
+  const callChatCompletions = vi.fn(async (_model: unknown, body: unknown): Promise<ProviderStreamResult<ChatCompletionsStreamEvent>> => {
+    capturedBodies.push(body as ChatCompletionsPayload);
+    return { ok: true, events: makeProtocolFrames(makeChatCompletionsEvents()), modelKey: 'gpt-5.4', headers: new Headers() };
+  });
+  queueCandidates([makeCandidate({ upstream: 'up_a', callChatCompletions })]);
+
+  const result = await chatCompletionsServe.generate({
+    payload: makePayload({ model: 'gpt-fast' }),
+    ctx: makeGatewayCtx(),
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'events');
+  if (result.type !== 'events') throw new Error('unreachable');
+  await collectEvents(result.events);
+
+  // The resolved target id, not the alias name, must reach candidate
+  // enumeration so prefix routing addresses the real upstream model.
+  assertEquals(lastCandidatesCall.model, 'gpt-5.4');
+  // The alias rule overrides must land on the IR before the upstream call.
+  // (The attempt strips `model` from the body — the provider re-stamps it
+  // from `candidate.binding.upstreamModel.id` — so we only verify the rule
+  // fields here.)
+  const observed = capturedBodies[0]!;
+  assertEquals(observed.reasoning_effort, 'low');
+  assertEquals(observed.verbosity, 'low');
+});
+
+test('alias resolves to no routable target — renders the protocol 404 envelope + stages x-floway-alias on the failure', async () => {
+  installRepo();
+  const { AliasNoTargetAvailableError } = await import('../../model-aliases/resolve.ts');
+  aliasResolutionQueue.push(new AliasNoTargetAvailableError({
+    aliasName: 'gpt-fast', targetCount: 2, allEndpointMismatch: false,
+  }));
+  // No candidates are consumed on this path; the alias error short-circuits
+  // the routing pipeline before the candidate queue is even read.
+
+  const ctx = makeGatewayCtx();
+  const result = await chatCompletionsServe.generate({
+    payload: makePayload({ model: 'gpt-fast' }),
+    ctx,
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'api-error');
+  if (result.type !== 'api-error') throw new Error('unreachable');
+  assertEquals(result.status, 404);
+  const body = JSON.parse(new TextDecoder().decode(result.body));
+  assertEquals(body.error.type, 'invalid_request_error');
+  assert(body.error.message.includes("alias 'gpt-fast'"));
+  assertEquals(ctx.responseHeaders.get('x-floway-alias'), 'gpt-fast');
+});
diff --git a/packages/gateway/src/data-plane/chat/gemini/attempt.ts b/packages/gateway/src/data-plane/chat/gemini/attempt.ts
index 6a0950b42..38904c57c 100644
--- a/packages/gateway/src/data-plane/chat/gemini/attempt.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/attempt.ts
@@ -6,13 +6,12 @@ import { chatCompletionsAttempt } from '../chat-completions/attempt.ts';
 import { messagesAttempt } from '../messages/attempt.ts';
 import { responsesAttempt } from '../responses/attempt.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import { traverseTranslation } from '../shared/translate-traverse.ts';
 import { runInterceptors } from '@floway-dev/interceptor';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
 import type { GeminiPayload, GeminiStreamEvent } from '@floway-dev/protocols/gemini';
-import { plainResult, type ExecuteResult, type GeminiInvocation, type PlainResult } from '@floway-dev/provider';
+import { plainResult, type ExecuteResult, type GeminiInvocation, type PlainResult, type ProviderCandidate } from '@floway-dev/provider';
 import { translateGeminiViaChatCompletions, translateGeminiViaMessages, translateGeminiViaResponses } from '@floway-dev/translate';
 
 export interface GeminiAttemptGenerateArgs {
diff --git a/packages/gateway/src/data-plane/chat/gemini/attempt_test.ts b/packages/gateway/src/data-plane/chat/gemini/attempt_test.ts
index fbba21fe4..3b61d8998 100644
--- a/packages/gateway/src/data-plane/chat/gemini/attempt_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/attempt_test.ts
@@ -4,14 +4,13 @@ import { geminiAttempt } from './attempt.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { GeminiPayload } from '@floway-dev/protocols/gemini';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_gemini_attempt_test';
@@ -23,6 +22,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/gemini/errors.ts b/packages/gateway/src/data-plane/chat/gemini/errors.ts
index ccfede92c..cc560a85f 100644
--- a/packages/gateway/src/data-plane/chat/gemini/errors.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/errors.ts
@@ -53,5 +53,7 @@ export const renderGeminiFailure = (
     return geminiRpcErrorResult(404, appendFailedUpstreams(`Model ${failure.model} is not available on any configured upstream.`, failure.failedUpstreams));
   case 'model-unsupported':
     return geminiRpcErrorResult(400, appendFailedUpstreams(`Model ${failure.model} does not support ${endpoint === 'countTokens' ? 'countTokens' : 'the Gemini generateContent endpoint'}.`, failure.failedUpstreams));
+  case 'alias-no-target-available':
+    return geminiRpcErrorResult(404, failure.message);
   }
 };
diff --git a/packages/gateway/src/data-plane/chat/gemini/http.ts b/packages/gateway/src/data-plane/chat/gemini/http.ts
index 35a6e921f..8126d13e7 100644
--- a/packages/gateway/src/data-plane/chat/gemini/http.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/http.ts
@@ -3,7 +3,7 @@ import { geminiServe } from './serve.ts';
 import type { AuthedContext } from '../../../middleware/auth.ts';
 import { inboundHeadersForUpstream } from '../../shared/inbound-headers.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import { createGatewayCtxFromHono, type GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse, type GatewayCtx } from '../shared/gateway-ctx.ts';
 import { readRequestBody, type RequestBody } from '../shared/request-body.ts';
 import type { GeminiContent, GeminiPayload } from '@floway-dev/protocols/gemini';
 import { internalErrorResult, ProviderModelsUnavailableError, toInternalDebugError } from '@floway-dev/provider';
@@ -66,11 +66,11 @@ const respondWithGeminiError = async (
       body: new TextEncoder().encode(body),
     };
     const { response } = await respondGemini(c, apiErrorResult, wantsStream, ctx);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, response);
   }
   const internalResult = internalErrorResult(500, toInternalDebugError(error));
   const { response } = await respondGemini(c, internalResult, wantsStream, ctx);
-  return (ctx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(ctx, response);
 };
 
 // Single entry for `/v1beta/models/:modelAction`. Splits the model and action
@@ -97,7 +97,7 @@ const runGeminiGenerate = async (c: AuthedContext, model: string, wantsStream: b
   try {
     const result = await geminiServe.generate({ payload, ctx, store, model, headers: inboundHeadersForUpstream(c) });
     const { response } = await respondGemini(c, result, wantsStream, ctx);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, response);
   } catch (error) {
     return await respondWithGeminiError(c, error, ctx, wantsStream);
   }
@@ -113,7 +113,7 @@ const runGeminiCountTokens = async (c: AuthedContext, model: string): Promise<Re
   try {
     const result = await geminiServe.countTokens({ payload, ctx, store, model, headers: inboundHeadersForUpstream(c) });
     const { response } = await respondGemini(c, result, false, ctx);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, response);
   } catch (error) {
     return await respondWithGeminiError(c, error, ctx, false);
   }
diff --git a/packages/gateway/src/data-plane/chat/gemini/http_test.ts b/packages/gateway/src/data-plane/chat/gemini/http_test.ts
index 276d3251a..4090d0bc6 100644
--- a/packages/gateway/src/data-plane/chat/gemini/http_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/http_test.ts
@@ -5,22 +5,21 @@ import type { AuthVars } from '../../../middleware/auth.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { ApiKey, User } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
-import { directFetcher, type ProviderCallResult, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async () => {
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('http_test: no candidates enqueued');
-      return next;
+      return { ...next, failedUpstreams: [], aliasResolution: null };
     }),
   };
 });
diff --git a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-safety-settings_test.ts b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-safety-settings_test.ts
index c0b39f699..fa4475ad4 100644
--- a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-safety-settings_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-safety-settings_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-part-fields_test.ts b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-part-fields_test.ts
index 6a4608cf4..9e0306e13 100644
--- a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-part-fields_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-part-fields_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-tools_test.ts b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-tools_test.ts
index 7cbfc4593..2d818f4ca 100644
--- a/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-tools_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/interceptors/strip-unsupported-tools_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/gemini/interceptors/suppress-thought-parts_test.ts b/packages/gateway/src/data-plane/chat/gemini/interceptors/suppress-thought-parts_test.ts
index e526bb9e3..2659a8833 100644
--- a/packages/gateway/src/data-plane/chat/gemini/interceptors/suppress-thought-parts_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/interceptors/suppress-thought-parts_test.ts
@@ -14,6 +14,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/gemini/respond_test.ts b/packages/gateway/src/data-plane/chat/gemini/respond_test.ts
index a5c887c14..192dfdc98 100644
--- a/packages/gateway/src/data-plane/chat/gemini/respond_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/respond_test.ts
@@ -25,6 +25,7 @@ const ctx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/gemini/routing.ts b/packages/gateway/src/data-plane/chat/gemini/routing.ts
index 2d5e37d87..35222b4a5 100644
--- a/packages/gateway/src/data-plane/chat/gemini/routing.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/routing.ts
@@ -1,8 +1,8 @@
 import { classifyResponsesItemAffinity } from '../responses/items/affinity.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { RoutingDecision } from '../shared/routing.ts';
 import type { GeminiPayload } from '@floway-dev/protocols/gemini';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import { geminiViaResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 export type GeminiRoutingDecision = RoutingDecision;
diff --git a/packages/gateway/src/data-plane/chat/gemini/serve.ts b/packages/gateway/src/data-plane/chat/gemini/serve.ts
index f5daa1d86..b98f117fa 100644
--- a/packages/gateway/src/data-plane/chat/gemini/serve.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/serve.ts
@@ -1,8 +1,9 @@
 import { geminiAttempt } from './attempt.ts';
 import { renderGeminiFailure } from './errors.ts';
 import { planGeminiRouting } from './routing.ts';
+import { applyChatRulesToGemini } from '../../model-aliases/apply.ts';
+import { resolveCandidatesAndApplyAlias } from '../../model-aliases/prelude.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import { enumerateProviderCandidates } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
 import type { GeminiPayload, GeminiStreamEvent } from '@floway-dev/protocols/gemini';
@@ -29,16 +30,18 @@ export interface GeminiServeCountTokensArgs {
 
 export const geminiServe = {
   generate: async (args: GeminiServeGenerateArgs): Promise<ExecuteResult<ProtocolFrame<GeminiStreamEvent>>> => {
-    const { payload, ctx, store, model, headers } = args;
-    const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-      upstreamIds: ctx.upstreamIds,
-      model,
+    const { payload, ctx, store, headers } = args;
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: args.model,
       // Gemini has no native upstream target in the provider API; prefer
       // Chat Completions, then Messages, then Responses.
       pickTarget: endpoints => endpoints.chatCompletions ? 'chat-completions' : endpoints.messages ? 'messages' : endpoints.responses ? 'responses' : null,
-      scheduler: ctx.backgroundScheduler,
-      currentColo: ctx.currentColo,
+      applyAlias: resolution => applyChatRulesToGemini(payload, resolution.rules),
+      renderAliasFailure: failure => renderGeminiFailure(failure, 'generate'),
     });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams, effectiveModelId: model } = resolved;
     const decision = await planGeminiRouting({ payload, candidates, store });
     if (decision.kind === 'failure') return renderGeminiFailure(decision.failure, 'generate');
 
@@ -59,17 +62,19 @@ export const geminiServe = {
   },
 
   countTokens: async (args: GeminiServeCountTokensArgs): Promise<ExecuteResult<ProtocolFrame<GeminiStreamEvent>> | PlainResult> => {
-    const { payload, ctx, store, model, headers } = args;
-    const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-      upstreamIds: ctx.upstreamIds,
-      model,
+    const { payload, ctx, store, headers } = args;
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: args.model,
       // Gemini countTokens has no native upstream support; only providers
       // exposing the Messages endpoint qualify because we translate Gemini
       // → Messages and call Messages count_tokens upstream.
       pickTarget: endpoints => endpoints.messages ? 'messages' : null,
-      scheduler: ctx.backgroundScheduler,
-      currentColo: ctx.currentColo,
+      applyAlias: resolution => applyChatRulesToGemini(payload, resolution.rules),
+      renderAliasFailure: failure => renderGeminiFailure(failure, 'countTokens'),
     });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams, effectiveModelId: model } = resolved;
     const decision = await planGeminiRouting({ payload, candidates, store });
     if (decision.kind === 'failure') return renderGeminiFailure(decision.failure, 'countTokens');
 
diff --git a/packages/gateway/src/data-plane/chat/gemini/serve_test.ts b/packages/gateway/src/data-plane/chat/gemini/serve_test.ts
index 7df20f27e..128d27065 100644
--- a/packages/gateway/src/data-plane/chat/gemini/serve_test.ts
+++ b/packages/gateway/src/data-plane/chat/gemini/serve_test.ts
@@ -3,24 +3,52 @@ import { test, vi } from 'vitest';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { GeminiPayload } from '@floway-dev/protocols/gemini';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+const lastCandidatesCall: { model?: string } = {};
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
+  const { resolveAlias } = await import('../../model-aliases/resolve.ts');
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async (args: { modelName: string; upstreamIds: readonly string[] | null; scheduler: () => void }) => {
+      // Pull the queued alias resolution so the serve sees a resolved target id and overlays rules from `aliasResolution`.
+      const aliasResolution = await resolveAlias({
+        modelName: args.modelName,
+        providers: [],
+        fetcherForUpstream: () => directFetcher,
+        scheduler: args.scheduler,
+        endpointAccepts: () => true,
+        repo: { getByName: () => Promise.resolve(null) } as never,
+      });
+      const effectiveModel = aliasResolution?.targetModelId ?? args.modelName;
+      lastCandidatesCall.model = effectiveModel;
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('serve_test: no candidates enqueued');
+      return { ...next, failedUpstreams: [], aliasResolution };
+    }),
+  };
+});
+
+// Mock the alias resolver so the integration test can inject a resolution
+// without standing up the full per-request fetcher + registry stack.
+const aliasResolutionQueue: ({ targetModelId: string; rules: Record<string, unknown>; aliasName: string } | null | Error)[] = [];
+vi.mock('../../model-aliases/resolve.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../model-aliases/resolve.ts')>();
+  return {
+    ...original,
+    resolveAlias: vi.fn(async () => {
+      if (aliasResolutionQueue.length === 0) return null;
+      const next = aliasResolutionQueue.shift()!;
+      if (next instanceof Error) throw next;
       return next;
     }),
   };
@@ -47,6 +75,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
@@ -319,3 +348,57 @@ test('countTokens renders a Google RPC NOT_FOUND when no Messages-capable candid
   const upstreamError = expectType(result, 'api-error');
   assertEquals(upstreamError.status, 404);
 });
+
+test('alias resolution swaps the inbound model id for the target and overlays rules onto the Gemini IR', async () => {
+  installRepo();
+  aliasResolutionQueue.push({
+    targetModelId: 'gpt-5.4',
+    rules: { reasoning: { effort: 'high', budget_tokens: 1024 }, verbosity: 'low' },
+    aliasName: 'gemini-fast',
+  });
+  const callChatCompletions = vi.fn(async (): Promise<ProviderStreamResult<ChatCompletionsStreamEvent>> => ({
+    ok: true, events: makeProtocolFrames(makeChatCompletionsEvents()), modelKey: 'gpt-5.4', headers: new Headers(),
+  }));
+  queueCandidates([makeCandidate({ targetApi: 'chat-completions', callChatCompletions })]);
+
+  const payload = makePayload();
+  const result = await geminiServe.generate({
+    payload,
+    ctx: makeGatewayCtx(),
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    model: 'gemini-fast',
+    headers: new Headers(),
+  });
+  await collectEvents(expectType(result, 'events').events);
+
+  // The resolved target id, not the alias name, reaches candidate enumeration.
+  assertEquals(lastCandidatesCall.model, 'gpt-5.4');
+  // Alias rules land on the Gemini IR before the cross-protocol translation.
+  assertEquals(payload.generationConfig?.thinkingConfig?.thinkingLevel, 'high');
+  assertEquals(payload.generationConfig?.thinkingConfig?.thinkingBudget, 1024);
+  assertEquals(payload.generationConfig?.verbosity, 'low');
+});
+
+test('alias resolves to no routable target — renders the Gemini 404 envelope + stages x-floway-alias on the failure', async () => {
+  installRepo();
+  const { AliasNoTargetAvailableError } = await import('../../model-aliases/resolve.ts');
+  aliasResolutionQueue.push(new AliasNoTargetAvailableError({
+    aliasName: 'gemini-fast', targetCount: 2, allEndpointMismatch: false,
+  }));
+
+  const ctx = makeGatewayCtx();
+  const result = await geminiServe.generate({
+    payload: makePayload(),
+    ctx,
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    model: 'gemini-fast',
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'api-error');
+  if (result.type !== 'api-error') throw new Error('unreachable');
+  assertEquals(result.status, 404);
+  const body = JSON.parse(new TextDecoder().decode(result.body));
+  assert(body.error.message.includes("alias 'gemini-fast'"));
+  assertEquals(ctx.responseHeaders.get('x-floway-alias'), 'gemini-fast');
+});
diff --git a/packages/gateway/src/data-plane/chat/messages/attempt.ts b/packages/gateway/src/data-plane/chat/messages/attempt.ts
index 4e585eec4..64dc1f157 100644
--- a/packages/gateway/src/data-plane/chat/messages/attempt.ts
+++ b/packages/gateway/src/data-plane/chat/messages/attempt.ts
@@ -6,16 +6,16 @@ import { responsesAttempt } from '../responses/attempt.ts';
 import { rewriteStoredResponsesItemsForCandidate } from '../responses/items/rewrite.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
 import { providerStreamResultToExecuteResult, buildUpstreamCallOptions } from '../shared/attempt-helpers.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import { tryCatchChatServeFailure } from '../shared/errors.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import { plainResultFromResponse } from '../shared/respond.ts';
+import { sanitizeForMessagesUpstream, createSanitizeTraceCtx } from '../shared/sanitize.ts';
 import { traverseTranslation } from '../shared/translate-traverse.ts';
 import { createUpstreamLatencyRecorder } from '../shared/upstream-telemetry.ts';
 import { runInterceptors } from '@floway-dev/interceptor';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesMessage, MessagesPayload, MessagesStreamEvent } from '@floway-dev/protocols/messages';
-import { type ExecuteResult, type PlainResult } from '@floway-dev/provider';
+import { type ExecuteResult, type PlainResult, type ProviderCandidate } from '@floway-dev/provider';
 import { translateMessagesViaChatCompletions, translateMessagesViaResponses } from '@floway-dev/translate';
 import { messagesViaResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
@@ -48,6 +48,7 @@ export const messagesAttempt = {
     return await runInterceptors(invocation, ctx, messagesInterceptors, async () => {
       if (candidate.targetApi === 'messages') {
         const { model: _model, ...body } = invocation.payload;
+        sanitizeForMessagesUpstream(body as Record<string, unknown>, createSanitizeTraceCtx());
         const recorder = createUpstreamLatencyRecorder();
         const providerResult = await candidate.binding.provider.callMessages(
           candidate.binding.upstreamModel,
@@ -98,6 +99,7 @@ export const messagesAttempt = {
     const recorder = createUpstreamLatencyRecorder();
     const response = await runInterceptors(invocation, ctx, messagesCountTokensInterceptors, async () => {
       const { model: _model, ...body } = invocation.payload;
+      sanitizeForMessagesUpstream(body as Record<string, unknown>, createSanitizeTraceCtx());
       const { response } = await candidate.binding.provider.callMessagesCountTokens(
         candidate.binding.upstreamModel,
         body,
diff --git a/packages/gateway/src/data-plane/chat/messages/attempt_test.ts b/packages/gateway/src/data-plane/chat/messages/attempt_test.ts
index d63961209..53d6f471d 100644
--- a/packages/gateway/src/data-plane/chat/messages/attempt_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/attempt_test.ts
@@ -4,13 +4,12 @@ import { messagesAttempt } from './attempt.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesPayload, MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assertEquals, assertExists, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_messages_attempt_test';
@@ -22,6 +21,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/messages/errors.ts b/packages/gateway/src/data-plane/chat/messages/errors.ts
index 6881616ec..7bb260396 100644
--- a/packages/gateway/src/data-plane/chat/messages/errors.ts
+++ b/packages/gateway/src/data-plane/chat/messages/errors.ts
@@ -38,5 +38,7 @@ export const renderMessagesFailure = (
     return anthropicErrorResult(404, 'not_found_error', appendFailedUpstreams(`Model ${failure.model} is not available on any configured upstream.`, failure.failedUpstreams));
   case 'model-unsupported':
     return anthropicErrorResult(400, 'invalid_request_error', appendFailedUpstreams(`Model ${failure.model} does not support the ${endpointPath} endpoint.`, failure.failedUpstreams));
+  case 'alias-no-target-available':
+    return anthropicErrorResult(404, 'not_found_error', failure.message);
   }
 };
diff --git a/packages/gateway/src/data-plane/chat/messages/http.ts b/packages/gateway/src/data-plane/chat/messages/http.ts
index 8dfc4dc6e..b138a9ccf 100644
--- a/packages/gateway/src/data-plane/chat/messages/http.ts
+++ b/packages/gateway/src/data-plane/chat/messages/http.ts
@@ -3,7 +3,7 @@ import { messagesServe } from './serve.ts';
 import type { AuthedContext } from '../../../middleware/auth.ts';
 import { inboundHeadersForUpstream } from '../../shared/inbound-headers.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import { createGatewayCtxFromHono, type GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse, type GatewayCtx } from '../shared/gateway-ctx.ts';
 import { readRequestBody, type RequestBody } from '../shared/request-body.ts';
 import { providerModelsUnavailableResponse } from '../shared/upstream-models-error.ts';
 import type { MessagesPayload } from '@floway-dev/protocols/messages';
@@ -44,7 +44,7 @@ const respondWithInternalError = async (c: AuthedContext, error: unknown, reques
   const effectiveCtx = ctx ?? createGatewayCtxFromHono(c, { wantsStream: false, requestBody });
   const result = internalErrorResult(502, toInternalDebugError(error));
   const { response } = await respondMessages(c, result, false, effectiveCtx);
-  return (effectiveCtx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(effectiveCtx, response);
 };
 
 const parsePayload = (requestBody: RequestBody): MessagesPayload =>
@@ -64,7 +64,7 @@ export const messagesHttp = {
       const store = createNonResponsesSourceStore(ctx.apiKeyId);
       const result = await messagesServe.generate({ payload, ctx, store, headers: inboundHeadersForUpstream(c) });
       const { response } = await respondMessages(c, result, wantsStream, ctx);
-      return (ctx.dump?.finalize(response) ?? response);
+      return finalizeGatewayResponse(ctx, response);
     } catch (error) {
       return await respondWithInternalError(c, error, requestBody, ctx);
     }
@@ -82,7 +82,7 @@ export const messagesHttp = {
       const store = createNonResponsesSourceStore(ctx.apiKeyId);
       const result = await messagesServe.countTokens({ payload, ctx, store, headers: inboundHeadersForUpstream(c) });
       const { response } = await respondMessages(c, result, false, ctx);
-      return (ctx.dump?.finalize(response) ?? response);
+      return finalizeGatewayResponse(ctx, response);
     } catch (error) {
       return await respondWithInternalError(c, error, requestBody, ctx);
     }
diff --git a/packages/gateway/src/data-plane/chat/messages/http_test.ts b/packages/gateway/src/data-plane/chat/messages/http_test.ts
index 844a05177..89fd82416 100644
--- a/packages/gateway/src/data-plane/chat/messages/http_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/http_test.ts
@@ -5,21 +5,20 @@ import type { AuthVars } from '../../../middleware/auth.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { ApiKey, User } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
-import { directFetcher, type ProviderCallResult, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderStreamResult, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async () => {
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('http_test: no candidates enqueued');
-      return next;
+      return { ...next, failedUpstreams: [], aliasResolution: null };
     }),
   };
 });
diff --git a/packages/gateway/src/data-plane/chat/messages/interceptors/demote-interleaved-system-to-user_test.ts b/packages/gateway/src/data-plane/chat/messages/interceptors/demote-interleaved-system-to-user_test.ts
index 7fcb07153..2980c1653 100644
--- a/packages/gateway/src/data-plane/chat/messages/interceptors/demote-interleaved-system-to-user_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/interceptors/demote-interleaved-system-to-user_test.ts
@@ -15,6 +15,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/messages/interceptors/disable-reasoning-on-forced-tool-choice_test.ts b/packages/gateway/src/data-plane/chat/messages/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
index 7ed0ca556..3a62c0111 100644
--- a/packages/gateway/src/data-plane/chat/messages/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
@@ -15,6 +15,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/messages/interceptors/strip-billing-attribution_test.ts b/packages/gateway/src/data-plane/chat/messages/interceptors/strip-billing-attribution_test.ts
index 3c74ea4a9..a853330ba 100644
--- a/packages/gateway/src/data-plane/chat/messages/interceptors/strip-billing-attribution_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/interceptors/strip-billing-attribution_test.ts
@@ -15,6 +15,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/messages/interceptors/web-search-shim_test.ts b/packages/gateway/src/data-plane/chat/messages/interceptors/web-search-shim_test.ts
index 27c5cad83..eb20ac927 100644
--- a/packages/gateway/src/data-plane/chat/messages/interceptors/web-search-shim_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/interceptors/web-search-shim_test.ts
@@ -57,6 +57,7 @@ const gatewayCtx = (apiKeyId: string = 'test-key'): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/messages/respond_test.ts b/packages/gateway/src/data-plane/chat/messages/respond_test.ts
index dfd3b10e3..fc945bc6c 100644
--- a/packages/gateway/src/data-plane/chat/messages/respond_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/respond_test.ts
@@ -537,6 +537,7 @@ const makeRespondCtx = (): GatewayCtx => ({
   requestStartedAt: 0,
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
 });
 
 const messagesEventsForRespond = (): readonly MessagesStreamEvent[] => [
diff --git a/packages/gateway/src/data-plane/chat/messages/routing.ts b/packages/gateway/src/data-plane/chat/messages/routing.ts
index d6de52107..5582aba37 100644
--- a/packages/gateway/src/data-plane/chat/messages/routing.ts
+++ b/packages/gateway/src/data-plane/chat/messages/routing.ts
@@ -1,8 +1,8 @@
 import { classifyResponsesItemAffinity } from '../responses/items/affinity.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { RoutingDecision } from '../shared/routing.ts';
 import type { MessagesPayload } from '@floway-dev/protocols/messages';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import { messagesViaResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 export type MessagesRoutingDecision = RoutingDecision;
diff --git a/packages/gateway/src/data-plane/chat/messages/routing_test.ts b/packages/gateway/src/data-plane/chat/messages/routing_test.ts
index eb11bb289..fbacd17c2 100644
--- a/packages/gateway/src/data-plane/chat/messages/routing_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/routing_test.ts
@@ -5,9 +5,8 @@ import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createStoredResponsesItemId } from '../responses/items/format.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { MessagesPayload } from '@floway-dev/protocols/messages';
-import { directFetcher } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate } from '@floway-dev/provider';
 import { stubProvider, stubUpstreamModel, assertEquals } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_messages_routing_test';
diff --git a/packages/gateway/src/data-plane/chat/messages/serve.ts b/packages/gateway/src/data-plane/chat/messages/serve.ts
index ae9bb5d6c..48ded7408 100644
--- a/packages/gateway/src/data-plane/chat/messages/serve.ts
+++ b/packages/gateway/src/data-plane/chat/messages/serve.ts
@@ -1,8 +1,9 @@
 import { messagesAttempt } from './attempt.ts';
 import { renderMessagesFailure } from './errors.ts';
 import { planMessagesRouting } from './routing.ts';
+import { applyChatRulesToMessages } from '../../model-aliases/apply.ts';
+import { resolveCandidatesAndApplyAlias } from '../../model-aliases/prelude.ts';
 import type { StatefulResponsesStore } from '../responses/items/store.ts';
-import { enumerateProviderCandidates } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesPayload, MessagesStreamEvent } from '@floway-dev/protocols/messages';
@@ -22,20 +23,27 @@ export interface MessagesServeCountTokensArgs {
   readonly headers: Headers;
 }
 
+const applyAlias = (payload: MessagesPayload) => (resolution: { targetModelId: string; rules: Parameters<typeof applyChatRulesToMessages>[1] }) => {
+  payload.model = resolution.targetModelId;
+  applyChatRulesToMessages(payload, resolution.rules);
+};
+
 export const messagesServe = {
   generate: async (args: MessagesServeGenerateArgs): Promise<ExecuteResult<ProtocolFrame<MessagesStreamEvent>>> => {
     const { payload, ctx, store, headers } = args;
-    const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-      upstreamIds: ctx.upstreamIds,
-      model: payload.model,
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: payload.model,
       pickTarget: endpoints =>
         endpoints.messages ? 'messages'
           : endpoints.responses ? 'responses'
             : endpoints.chatCompletions ? 'chat-completions'
               : null,
-      scheduler: ctx.backgroundScheduler,
-      currentColo: ctx.currentColo,
+      applyAlias: applyAlias(payload),
+      renderAliasFailure: failure => renderMessagesFailure(failure, 'generate'),
     });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams } = resolved;
     const decision = await planMessagesRouting({ payload, candidates, store });
     if (decision.kind === 'failure') return renderMessagesFailure(decision.failure, 'generate');
 
@@ -57,13 +65,15 @@ export const messagesServe = {
 
   countTokens: async (args: MessagesServeCountTokensArgs): Promise<ExecuteResult<ProtocolFrame<MessagesStreamEvent>> | PlainResult> => {
     const { payload, ctx, store, headers } = args;
-    const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-      upstreamIds: ctx.upstreamIds,
-      model: payload.model,
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: payload.model,
       pickTarget: endpoints => endpoints.messages ? 'messages' : null,
-      scheduler: ctx.backgroundScheduler,
-      currentColo: ctx.currentColo,
+      applyAlias: applyAlias(payload),
+      renderAliasFailure: failure => renderMessagesFailure(failure, 'countTokens'),
     });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams } = resolved;
     const decision = await planMessagesRouting({ payload, candidates, store });
     if (decision.kind === 'failure') return renderMessagesFailure(decision.failure, 'countTokens');
 
diff --git a/packages/gateway/src/data-plane/chat/messages/serve_test.ts b/packages/gateway/src/data-plane/chat/messages/serve_test.ts
index ed6f0b507..cbfff3fb8 100644
--- a/packages/gateway/src/data-plane/chat/messages/serve_test.ts
+++ b/packages/gateway/src/data-plane/chat/messages/serve_test.ts
@@ -3,22 +3,50 @@ import { test, vi } from 'vitest';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import { createNonResponsesSourceStore } from '../responses/items/store.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesPayload, MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { defaultsForProvider, directFetcher, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { defaultsForProvider, directFetcher, type ProviderCallResult, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+const lastCandidatesCall: { model?: string } = {};
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
+  const { resolveAlias } = await import('../../model-aliases/resolve.ts');
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async (args: { modelName: string; upstreamIds: readonly string[] | null; scheduler: () => void }) => {
+      // Pull the queued alias resolution so the serve sees a resolved target id and overlays rules from `aliasResolution`.
+      const aliasResolution = await resolveAlias({
+        modelName: args.modelName,
+        providers: [],
+        fetcherForUpstream: () => directFetcher,
+        scheduler: args.scheduler,
+        endpointAccepts: () => true,
+        repo: { getByName: () => Promise.resolve(null) } as never,
+      });
+      const effectiveModel = aliasResolution?.targetModelId ?? args.modelName;
+      lastCandidatesCall.model = effectiveModel;
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('serve_test: no candidates enqueued');
+      return { ...next, failedUpstreams: [], aliasResolution };
+    }),
+  };
+});
+
+// Mock the alias resolver so the integration test can inject a resolution
+// without standing up the full per-request fetcher + registry stack.
+const aliasResolutionQueue: ({ targetModelId: string; rules: Record<string, unknown>; aliasName: string } | null | Error)[] = [];
+vi.mock('../../model-aliases/resolve.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../model-aliases/resolve.ts')>();
+  return {
+    ...original,
+    resolveAlias: vi.fn(async () => {
+      if (aliasResolutionQueue.length === 0) return null;
+      const next = aliasResolutionQueue.shift()!;
+      if (next instanceof Error) throw next;
       return next;
     }),
   };
@@ -45,6 +73,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
@@ -434,3 +463,59 @@ test('copilot binding strips x-anthropic-billing-header system block via the def
   assertEquals(observed.system.length, 1);
   assertEquals(observed.system[0].text, 'You are a helpful assistant.');
 });
+
+test('alias resolution swaps the inbound model id for the target and overlays rules onto the Messages IR', async () => {
+  installRepo();
+  aliasResolutionQueue.push({
+    targetModelId: 'claude-opus-4-7',
+    rules: { reasoning: { effort: 'high', budget_tokens: 2048 }, serviceTier: 'fast' },
+    aliasName: 'claude-fast',
+  });
+  const capturedBodies: MessagesPayload[] = [];
+  const callMessages = vi.fn(async (_model: unknown, body: unknown): Promise<ProviderStreamResult<MessagesStreamEvent>> => {
+    capturedBodies.push({ ...(body as Omit<MessagesPayload, 'model'>), model: 'claude-opus-4-7' });
+    return { ok: true, events: makeProtocolFrames(makeMessagesResultEvents()), modelKey: 'claude-opus-4-7' };
+  });
+  queueCandidates([makeCandidate({ upstream: 'up_cf', callMessages })]);
+
+  const result = await messagesServe.generate({
+    payload: makePayload({ model: 'claude-fast' }),
+    ctx: makeGatewayCtx(),
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    headers: new Headers(),
+  });
+
+  await collectEvents(assertResultType(result, 'events').events);
+
+  assertEquals(lastCandidatesCall.model, 'claude-opus-4-7');
+  const observed = capturedBodies[0]!;
+  assertEquals(observed.output_config?.effort, 'high');
+  assertEquals(observed.thinking?.budget_tokens, 2048);
+  // The serviceTier=fast → speed=fast bridge lands the alias rule on
+  // Anthropic's native Fast Mode field.
+  assertEquals(observed.speed, 'fast');
+});
+
+test('alias resolves to no routable target — renders the Messages 404 envelope + stages x-floway-alias on the failure', async () => {
+  installRepo();
+  const { AliasNoTargetAvailableError } = await import('../../model-aliases/resolve.ts');
+  aliasResolutionQueue.push(new AliasNoTargetAvailableError({
+    aliasName: 'claude-fast', targetCount: 2, allEndpointMismatch: false,
+  }));
+
+  const ctx = makeGatewayCtx();
+  const result = await messagesServe.generate({
+    payload: makePayload({ model: 'claude-fast' }),
+    ctx,
+    store: createNonResponsesSourceStore(API_KEY_ID),
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'api-error');
+  if (result.type !== 'api-error') throw new Error('unreachable');
+  assertEquals(result.status, 404);
+  const body = JSON.parse(new TextDecoder().decode(result.body));
+  assertEquals(body.error.type, 'not_found_error');
+  assert(body.error.message.includes("alias 'claude-fast'"));
+  assertEquals(ctx.responseHeaders.get('x-floway-alias'), 'claude-fast');
+});
diff --git a/packages/gateway/src/data-plane/chat/responses/attempt.ts b/packages/gateway/src/data-plane/chat/responses/attempt.ts
index d3f2fbebd..d75e492a2 100644
--- a/packages/gateway/src/data-plane/chat/responses/attempt.ts
+++ b/packages/gateway/src/data-plane/chat/responses/attempt.ts
@@ -10,16 +10,16 @@ import { recordPerformanceLatency, requireRecordedDurationMs } from '../../share
 import { chatCompletionsAttempt } from '../chat-completions/attempt.ts';
 import { messagesAttempt } from '../messages/attempt.ts';
 import { providerStreamResultToExecuteResult, buildUpstreamCallOptions, telemetryModelIdentity } from '../shared/attempt-helpers.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import { tryCatchChatServeFailure } from '../shared/errors.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createSanitizeTraceCtx, sanitizeForResponsesUpstream } from '../shared/sanitize.ts';
 import { traverseTranslation } from '../shared/translate-traverse.ts';
 import { createUpstreamLatencyRecorder, recordUpstreamHttpFailure, upstreamPerformanceContext } from '../shared/upstream-telemetry.ts';
 import { runInterceptors } from '@floway-dev/interceptor';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
 import { collectResponsesProtocolEventsToResult } from '@floway-dev/protocols/responses';
 import { type ResponsesPayload, type ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { eventResult, readUpstreamApiError, type ExecuteResult, type ProviderResponsesResult, type ResponsesAction } from '@floway-dev/provider';
+import { eventResult, readUpstreamApiError, type ExecuteResult, type ProviderCandidate, type ProviderResponsesResult, type ResponsesAction } from '@floway-dev/provider';
 import { translateResponsesViaChatCompletions, translateResponsesViaMessages } from '@floway-dev/translate';
 
 export interface ResponsesAttemptInvokeArgs {
@@ -203,6 +203,7 @@ const dispatchResponses = async (
       // provider can decide for itself (every provider's streaming call
       // forces stream=true anyway).
       const { model: _model, stream: _stream, store: _store, ...body } = invocation.payload;
+      sanitizeForResponsesUpstream(body as Record<string, unknown>, createSanitizeTraceCtx());
       const providerResult = await candidate.binding.provider.callResponses(
         candidate.binding.upstreamModel,
         body,
@@ -213,6 +214,7 @@ const dispatchResponses = async (
       return await providerResponsesResultToExecuteResult(providerResult, candidate, ctx, recorder);
     }
     const { model: _model, ...body } = invocation.payload;
+    sanitizeForResponsesUpstream(body as Record<string, unknown>, createSanitizeTraceCtx());
     const providerResult = await candidate.binding.provider.callResponses(
       candidate.binding.upstreamModel,
       body,
diff --git a/packages/gateway/src/data-plane/chat/responses/attempt_test.ts b/packages/gateway/src/data-plane/chat/responses/attempt_test.ts
index 15f6f376a..d80eddf7d 100644
--- a/packages/gateway/src/data-plane/chat/responses/attempt_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/attempt_test.ts
@@ -7,12 +7,11 @@ import { createResponsesHttpStore } from './items/store.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { StoredResponsesItem } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesPayload, ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions, type UpstreamModel } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions, type UpstreamModel } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_attempt_test';
@@ -24,6 +23,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/responses/errors.ts b/packages/gateway/src/data-plane/chat/responses/errors.ts
index 215f218a0..86c880131 100644
--- a/packages/gateway/src/data-plane/chat/responses/errors.ts
+++ b/packages/gateway/src/data-plane/chat/responses/errors.ts
@@ -34,5 +34,7 @@ export const renderResponsesFailure = (
     return openAiErrorResult(404, appendFailedUpstreams(`Model ${failure.model} is not available on any configured upstream.`, failure.failedUpstreams));
   case 'model-unsupported':
     return openAiErrorResult(400, appendFailedUpstreams(`Model ${failure.model} does not support the /responses endpoint.`, failure.failedUpstreams));
+  case 'alias-no-target-available':
+    return openAiErrorResult(404, failure.message);
   }
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/http.ts b/packages/gateway/src/data-plane/chat/responses/http.ts
index a38ee3866..ccaa3ffb4 100644
--- a/packages/gateway/src/data-plane/chat/responses/http.ts
+++ b/packages/gateway/src/data-plane/chat/responses/http.ts
@@ -3,29 +3,13 @@ import { respondResponses } from './respond.ts';
 import { PreviousResponseNotFoundError } from './serve-prep.ts';
 import { responsesServe } from './serve.ts';
 import type { AuthedContext } from '../../../middleware/auth.ts';
-import { CODEX_AUTO_REVIEW_ALIAS, CODEX_AUTO_REVIEW_TARGET } from '../../codex/auto-review-alias.ts';
 import { inboundHeadersForUpstream } from '../../shared/inbound-headers.ts';
-import { createGatewayCtxFromHono, type GatewayCtx } from '../shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse, type GatewayCtx } from '../shared/gateway-ctx.ts';
 import { readRequestBody, type RequestBody } from '../shared/request-body.ts';
 import { providerModelsUnavailableResponse } from '../shared/upstream-models-error.ts';
 import type { ResponsesPayload } from '@floway-dev/protocols/responses';
 import { internalErrorResult, toInternalDebugError } from '@floway-dev/provider';
 
-// Codex sends auto-review requests over the Responses wire API as a
-// `codex-auto-review` model id; rewrite at the entry so downstream routing,
-// performance telemetry, and usage accounting all see the real model name
-// (and the `low` reasoning effort the alias implies — generate only;
-// compact carries no `reasoning` field).
-const rewriteResponsesEntryModelAlias = (payload: ResponsesPayload, stampReasoningEffort: boolean): ResponsesPayload => {
-  if (payload.model !== CODEX_AUTO_REVIEW_ALIAS) return payload;
-  if (!stampReasoningEffort) return { ...payload, model: CODEX_AUTO_REVIEW_TARGET };
-  return {
-    ...payload,
-    model: CODEX_AUTO_REVIEW_TARGET,
-    reasoning: { ...(payload.reasoning ?? {}), effort: 'low' },
-  };
-};
-
 // OpenAI's verbatim previous_response_not_found envelope. Codex compares this
 // body byte-for-byte against upstream — see the cross-references on
 // `PreviousResponseNotFoundError` in serve-prep.ts.
@@ -57,29 +41,29 @@ const respondWithInternalError = async (c: AuthedContext, error: unknown, reques
   const effectiveCtx = ctx ?? createGatewayCtxFromHono(c, { wantsStream: false, requestBody });
   const result = internalErrorResult(502, toInternalDebugError(error));
   const { response } = await respondResponses(c, result, false, effectiveCtx);
-  return (effectiveCtx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(effectiveCtx, response);
 };
 
-const parsePayload = (requestBody: RequestBody, stampReasoningEffort: boolean): ResponsesPayload =>
-  rewriteResponsesEntryModelAlias(JSON.parse(new TextDecoder().decode(requestBody.bytes)) as ResponsesPayload, stampReasoningEffort);
+const parsePayload = (requestBody: RequestBody): ResponsesPayload =>
+  JSON.parse(new TextDecoder().decode(requestBody.bytes)) as ResponsesPayload;
 
 export const responsesHttp = {
   generate: async (c: AuthedContext): Promise<Response> => {
     const requestBody = await readRequestBody(c);
     let ctx: GatewayCtx | undefined;
     try {
-      const payload = parsePayload(requestBody, true);
+      const payload = parsePayload(requestBody);
       const wantsStream = payload.stream === true;
       ctx = createGatewayCtxFromHono(c, { wantsStream, requestBody, model: payload.model });
       const store = createResponsesHttpStore(ctx.apiKeyId, payload.store ?? undefined);
       const result = await responsesServe.generate({ payload, ctx, store, headers: inboundHeadersForUpstream(c) });
       const { response } = await respondResponses(c, result, wantsStream, ctx);
-      return (ctx.dump?.finalize(response) ?? response);
+      return finalizeGatewayResponse(ctx, response);
     } catch (error) {
       if (error instanceof PreviousResponseNotFoundError) {
         const response = previousResponseNotFoundResponse(error.previousResponseId);
         ctx?.dump?.error('gateway');
-        return (ctx?.dump?.finalize(response) ?? response);
+        return ctx ? finalizeGatewayResponse(ctx, response) : response;
       }
       return await respondWithInternalError(c, error, requestBody, ctx);
     }
@@ -89,22 +73,22 @@ export const responsesHttp = {
     const requestBody = await readRequestBody(c);
     let ctx: GatewayCtx | undefined;
     try {
-      const payload = parsePayload(requestBody, false);
+      const payload = parsePayload(requestBody);
       ctx = createGatewayCtxFromHono(c, { wantsStream: false, requestBody, model: payload.model });
       const store = createResponsesHttpStore(ctx.apiKeyId, payload.store ?? undefined);
       const result = await responsesServe.compact({ payload, ctx, store, headers: inboundHeadersForUpstream(c) });
       if (result.type === 'result') {
         ctx.dump?.success(result.modelIdentity, result.usage);
         const compactResponse = Response.json(result.result);
-        return (ctx.dump?.finalize(compactResponse) ?? compactResponse);
+        return finalizeGatewayResponse(ctx, compactResponse);
       }
       const { response } = await respondResponses(c, result, false, ctx);
-      return (ctx.dump?.finalize(response) ?? response);
+      return finalizeGatewayResponse(ctx, response);
     } catch (error) {
       if (error instanceof PreviousResponseNotFoundError) {
         const response = previousResponseNotFoundResponse(error.previousResponseId);
         ctx?.dump?.error('gateway');
-        return (ctx?.dump?.finalize(response) ?? response);
+        return ctx ? finalizeGatewayResponse(ctx, response) : response;
       }
       return await respondWithInternalError(c, error, requestBody, ctx);
     }
diff --git a/packages/gateway/src/data-plane/chat/responses/http_test.ts b/packages/gateway/src/data-plane/chat/responses/http_test.ts
index bd612fa6a..f4c205b93 100644
--- a/packages/gateway/src/data-plane/chat/responses/http_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/http_test.ts
@@ -6,25 +6,49 @@ import type { AuthVars } from '../../../middleware/auth.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { ApiKey, StoredResponsesItem, User } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
-import type { ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderResponsesResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import type { ResponsesPayload, ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
+import { directFetcher, type ProviderCandidate, type ProviderResponsesResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
 // Mock the candidates seam so each test hands the http entry exactly the
-// provider candidates it wants. Mirrors the pattern from serve_test.ts.
+// provider candidates it wants, with an optional queued alias resolution.
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-const seenModels: string[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+const lastSeenModel: { value: string | null } = { value: null };
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
+  const { resolveAlias } = await import('../../model-aliases/resolve.ts');
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async (args: { model: string }) => {
-      seenModels.push(args.model);
+    resolveModelCandidates: vi.fn(async (args: { modelName: string; scheduler: () => void }) => {
+      const aliasResolution = await resolveAlias({
+        modelName: args.modelName,
+        providers: [],
+        fetcherForUpstream: () => directFetcher,
+        scheduler: args.scheduler,
+        endpointAccepts: () => true,
+        repo: { getByName: () => Promise.resolve(null) } as never,
+      });
+      lastSeenModel.value = aliasResolution?.targetModelId ?? args.modelName;
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('http_test: no candidates enqueued');
-      return next;
+      return { ...next, failedUpstreams: [], aliasResolution };
+    }),
+  };
+});
+
+// Mock the alias resolver so the alias-rewrite tests can inject a resolution
+// without standing up the per-request fetcher + registry stack the routability
+// pool needs. Tests that don't enqueue a resolution see the default
+// (`null` = no alias matched).
+const aliasResolutionQueue: ({ targetModelId: string; rules: Record<string, unknown>; aliasName: string } | null)[] = [];
+vi.mock('../../model-aliases/resolve.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../model-aliases/resolve.ts')>();
+  return {
+    ...original,
+    resolveAlias: vi.fn(async () => {
+      if (aliasResolutionQueue.length === 0) return null;
+      return aliasResolutionQueue.shift()!;
     }),
   };
 });
@@ -282,12 +306,21 @@ test('POST /v1/responses renders a routing-unavailable 400 when a forcing item n
   assertEquals(body.error.code, 'responses_item_routing_unavailable');
 });
 
-test('POST /v1/responses rewrites the codex-auto-review alias before routing', async () => {
+const seedCodexAutoReviewAliasResolution = (): void => {
+  aliasResolutionQueue.push({
+    targetModelId: 'gpt-5.4',
+    rules: { reasoning: { effort: 'low' } },
+    aliasName: 'codex-auto-review',
+  });
+};
+
+test('POST /v1/responses routes a codex-auto-review request through the seeded alias: rewrites the model to gpt-5.4 and stamps reasoning.effort=low', async () => {
   installRepo();
-  seenModels.length = 0;
-  const observedBodies: { reasoning?: { effort?: string } }[] = [];
+  seedCodexAutoReviewAliasResolution();
+  lastSeenModel.value = null;
+  const observedBodies: ResponsesPayload[] = [];
   const callResponses = vi.fn(async (_model: unknown, body: unknown): Promise<ProviderResponsesResult> => {
-    observedBodies.push(body as { reasoning?: { effort?: string } });
+    observedBodies.push(body as ResponsesPayload);
     return {
       action: 'generate', ok: true,
       events: makeProviderEvents([completedEvent()]),
@@ -300,20 +333,21 @@ test('POST /v1/responses rewrites the codex-auto-review alias before routing', a
   const response = await makeApp().request('/v1/responses', {
     method: 'POST',
     headers: new Headers({ 'content-type': 'application/json' }),
-    body: JSON.stringify({ model: 'codex-auto-review', input: 'hello' }),
+    body: JSON.stringify({ model: 'codex-auto-review', input: 'hello', stream: true }),
   });
 
   assertEquals(response.status, 200);
-  assertEquals(seenModels, ['gpt-5.4']);
+  assertEquals(lastSeenModel.value, 'gpt-5.4');
   const observed = observedBodies[0];
   if (observed === undefined) throw new Error('expected callResponses to receive a body');
   assertEquals(observed.reasoning?.effort, 'low');
 });
 
-test('POST /v1/responses/compact rewrites the codex-auto-review alias to gpt-5.4 with no reasoning field', async () => {
+test('POST /v1/responses/compact routes a codex-auto-review request through the seeded alias: rewrites the model to gpt-5.4 and stamps reasoning.effort=low (the alias rule overlays the compact body too)', async () => {
   installRepo();
-  seenModels.length = 0;
-  const observedBodies: { reasoning?: unknown }[] = [];
+  seedCodexAutoReviewAliasResolution();
+  lastSeenModel.value = null;
+  const observedBodies: ResponsesPayload[] = [];
   const compactionItem = { type: 'compaction' as const, id: 'cmp_1', encrypted_content: 'ENC' };
   const compactionResult: ResponsesResult = {
     ...makeResponsesResult(),
@@ -322,7 +356,7 @@ test('POST /v1/responses/compact rewrites the codex-auto-review alias to gpt-5.4
   };
   const callResponses = vi.fn(async (_model: unknown, body: unknown, action: ResponsesAction): Promise<ProviderResponsesResult> => {
     if (action !== 'compact') throw new Error(`expected compact, got ${action}`);
-    observedBodies.push(body as { reasoning?: unknown });
+    observedBodies.push(body as ResponsesPayload);
     return { action: 'compact', ok: true, result: compactionResult, modelKey: 'test-model-key' };
   });
   queueCandidates([makeCandidate({ callResponses })]);
@@ -337,8 +371,8 @@ test('POST /v1/responses/compact rewrites the codex-auto-review alias to gpt-5.4
   });
 
   assertEquals(response.status, 200);
-  assertEquals(seenModels, ['gpt-5.4']);
+  assertEquals(lastSeenModel.value, 'gpt-5.4');
   const observed = observedBodies[0];
   if (observed === undefined) throw new Error('expected callResponses to receive a body');
-  assertEquals(observed.reasoning, undefined);
+  assertEquals(observed.reasoning?.effort, 'low');
 });
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/canonicalize-output-items_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/canonicalize-output-items_test.ts
index 6ddf17ff6..e19eb9bd5 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/canonicalize-output-items_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/canonicalize-output-items_test.ts
@@ -18,6 +18,7 @@ const stubCtx: GatewayCtx = {
   dump: null,
   backgroundScheduler: () => {},
   requestStartedAt: 0,
+  responseHeaders: new Headers(),
 };
 
 const invocation = (): ResponsesInvocation => ({
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/demote-developer-to-system_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/demote-developer-to-system_test.ts
index cd04a23d5..f28d4e006 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/demote-developer-to-system_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/demote-developer-to-system_test.ts
@@ -16,6 +16,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/demote-interleaved-system-to-user_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/demote-interleaved-system-to-user_test.ts
index 295ccdb06..c6e1e2eea 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/demote-interleaved-system-to-user_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/demote-interleaved-system-to-user_test.ts
@@ -16,6 +16,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/disable-reasoning-on-forced-tool-choice_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
index f82024a14..f2fbe56e7 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/disable-reasoning-on-forced-tool-choice_test.ts
@@ -16,6 +16,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/retry-cyber-policy_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/retry-cyber-policy_test.ts
index 696dcbade..fdbc7bb08 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/retry-cyber-policy_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/retry-cyber-policy_test.ts
@@ -45,6 +45,7 @@ const stubCtx = (overrides: { abortSignal?: AbortSignal } = {}): GatewayCtx => (
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
   ...overrides,
@@ -159,6 +160,7 @@ const performanceFor = (modelKey: string) => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
 });
 
 const upstreamCyberPolicyError = (message: string): ExecuteResult<ProtocolFrame<ResponsesStreamEvent>> => ({
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tool-shim_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tool-shim_test.ts
index 218727c9a..8a0fee2a6 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tool-shim_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tool-shim_test.ts
@@ -348,6 +348,7 @@ const makeGatewayCtx = (apiKeyId: string = 'k1'): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
@@ -4496,6 +4497,7 @@ test('downstream AbortSignal threads through to provider search / fetchPage and
     runtimeLocation: 'TEST',
     currentColo: 'TEST',
     dump: null,
+    responseHeaders: new Headers(),
     backgroundScheduler: () => {},
     requestStartedAt: 0,
     abortSignal: controller.signal,
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation-integration_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation-integration_test.ts
index bbe8d1a64..82484e621 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation-integration_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation-integration_test.ts
@@ -30,13 +30,8 @@ interface BackendStub {
 const stub = vi.hoisted((): BackendStub => ({ generationsCalls: [], editsForms: [], nextGenerations: [], nextEdits: [] }));
 
 vi.mock('../../../../providers/registry.ts', () => ({
-  resolveModelForRequest: vi.fn(async () => ({
-    matches: [{
-      id: 'gpt-image-2',
-      model: {
-        id: 'gpt-image-2',
-        endpoints: { imagesGenerations: {}, imagesEdits: {} },
-      },
+  resolveModelCandidates: vi.fn(async () => ({
+    candidates: [{
       binding: {
         upstream: 'u',
         upstreamModel: { id: 'gpt-image-2', endpoints: { imagesGenerations: {}, imagesEdits: {} } },
@@ -56,8 +51,11 @@ vi.mock('../../../../providers/registry.ts', () => ({
           },
         },
       },
+      fetcher: directFetcher,
     }],
+    sawModel: true,
     failedUpstreams: [],
+    aliasResolution: null,
   })),
 }));
 
@@ -144,6 +142,7 @@ const gatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation.ts
index a66fe9995..229363cf7 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation.ts
@@ -1,6 +1,5 @@
-import { createPerRequestFetcher } from '../../../../../dial/per-request.ts';
 import { sleep } from '../../../../../shared/sleep.ts';
-import { resolveModelForRequest } from '../../../../providers/registry.ts';
+import { resolveModelCandidates } from '../../../../providers/registry.ts';
 import { appendFailedUpstreams } from '../../../../shared/failed-upstreams.ts';
 import { createUpstreamLatencyRecorder, recordPerformanceError, recordPerformanceLatency, requireRecordedDurationMs } from '../../../../shared/telemetry/performance.ts';
 import { recordTokenUsage, tokenUsageFromImagesBody } from '../../../../shared/telemetry/usage.ts';
@@ -529,18 +528,23 @@ const serverError = (e: unknown): ImageError => ({
 const resolveImageBinding = async (
   isEdit: boolean,
   state: ShimState,
-  fetcherForUpstream: (upstreamId: string) => Fetcher,
-): Promise<{ ok: true; binding: ProviderModelRecord } | { ok: false; error: ImageError }> => {
+): Promise<{ ok: true; binding: ProviderModelRecord; fetcher: Fetcher } | { ok: false; error: ImageError }> => {
   const endpointKey = isEdit ? 'imagesEdits' : 'imagesGenerations';
   const endpointPath = isEdit ? '/images/edits' : '/images/generations';
   let resolution;
   try {
-    resolution = await resolveModelForRequest(state.config.model, state.upstreamIds, fetcherForUpstream, state.backgroundScheduler);
+    resolution = await resolveModelCandidates({
+      modelName: state.config.model,
+      upstreamIds: state.upstreamIds,
+      scheduler: state.backgroundScheduler,
+      currentColo: state.currentColo,
+      pickTarget: endpoints => endpoints[endpointKey] !== undefined ? endpointKey : null,
+    });
   } catch (e) {
     return { ok: false, error: serverError(e) };
   }
-  const match = resolution.matches.find(m => m.binding.upstreamModel.endpoints[endpointKey] !== undefined);
-  if (match === undefined) {
+  const [candidate] = resolution.candidates;
+  if (candidate === undefined) {
     return {
       ok: false,
       error: {
@@ -551,7 +555,7 @@ const resolveImageBinding = async (
       },
     };
   }
-  return { ok: true, binding: match.binding };
+  return { ok: true, binding: candidate.binding, fetcher: candidate.fetcher };
 };
 
 // 60s cap matches the per-minute refill window of Azure TPM/RPM and
@@ -757,11 +761,9 @@ const streamImageGeneration = (
   sources: readonly ImageSource[],
   state: ShimState,
 ) => async function* (): AsyncGenerator<ServerToolLifecycleEvent, ServerToolTerminal> {
-  const fetcherForUpstream = await createPerRequestFetcher(state.currentColo);
-  const resolved = await resolveImageBinding(isEdit, state, fetcherForUpstream);
+  const resolved = await resolveImageBinding(isEdit, state);
   if (!resolved.ok) return imageTerminal(prompt, action, { ok: false, error: resolved.error });
-  const { binding } = resolved;
-  const fetcher = fetcherForUpstream(binding.upstream);
+  const { binding, fetcher } = resolved;
   const wantsPartials = (state.config.partial_images ?? 0) > 0;
 
   let response: Response;
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation_test.ts
index 0e3428972..30a057798 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/server-tools/image-generation_test.ts
@@ -56,6 +56,7 @@ const gatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-deepseek-normalize_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-deepseek-normalize_test.ts
index 60ef141aa..5c33c0be2 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-deepseek-normalize_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-deepseek-normalize_test.ts
@@ -16,6 +16,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-qwen-normalize_test.ts b/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-qwen-normalize_test.ts
index 048c4cacc..bc8b099bc 100644
--- a/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-qwen-normalize_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/interceptors/vendor-qwen-normalize_test.ts
@@ -16,6 +16,7 @@ const stubCtx: GatewayCtx = {
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 };
diff --git a/packages/gateway/src/data-plane/chat/responses/items/affinity.ts b/packages/gateway/src/data-plane/chat/responses/items/affinity.ts
index 8fbc1a146..a2c612e82 100644
--- a/packages/gateway/src/data-plane/chat/responses/items/affinity.ts
+++ b/packages/gateway/src/data-plane/chat/responses/items/affinity.ts
@@ -1,10 +1,10 @@
 import { hashResponsesItemEncryptedContent, isStoredResponsesItemId, responsesItemEncryptedContent, responsesItemId } from './format.ts';
 import type { StatefulResponsesStore } from './store.ts';
 import type { StoredResponsesItem } from '../../../../repo/types.ts';
-import type { ProviderCandidate } from '../../shared/candidates.ts';
 import type { ChatServeFailure } from '../../shared/errors.ts';
 import type { RoutingDecision } from '../../shared/routing.ts';
 import type { ResponsesInputItem } from '@floway-dev/protocols/responses';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import type { ResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 type StoredResponsesAffinity = 'forcing' | 'portable' | 'downgradable' | 'non_affinity';
@@ -98,10 +98,10 @@ const collectStoredResponsesItemRefs = async <TSourceItems>(
   return references;
 };
 
-const orderCandidatesByStoredResponsesAffinity = (
-  candidates: readonly ProviderCandidate[],
+const orderCandidatesByStoredResponsesAffinity = <T extends ProviderCandidate>(
+  candidates: readonly T[],
   preferredUpstreamIds: ReadonlySet<string>,
-): readonly ProviderCandidate[] => {
+): readonly T[] => {
   const preferred = [...preferredUpstreamIds].reverse();
   if (preferred.length === 0) return candidates;
 
@@ -113,17 +113,17 @@ const orderCandidatesByStoredResponsesAffinity = (
   return [...preferredCandidates, ...remainingCandidates];
 };
 
-export const classifyResponsesItemAffinity = async <TSourceItems>(input: {
+export const classifyResponsesItemAffinity = async <TSourceItems, TCandidate extends ProviderCandidate>(input: {
   sourceItems: TSourceItems;
   view: ResponsesItemsView<TSourceItems>;
   store: StatefulResponsesStore;
-  candidates: readonly ProviderCandidate[];
+  candidates: readonly TCandidate[];
   // Items the caller will stage as inputs after the affinity walk; passed
   // here so `loadInputItems` can pre-load any stored row whose content hash
   // matches one of them. Without this, a duplicate user message resent on
   // a later turn cannot be reused — it would mint a fresh row each time.
   inputItemsToStage?: readonly ResponsesInputItem[];
-}): Promise<RoutingDecision> => {
+}): Promise<RoutingDecision<TCandidate>> => {
   const { sourceItems, view, store, candidates, inputItemsToStage } = input;
   await store.loadInputItems({
     sourceItems,
diff --git a/packages/gateway/src/data-plane/chat/responses/items/affinity_test.ts b/packages/gateway/src/data-plane/chat/responses/items/affinity_test.ts
index d3a114464..02f1ea80c 100644
--- a/packages/gateway/src/data-plane/chat/responses/items/affinity_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/items/affinity_test.ts
@@ -6,9 +6,8 @@ import { createNonResponsesSourceStore } from './store.ts';
 import { initRepo } from '../../../../repo/index.ts';
 import { InMemoryRepo } from '../../../../repo/memory.ts';
 import type { StoredResponsesItem } from '../../../../repo/types.ts';
-import type { ProviderCandidate } from '../../shared/candidates.ts';
 import type { ResponsesInputItem } from '@floway-dev/protocols/responses';
-import { directFetcher } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate } from '@floway-dev/provider';
 import { stubProvider, stubUpstreamModel, assertEquals } from '@floway-dev/test-utils';
 import { responsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
diff --git a/packages/gateway/src/data-plane/chat/responses/items/rewrite.ts b/packages/gateway/src/data-plane/chat/responses/items/rewrite.ts
index 27877edf0..06f66cf87 100644
--- a/packages/gateway/src/data-plane/chat/responses/items/rewrite.ts
+++ b/packages/gateway/src/data-plane/chat/responses/items/rewrite.ts
@@ -1,9 +1,9 @@
 import { createTemporaryResponsesItemId, hashResponsesItemEncryptedContent, responsesItemEncryptedContent, responsesItemId } from './format.ts';
 import type { StatefulResponsesStore } from './store.ts';
 import type { StoredResponsesItem } from '../../../../repo/types.ts';
-import type { ProviderCandidate } from '../../shared/candidates.ts';
 import { throwChatServeFailure } from '../../shared/errors.ts';
 import type { ResponsesInputItem, ResponsesPayload } from '@floway-dev/protocols/responses';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import type { ResponsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 const isUpstreamOwned = (row: StoredResponsesItem): row is StoredResponsesItem & { upstreamId: string } =>
diff --git a/packages/gateway/src/data-plane/chat/responses/items/rewrite_test.ts b/packages/gateway/src/data-plane/chat/responses/items/rewrite_test.ts
index db4b45d07..f6e5e3911 100644
--- a/packages/gateway/src/data-plane/chat/responses/items/rewrite_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/items/rewrite_test.ts
@@ -7,9 +7,8 @@ import { createNonResponsesSourceStore } from './store.ts';
 import { initRepo } from '../../../../repo/index.ts';
 import { InMemoryRepo } from '../../../../repo/memory.ts';
 import type { StoredResponsesItem } from '../../../../repo/types.ts';
-import type { ProviderCandidate } from '../../shared/candidates.ts';
 import type { ResponsesInputItem, ResponsesPayload } from '@floway-dev/protocols/responses';
-import { directFetcher } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate } from '@floway-dev/provider';
 import { stubProvider, stubUpstreamModel, assert, assertEquals, assertFalse } from '@floway-dev/test-utils';
 import { responsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
diff --git a/packages/gateway/src/data-plane/chat/responses/routing.ts b/packages/gateway/src/data-plane/chat/responses/routing.ts
index 519e95bfe..4bc8a7662 100644
--- a/packages/gateway/src/data-plane/chat/responses/routing.ts
+++ b/packages/gateway/src/data-plane/chat/responses/routing.ts
@@ -1,8 +1,8 @@
 import { classifyResponsesItemAffinity } from './items/affinity.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { RoutingDecision } from '../shared/routing.ts';
 import type { StatefulResponsesStore } from './items/store.ts';
 import type { ResponsesInputItem, ResponsesPayload } from '@floway-dev/protocols/responses';
+import type { ProviderCandidate } from '@floway-dev/provider';
 import { responsesItemsView } from '@floway-dev/translate/via-responses/responses-items';
 
 export const planResponsesRouting = async (input: {
diff --git a/packages/gateway/src/data-plane/chat/responses/routing_test.ts b/packages/gateway/src/data-plane/chat/responses/routing_test.ts
index 2fafb477b..8ad4d0823 100644
--- a/packages/gateway/src/data-plane/chat/responses/routing_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/routing_test.ts
@@ -6,9 +6,8 @@ import { planResponsesRouting } from './routing.ts';
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { StoredResponsesItem } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { ResponsesPayload } from '@floway-dev/protocols/responses';
-import { directFetcher } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate } from '@floway-dev/provider';
 import { stubProvider, stubUpstreamModel, assertEquals } from '@floway-dev/test-utils';
 
 const API_KEY_ID = 'key_routing_test';
diff --git a/packages/gateway/src/data-plane/chat/responses/serve-prep.ts b/packages/gateway/src/data-plane/chat/responses/serve-prep.ts
index 96096ee29..7a07de65e 100644
--- a/packages/gateway/src/data-plane/chat/responses/serve-prep.ts
+++ b/packages/gateway/src/data-plane/chat/responses/serve-prep.ts
@@ -1,11 +1,12 @@
 import { renderResponsesFailure } from './errors.ts';
 import type { StatefulResponsesStore } from './items/store.ts';
 import { planResponsesRouting } from './routing.ts';
-import { enumerateProviderCandidates, type ProviderCandidate } from '../shared/candidates.ts';
+import { applyChatRulesToResponses } from '../../model-aliases/apply.ts';
+import { resolveCandidatesAndApplyAlias } from '../../model-aliases/prelude.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ModelEndpoints, ProtocolFrame } from '@floway-dev/protocols/common';
 import type { ResponsesInputItem, ResponsesPayload, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import type { ExecuteResult, ChatTargetApi } from '@floway-dev/provider';
+import type { ChatTargetApi, ExecuteResult, ProviderCandidate } from '@floway-dev/provider';
 
 // Thrown when a request names a `previous_response_id` that the store cannot
 // resolve. The HTTP/WS entry layer catches this and renders the OpenAI-shaped
@@ -74,12 +75,10 @@ export type ResponsesServePlan =
   | { readonly kind: 'failure'; readonly result: ExecuteResult<ProtocolFrame<ResponsesStreamEvent>> }
   | { readonly kind: 'ready'; readonly prepared: ResponsesPayload; readonly candidate: ProviderCandidate };
 
-// Runs the shared serve-side prep both `responsesServe.generate` and
-// `responsesServe.compact` need before dispatching to `responsesAttempt`:
-// expand any `previous_response_id`, enumerate candidates, plan routing,
-// stage the user input, and pick the first candidate. Returns a rendered
-// failure result when no candidate is viable so the caller can surface it
-// directly without re-deriving the model-error branch.
+// Shared serve-side prep for both `responsesServe.generate` and
+// `responsesServe.compact`. Returns a rendered failure result when no
+// candidate is viable so the caller can surface it directly without
+// re-deriving the model-error branch.
 export const prepareResponsesServePlan = async (args: {
   readonly payload: ResponsesPayload;
   readonly ctx: GatewayCtx;
@@ -88,13 +87,18 @@ export const prepareResponsesServePlan = async (args: {
 }): Promise<ResponsesServePlan> => {
   const { payload, ctx, store, pickTarget } = args;
   const prepared = await expandPreviousResponseId(payload, store);
-  const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
-    upstreamIds: ctx.upstreamIds,
-    model: prepared.model,
+  const resolved = await resolveCandidatesAndApplyAlias({
+    ctx,
+    modelName: prepared.model,
     pickTarget,
-    scheduler: ctx.backgroundScheduler,
-    currentColo: ctx.currentColo,
+    applyAlias: resolution => {
+      prepared.model = resolution.targetModelId;
+      applyChatRulesToResponses(prepared, resolution.rules);
+    },
+    renderAliasFailure: failure => renderResponsesFailure(failure),
   });
+  if (resolved.kind === 'failure') return { kind: 'failure', result: resolved.result };
+  const { candidates, sawModel, failedUpstreams } = resolved;
   const decision = await planResponsesRouting({ payload: prepared, candidates, store });
   if (decision.kind === 'failure') return { kind: 'failure', result: renderResponsesFailure(decision.failure) };
   // Stage the user-supplied input from the original payload — not the
diff --git a/packages/gateway/src/data-plane/chat/responses/serve_test.ts b/packages/gateway/src/data-plane/chat/responses/serve_test.ts
index 9e8cd928e..526f825f1 100644
--- a/packages/gateway/src/data-plane/chat/responses/serve_test.ts
+++ b/packages/gateway/src/data-plane/chat/responses/serve_test.ts
@@ -5,16 +5,15 @@ import { createResponsesHttpStore, MemoryStatefulResponsesBacking, LayeredStatef
 import { initRepo } from '../../../repo/index.ts';
 import { InMemoryRepo } from '../../../repo/memory.ts';
 import type { StoredResponsesItem, StoredResponsesSnapshot } from '../../../repo/types.ts';
-import type { ProviderCandidate } from '../shared/candidates.ts';
 import type { GatewayCtx } from '../shared/gateway-ctx.ts';
 import type { ChatCompletionsStreamEvent } from '@floway-dev/protocols/chat-completions';
 import { doneFrame, eventFrame, type ProtocolFrame } from '@floway-dev/protocols/common';
 import type { MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import type { ResponsesPayload, ResponsesResult, ResponsesStreamEvent } from '@floway-dev/protocols/responses';
-import { directFetcher, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
+import { directFetcher, type ProviderCandidate, type ProviderResponsesResult, type ProviderStreamResult, type ResponsesAction, type UpstreamCallOptions } from '@floway-dev/provider';
 import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-dev/test-utils';
 
-// `enumerateProviderCandidates` is the only seam between serve and the
+// `resolveModelCandidates` is the only seam between serve and the
 // provider registry — mocking it directly keeps the serve tests narrow
 // (no fake fetch, no repo upstream rows for provider catalogs) and lets
 // each test hand the serve exactly the candidates it wants to exercise.
@@ -22,13 +21,42 @@ import { assert, assertEquals, stubProvider, stubUpstreamModel } from '@floway-d
 // `model-missing` failure tests queue an empty list and expect `sawModel:
 // false` so the serve renders 404 rather than 400.
 const candidatesQueue: { readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean }[] = [];
-vi.mock('../shared/candidates.ts', async importOriginal => {
-  const original = await importOriginal<typeof import('../shared/candidates.ts')>();
+const lastCandidatesCall: { model?: string } = {};
+vi.mock('../../providers/registry.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../providers/registry.ts')>();
+  const { resolveAlias } = await import('../../model-aliases/resolve.ts');
   return {
     ...original,
-    enumerateProviderCandidates: vi.fn(async () => {
+    resolveModelCandidates: vi.fn(async (args: { modelName: string; upstreamIds: readonly string[] | null; scheduler: () => void }) => {
+      // Pull the queued alias resolution so the serve sees a resolved target id and overlays rules from `aliasResolution`.
+      const aliasResolution = await resolveAlias({
+        modelName: args.modelName,
+        providers: [],
+        fetcherForUpstream: () => directFetcher,
+        scheduler: args.scheduler,
+        endpointAccepts: () => true,
+        repo: { getByName: () => Promise.resolve(null) } as never,
+      });
+      const effectiveModel = aliasResolution?.targetModelId ?? args.modelName;
+      lastCandidatesCall.model = effectiveModel;
       const next = candidatesQueue.shift();
       if (next === undefined) throw new Error('serve_test: no candidates enqueued');
+      return { ...next, failedUpstreams: [], aliasResolution };
+    }),
+  };
+});
+
+// Mock the alias resolver so the integration test can inject a resolution
+// without standing up the full per-request fetcher + registry stack.
+const aliasResolutionQueue: ({ targetModelId: string; rules: Record<string, unknown>; aliasName: string } | null | Error)[] = [];
+vi.mock('../../model-aliases/resolve.ts', async importOriginal => {
+  const original = await importOriginal<typeof import('../../model-aliases/resolve.ts')>();
+  return {
+    ...original,
+    resolveAlias: vi.fn(async () => {
+      if (aliasResolutionQueue.length === 0) return null;
+      const next = aliasResolutionQueue.shift()!;
+      if (next instanceof Error) throw next;
       return next;
     }),
   };
@@ -56,6 +84,7 @@ const makeGatewayCtx = (): GatewayCtx => ({
   runtimeLocation: 'TEST',
   currentColo: 'TEST',
   dump: null,
+  responseHeaders: new Headers(),
   backgroundScheduler: () => {},
   requestStartedAt: 0,
 });
@@ -642,3 +671,60 @@ test('generate treats compaction_trigger-bearing input as compaction: snapshot r
   if (!Array.isArray(receivedInput)) throw new Error('expected the wire input to be an array');
   assertEquals((receivedInput.at(-1) as { type?: unknown })?.type, 'compaction_trigger');
 });
+
+test('alias resolution swaps the inbound model id for the target and overlays rules onto the Responses IR', async () => {
+  installRepo();
+  aliasResolutionQueue.push({
+    targetModelId: 'gpt-5.4',
+    rules: { reasoning: { effort: 'high', summary: 'detailed' }, verbosity: 'medium', serviceTier: 'priority' },
+    aliasName: 'gpt-fast',
+  });
+  const capturedBodies: ResponsesPayload[] = [];
+  const callResponses = vi.fn(async (_model: unknown, body: unknown): Promise<ProviderResponsesResult> => {
+    capturedBodies.push(body as ResponsesPayload);
+    return { action: 'generate', ok: true, events: makeProtocolFrames([{ type: 'response.completed', sequence_number: 0, response: makeResponsesResult() }]), modelKey: 'gpt-5.4', headers: new Headers() };
+  });
+  queueCandidates([makeCandidate({ upstream: 'up_a', callResponses })]);
+
+  const result = await responsesServe.generate({
+    payload: makePayload({ model: 'gpt-fast' }),
+    ctx: makeGatewayCtx(),
+    store: createResponsesHttpStore(API_KEY_ID, true),
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'events');
+  if (result.type !== 'events') throw new Error('unreachable');
+  await collectEvents(result.events);
+
+  // The resolved target id, not the alias name, reaches candidate enumeration.
+  assertEquals(lastCandidatesCall.model, 'gpt-5.4');
+  const observed = capturedBodies[0]!;
+  assertEquals(observed.reasoning?.effort, 'high');
+  assertEquals(observed.reasoning?.summary, 'detailed');
+  assertEquals(observed.text?.verbosity, 'medium');
+  assertEquals(observed.service_tier, 'priority');
+});
+
+test('alias resolves to no routable target — renders the Responses 404 envelope + stages x-floway-alias on the failure', async () => {
+  installRepo();
+  const { AliasNoTargetAvailableError } = await import('../../model-aliases/resolve.ts');
+  aliasResolutionQueue.push(new AliasNoTargetAvailableError({
+    aliasName: 'gpt-fast', targetCount: 2, allEndpointMismatch: false,
+  }));
+
+  const ctx = makeGatewayCtx();
+  const result = await responsesServe.generate({
+    payload: makePayload({ model: 'gpt-fast' }),
+    ctx,
+    store: createResponsesHttpStore(API_KEY_ID, true),
+    headers: new Headers(),
+  });
+
+  assertEquals(result.type, 'api-error');
+  if (result.type !== 'api-error') throw new Error('unreachable');
+  assertEquals(result.status, 404);
+  const body = JSON.parse(new TextDecoder().decode(result.body));
+  assert(body.error.message.includes("alias 'gpt-fast'"));
+  assertEquals(ctx.responseHeaders.get('x-floway-alias'), 'gpt-fast');
+});
diff --git a/packages/gateway/src/data-plane/chat/shared/attempt-helpers.ts b/packages/gateway/src/data-plane/chat/shared/attempt-helpers.ts
index 64a072059..20486e478 100644
--- a/packages/gateway/src/data-plane/chat/shared/attempt-helpers.ts
+++ b/packages/gateway/src/data-plane/chat/shared/attempt-helpers.ts
@@ -1,9 +1,8 @@
-import type { ProviderCandidate } from './candidates.ts';
 import type { GatewayCtx } from './gateway-ctx.ts';
 import { recordUpstreamHttpFailure, upstreamPerformanceContext, withUpstreamTelemetry } from './upstream-telemetry.ts';
 import { requireRecordedDurationMs, type UpstreamLatencyRecorder } from '../../shared/telemetry/performance.ts';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
-import { eventResult, readUpstreamApiError, type ExecuteResult, type ProviderStreamResult, type TelemetryModelIdentity, type UpstreamCallOptions } from '@floway-dev/provider';
+import { eventResult, readUpstreamApiError, type ExecuteResult, type ProviderCandidate, type ProviderStreamResult, type TelemetryModelIdentity, type UpstreamCallOptions } from '@floway-dev/provider';
 
 // Telemetry identity for the chosen candidate plus the upstream-reported
 // model key. Pricing reads off the provider so the cost lookup respects any
diff --git a/packages/gateway/src/data-plane/chat/shared/candidates.ts b/packages/gateway/src/data-plane/chat/shared/candidates.ts
deleted file mode 100644
index 86b02e721..000000000
--- a/packages/gateway/src/data-plane/chat/shared/candidates.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { createPerRequestFetcher } from '../../../dial/per-request.ts';
-import { collectInterpretationOutcomes, enumerateModelInterpretations, listModelProviders } from '../../providers/registry.ts';
-import type { BackgroundScheduler } from '@floway-dev/platform';
-import type { ModelEndpoints } from '@floway-dev/protocols/common';
-import type { ChatTargetApi, ProviderCandidate } from '@floway-dev/provider';
-
-export type { ProviderCandidate };
-
-// Returns the candidates that satisfy both the model resolution and the
-// target-endpoint pick, plus a `sawModel` flag that distinguishes the
-// "model is missing entirely" failure from "model exists but does not
-// expose the endpoint this source needs", plus the names of upstreams
-// whose catalog fetch rejected this round so the caller's failure
-// renderer can surface them parenthetically.
-export const enumerateProviderCandidates = async ({
-  upstreamIds, model, pickTarget, scheduler, currentColo,
-}: {
-  // null = unrestricted; empty list = no providers visible.
-  upstreamIds: readonly string[] | null;
-  model: string;
-  pickTarget: (endpoints: ModelEndpoints) => ChatTargetApi | null;
-  // Threaded into `resolveModelForProvider` so the per-upstream catalog
-  // lookup hits the SWR-cached `fetchUpstreamModelsCached` instead of
-  // round-tripping to the upstream on every chat serve.
-  scheduler: BackgroundScheduler;
-  // Current colo for this request — see GatewayCtx.currentColo. Threaded
-  // into the per-request fetcher so colo-scoped fallback entries can be
-  // honoured at dial time.
-  currentColo: string;
-}): Promise<{ readonly candidates: readonly ProviderCandidate[]; readonly sawModel: boolean; readonly failedUpstreams: readonly string[] }> => {
-  const fetcherForUpstream = await createPerRequestFetcher(currentColo);
-  const providers = await listModelProviders(upstreamIds);
-
-  // Each (provider, lookupId) interpretation describes one way the inbound
-  // id can address an upstream — bare form for `[unprefixed]`-addressable
-  // upstreams, stripped form for `[prefixed]`-addressable upstreams when the
-  // inbound starts with the configured prefix. A dual-addressable upstream
-  // contributes both when applicable. The fan-out is shared with
-  // `resolveModelForRequest`; first-viable-wins ordering follows configured
-  // sort_order across upstreams, with the unprefixed interpretation pushed
-  // before the prefixed one within a single upstream.
-  const interpretations = enumerateModelInterpretations(model, providers);
-  const { resolutions, failedUpstreams } = await collectInterpretationOutcomes(interpretations, fetcherForUpstream, scheduler);
-
-  const candidates: ProviderCandidate[] = [];
-  let sawModel = false;
-
-  for (const { provider, resolved } of resolutions) {
-    sawModel = true;
-    const targetApi = pickTarget(resolved.binding.upstreamModel.endpoints);
-    if (!targetApi) continue;
-    candidates.push({ provider, binding: resolved.binding, targetApi, fetcher: fetcherForUpstream(provider.upstream) });
-  }
-
-  return { candidates, sawModel, failedUpstreams };
-};
diff --git a/packages/gateway/src/data-plane/chat/shared/candidates_test.ts b/packages/gateway/src/data-plane/chat/shared/candidates_test.ts
index 627b631d5..aabe4ef3c 100644
--- a/packages/gateway/src/data-plane/chat/shared/candidates_test.ts
+++ b/packages/gateway/src/data-plane/chat/shared/candidates_test.ts
@@ -1,8 +1,8 @@
 import { describe, test } from 'vitest';
 
-import { enumerateProviderCandidates } from './candidates.ts';
 import { buildCustomUpstreamRecord, setupAppTest } from '../../../test-helpers.ts';
 import { clearInFlightForTesting } from '../../providers/models-cache.ts';
+import { resolveModelCandidates } from '../../providers/registry.ts';
 import type { ModelEndpoints } from '@floway-dev/protocols/common';
 import type { ChatTargetApi, UpstreamRecord } from '@floway-dev/provider';
 import { assertEquals, jsonResponse, withMockedFetch } from '@floway-dev/test-utils';
@@ -46,15 +46,15 @@ const pickResponses = (e: ModelEndpoints): ChatTargetApi | null =>
 const pickAny = (e: ModelEndpoints): ChatTargetApi | null =>
   e.messages ? 'messages' : e.responses ? 'responses' : e.chatCompletions ? 'chat-completions' : null;
 
-describe('enumerateProviderCandidates', () => {
+describe('resolveModelCandidates', () => {
   test('single provider with a matching binding yields one candidate', async () => {
     const { repo } = await setupAppTest();
     await repo.upstreams.deleteAll();
     await repo.upstreams.save(azureUpstream('up_a', 10, ['test-model'], { messages: {} }));
 
-    const { candidates, sawModel } = await enumerateProviderCandidates({
+    const { candidates, sawModel } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -72,9 +72,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.deleteAll();
     await repo.upstreams.save(azureUpstream('up_chat', 10, ['test-model'], { chatCompletions: {} }));
 
-    const { candidates, sawModel } = await enumerateProviderCandidates({
+    const { candidates, sawModel } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -92,9 +92,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.deleteAll();
     await repo.upstreams.save(azureUpstream('up_a', 10, ['other-model'], { messages: {} }));
 
-    const { candidates, sawModel } = await enumerateProviderCandidates({
+    const { candidates, sawModel } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -111,9 +111,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.save(azureUpstream('up_second', 20, ['other-model'], { messages: {} }));
     await repo.upstreams.save(azureUpstream('up_third', 30, ['test-model'], { messages: {} }));
 
-    const { candidates } = await enumerateProviderCandidates({
+    const { candidates } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -131,9 +131,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.save(azureUpstream('up_b', 20, ['test-model'], { messages: {} }));
     await repo.upstreams.save(azureUpstream('up_c', 30, ['test-model'], { messages: {} }));
 
-    const { candidates } = await enumerateProviderCandidates({
+    const { candidates } = await resolveModelCandidates({
       upstreamIds: ['up_c', 'up_a'],
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -153,9 +153,9 @@ describe('enumerateProviderCandidates', () => {
       enabled: false,
     });
 
-    const { candidates } = await enumerateProviderCandidates({
+    const { candidates } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -170,9 +170,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.deleteAll();
     await repo.upstreams.save(azureUpstream('up_multi', 10, ['test-model'], { messages: {}, responses: {} }));
 
-    const { candidates: msgCandidates } = await enumerateProviderCandidates({
+    const { candidates: msgCandidates } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessagesOrResponses,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -180,9 +180,9 @@ describe('enumerateProviderCandidates', () => {
     assertEquals(msgCandidates.length, 1);
     assertEquals(msgCandidates[0].targetApi, 'messages');
 
-    const { candidates: resCandidates } = await enumerateProviderCandidates({
+    const { candidates: resCandidates } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickResponses,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -196,9 +196,9 @@ describe('enumerateProviderCandidates', () => {
     await repo.upstreams.deleteAll();
     await repo.upstreams.save(azureUpstream('up_chat', 10, ['test-model'], { chatCompletions: {} }));
 
-    const { candidates: anyCandidates } = await enumerateProviderCandidates({
+    const { candidates: anyCandidates } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickAny,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -206,9 +206,9 @@ describe('enumerateProviderCandidates', () => {
     assertEquals(anyCandidates.length, 1);
     assertEquals(anyCandidates[0].targetApi, 'chat-completions');
 
-    const { candidates: msgCandidates, sawModel } = await enumerateProviderCandidates({
+    const { candidates: msgCandidates, sawModel } = await resolveModelCandidates({
       upstreamIds: null,
-      model: 'test-model',
+      modelName: 'test-model',
       pickTarget: pickMessages,
       scheduler: testScheduler,
       currentColo: 'TEST',
@@ -243,9 +243,9 @@ describe('enumerateProviderCandidates', () => {
         throw new Error(`Unhandled fetch ${request.url}`);
       },
       async () => {
-        const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
+        const { candidates, sawModel, failedUpstreams } = await resolveModelCandidates({
           upstreamIds: null,
-          model: 'test-model',
+          modelName: 'test-model',
           pickTarget: pickMessages,
           scheduler: testScheduler,
           currentColo: 'TEST',
@@ -286,9 +286,9 @@ describe('enumerateProviderCandidates', () => {
         throw new Error(`Unhandled fetch ${request.url}`);
       },
       async () => {
-        const { candidates, sawModel, failedUpstreams } = await enumerateProviderCandidates({
+        const { candidates, sawModel, failedUpstreams } = await resolveModelCandidates({
           upstreamIds: null,
-          model: 'test-model',
+          modelName: 'test-model',
           pickTarget: pickMessages,
           scheduler: testScheduler,
           currentColo: 'TEST',
diff --git a/packages/gateway/src/data-plane/chat/shared/errors.ts b/packages/gateway/src/data-plane/chat/shared/errors.ts
index 7a98db1db..b043eddef 100644
--- a/packages/gateway/src/data-plane/chat/shared/errors.ts
+++ b/packages/gateway/src/data-plane/chat/shared/errors.ts
@@ -9,7 +9,12 @@ export type ChatServeFailure =
   | { readonly kind: 'model-missing'; readonly model: string; readonly failedUpstreams?: readonly string[] }
   | { readonly kind: 'model-unsupported'; readonly model: string; readonly failedUpstreams?: readonly string[] }
   | { readonly kind: 'item-not-found'; readonly itemId: string }
-  | { readonly kind: 'routing-unavailable'; readonly message: string };
+  | { readonly kind: 'routing-unavailable'; readonly message: string }
+  // Alias name resolved, but no entry in its targets list currently maps
+  // to an enabled upstream binding. `message` carries the canonical
+  // wording the Error class already built, so renderers do not re-derive
+  // it.
+  | { readonly kind: 'alias-no-target-available'; readonly message: string };
 
 class ChatServeFailureError extends Error {
   readonly failure: ChatServeFailure;
diff --git a/packages/gateway/src/data-plane/chat/shared/gateway-ctx.ts b/packages/gateway/src/data-plane/chat/shared/gateway-ctx.ts
index 21f14d66d..131fde2c1 100644
--- a/packages/gateway/src/data-plane/chat/shared/gateway-ctx.ts
+++ b/packages/gateway/src/data-plane/chat/shared/gateway-ctx.ts
@@ -21,10 +21,14 @@ export interface GatewayCtx {
   // provider-call boundary.
   readonly runtimeLocation: string;
   readonly currentColo: string;
-  // Null when the api key has no retention configured, in which case the
-  // respond layer's `ctx.dump?.X(...)` calls collapse to no-ops and
-  // `ctx.dump?.finalize(response) ?? response` returns the response unchanged.
+  // Null when the api key has no retention configured, in which case
+  // `finalizeGatewayResponse` short-circuits the dump tee and returns the
+  // response untouched.
   readonly dump: DumpAccumulator | null;
+  // Headers staged during request processing and written onto the
+  // outbound response by `finalizeGatewayResponse`, regardless of how
+  // the responder built the body.
+  readonly responseHeaders: Headers;
 }
 
 export interface CreateGatewayCtxOptions {
@@ -70,5 +74,14 @@ export const createGatewayCtxFromHono = (c: AuthedContext, opts: CreateGatewayCt
     runtimeLocation: colo,
     currentColo: colo,
     dump,
+    responseHeaders: new Headers(),
   };
 };
+
+// Run the dump-accumulator's finalize tee on the outgoing Response. Every
+// inbound HTTP wrapper returns its response through this seam so the dump
+// pipeline applies uniformly across happy-path, error, and passthrough paths.
+export const finalizeGatewayResponse = (ctx: GatewayCtx, response: Response): Response => {
+  for (const [name, value] of ctx.responseHeaders) response.headers.set(name, value);
+  return ctx.dump?.finalize(response) ?? response;
+};
diff --git a/packages/gateway/src/data-plane/chat/shared/respond_test.ts b/packages/gateway/src/data-plane/chat/shared/respond_test.ts
index e57f52ae4..328da2ee5 100644
--- a/packages/gateway/src/data-plane/chat/shared/respond_test.ts
+++ b/packages/gateway/src/data-plane/chat/shared/respond_test.ts
@@ -43,6 +43,7 @@ const setup = (): Harness => {
       runtimeLocation: 'TEST',
       currentColo: 'TEST',
       dump: null,
+      responseHeaders: new Headers(),
       backgroundScheduler: promise => { background.push(promise); },
       requestStartedAt,
     }),
diff --git a/packages/gateway/src/data-plane/chat/shared/routing.ts b/packages/gateway/src/data-plane/chat/shared/routing.ts
index 96785da70..10b1584e6 100644
--- a/packages/gateway/src/data-plane/chat/shared/routing.ts
+++ b/packages/gateway/src/data-plane/chat/shared/routing.ts
@@ -1,6 +1,10 @@
-import type { ProviderCandidate } from './candidates.ts';
 import type { ChatServeFailure } from './errors.ts';
+import type { ProviderCandidate } from '@floway-dev/provider';
 
-export type RoutingDecision =
-  | { readonly kind: 'success'; readonly candidates: readonly ProviderCandidate[] }
+// Generic over the candidate type so call sites can narrow back to their
+// concrete shape. The candidate filtering and ordering inside routing is
+// shape-agnostic — it touches `binding.upstream` and
+// `binding.supportsResponsesItemReference` only.
+export type RoutingDecision<T extends ProviderCandidate = ProviderCandidate> =
+  | { readonly kind: 'success'; readonly candidates: readonly T[] }
   | { readonly kind: 'failure'; readonly failure: ChatServeFailure };
diff --git a/packages/gateway/src/data-plane/chat/shared/sanitize.ts b/packages/gateway/src/data-plane/chat/shared/sanitize.ts
new file mode 100644
index 000000000..10f3f3b07
--- /dev/null
+++ b/packages/gateway/src/data-plane/chat/shared/sanitize.ts
@@ -0,0 +1,36 @@
+import { FLOWAY_EXTENSION_FIELDS } from '@floway-dev/protocols/extensions';
+
+export interface SanitizeTraceCtx {
+  readonly emit: (line: { field: string; targetProtocol: string }) => void;
+}
+
+// Default per-request trace that flows through the gateway's console logger.
+export const createSanitizeTraceCtx = (): SanitizeTraceCtx => ({
+  emit: line => console.warn('floway.extension.drop', JSON.stringify(line)),
+});
+
+const stripKeys = (
+  body: Record<string, unknown>,
+  keys: readonly string[],
+  targetProtocol: string,
+  trace: SanitizeTraceCtx,
+): void => {
+  for (const key of keys) {
+    if (key in body) {
+      delete body[key];
+      trace.emit({ field: key, targetProtocol });
+    }
+  }
+};
+
+export const sanitizeForChatCompletionsUpstream = (body: Record<string, unknown>, trace: SanitizeTraceCtx): void => {
+  stripKeys(body, FLOWAY_EXTENSION_FIELDS.chatCompletions, 'chat-completions', trace);
+};
+
+export const sanitizeForResponsesUpstream = (body: Record<string, unknown>, trace: SanitizeTraceCtx): void => {
+  stripKeys(body, FLOWAY_EXTENSION_FIELDS.responses, 'responses', trace);
+};
+
+export const sanitizeForMessagesUpstream = (body: Record<string, unknown>, trace: SanitizeTraceCtx): void => {
+  stripKeys(body, FLOWAY_EXTENSION_FIELDS.messages, 'messages', trace);
+};
diff --git a/packages/gateway/src/data-plane/chat/shared/sanitize_test.ts b/packages/gateway/src/data-plane/chat/shared/sanitize_test.ts
new file mode 100644
index 000000000..6a0bee4f9
--- /dev/null
+++ b/packages/gateway/src/data-plane/chat/shared/sanitize_test.ts
@@ -0,0 +1,61 @@
+import { test } from 'vitest';
+
+import {
+  createSanitizeTraceCtx,
+  sanitizeForChatCompletionsUpstream,
+  sanitizeForMessagesUpstream,
+  sanitizeForResponsesUpstream,
+  type SanitizeTraceCtx,
+} from './sanitize.ts';
+import { assertEquals } from '@floway-dev/test-utils';
+
+type TraceLine = { field: string; targetProtocol: string };
+
+const makeTrace = (): { ctx: SanitizeTraceCtx; lines: TraceLine[] } => {
+  const lines: TraceLine[] = [];
+  return {
+    ctx: { emit: line => lines.push(line) },
+    lines,
+  };
+};
+
+test('sanitizeForMessagesUpstream strips verbosity and emits one trace line', () => {
+  const body: Record<string, unknown> = { verbosity: 'low', model: 'x' };
+  const { ctx, lines } = makeTrace();
+  sanitizeForMessagesUpstream(body, ctx);
+  assertEquals(body, { model: 'x' });
+  assertEquals(lines.length, 1);
+  assertEquals(lines[0].field, 'verbosity');
+  assertEquals(lines[0].targetProtocol, 'messages');
+});
+
+test('sanitizeForChatCompletionsUpstream strips Floway extensions and leaves native fields', () => {
+  const body: Record<string, unknown> = {
+    thinking_budget: 4096,
+    reasoning_summary: 'concise',
+    reasoning_effort: 'high',
+    model: 'x',
+  };
+  const { ctx, lines } = makeTrace();
+  sanitizeForChatCompletionsUpstream(body, ctx);
+  assertEquals(body, { reasoning_effort: 'high', model: 'x' });
+  assertEquals(lines.length, 2);
+  assertEquals(lines.every(l => l.targetProtocol === 'chat-completions'), true);
+  const droppedFields = lines.map(l => l.field).sort();
+  assertEquals(droppedFields, ['reasoning_summary', 'thinking_budget']);
+});
+
+test('sanitizeForResponsesUpstream strips extensions when fed the default per-request trace', () => {
+  const body: Record<string, unknown> = { adaptive_thinking: true, thinking_budget: 4096 };
+  sanitizeForResponsesUpstream(body, createSanitizeTraceCtx());
+  assertEquals(body, {});
+});
+
+test('sanitizer is idempotent — a second run emits no additional traces', () => {
+  const body: Record<string, unknown> = { verbosity: 'low', model: 'x' };
+  const { ctx, lines } = makeTrace();
+  sanitizeForMessagesUpstream(body, ctx);
+  assertEquals(lines.length, 1);
+  sanitizeForMessagesUpstream(body, ctx);
+  assertEquals(lines.length, 1);
+});
diff --git a/packages/gateway/src/data-plane/chat/shared/upstream-telemetry.ts b/packages/gateway/src/data-plane/chat/shared/upstream-telemetry.ts
index c362071cb..cc40bf330 100644
--- a/packages/gateway/src/data-plane/chat/shared/upstream-telemetry.ts
+++ b/packages/gateway/src/data-plane/chat/shared/upstream-telemetry.ts
@@ -1,8 +1,7 @@
-import type { ProviderCandidate } from './candidates.ts';
 import type { GatewayCtx } from './gateway-ctx.ts';
 import { recordPerformanceError, recordPerformanceLatency } from '../../shared/telemetry/performance.ts';
 import type { ProtocolFrame } from '@floway-dev/protocols/common';
-import type { ChatTargetApi, PerformanceTelemetryContext } from '@floway-dev/provider';
+import type { ChatTargetApi, PerformanceTelemetryContext, ProviderCandidate } from '@floway-dev/provider';
 
 export { createUpstreamLatencyRecorder } from '../../shared/telemetry/performance.ts';
 
diff --git a/packages/gateway/src/data-plane/chat/shared/upstream-telemetry_test.ts b/packages/gateway/src/data-plane/chat/shared/upstream-telemetry_test.ts
index d1d10a103..1af801e10 100644
--- a/packages/gateway/src/data-plane/chat/shared/upstream-telemetry_test.ts
+++ b/packages/gateway/src/data-plane/chat/shared/upstream-telemetry_test.ts
@@ -28,6 +28,7 @@ const baseCtx = (overrides: Partial<GatewayCtx> = {}): GatewayCtx => {
     runtimeLocation: 'TEST',
     currentColo: 'TEST',
     dump: null,
+    responseHeaders: new Headers(),
     abortSignal: downstream.signal,
     downstreamAbortController: downstream,
     backgroundScheduler: promise => { void promise; },
diff --git a/packages/gateway/src/data-plane/codex/auto-review-alias.ts b/packages/gateway/src/data-plane/codex/auto-review-alias.ts
deleted file mode 100644
index 7d0668224..000000000
--- a/packages/gateway/src/data-plane/codex/auto-review-alias.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-// codex's `codex-auto-review` is a model-id alias the CLI sends on auto-review
-// turns; it has no upstream of its own and gets rewritten request-side to
-// `gpt-5.4`. The constants live here so the responses HTTP entry (which
-// performs the rewrite) and the codex 1p catalog handler (which decides
-// whether to keep the alias slug in the catalog) can agree on the target
-// without one reaching into the other's module.
-//
-// Codex defines the alias as `DEFAULT_APPROVAL_REVIEW_PREFERRED_MODEL`:
-// https://github.com/openai/codex/blob/e7bffc5a20e92cbc64d6c16a1b257d0b2e4cd5df/codex-rs/model-provider/src/provider.rs#L73-L96
-
-export const CODEX_AUTO_REVIEW_ALIAS = 'codex-auto-review';
-export const CODEX_AUTO_REVIEW_TARGET = 'gpt-5.4';
diff --git a/packages/gateway/src/data-plane/codex/models.ts b/packages/gateway/src/data-plane/codex/models.ts
index d06b89d7b..d9bb42d46 100644
--- a/packages/gateway/src/data-plane/codex/models.ts
+++ b/packages/gateway/src/data-plane/codex/models.ts
@@ -13,6 +13,15 @@
 // registry (see context-window.ts) so the codex client sees the same
 // limits the data plane will actually enforce.
 //
+// Operator-defined aliases participate in the same filter: a bundled
+// catalog slug that matches a visible alias survives whenever the alias
+// has at least one currently-routable target. The context window the alias
+// advertises follows its announced metadata (when the operator overrode
+// it) or the min across every routable target's window — the safe lower
+// bound `/v1/models`'s rule-aware intersection already applies, so
+// whichever target the resolver picks at request time the catalog's
+// published window is one the gateway can actually serve.
+//
 // Latency: codex aborts the catalog fetch after 5 s
 // (`MODELS_REFRESH_TIMEOUT` in codex-rs/model-provider/src/models_endpoint.rs)
 // and silently falls back to its binary-bundled catalog on miss. The
@@ -25,14 +34,15 @@
 
 import type { Context } from 'hono';
 
-import { CODEX_AUTO_REVIEW_ALIAS, CODEX_AUTO_REVIEW_TARGET } from './auto-review-alias.ts';
 import { parseCodexVersion, resolveCodexCatalog, type CodexCatalog } from './catalog.ts';
 import { applyContextWindowFromRegistry, type ContextWindowResolver } from './context-window.ts';
 import { createPerRequestFetcher } from '../../dial/per-request.ts';
 import { effectiveUpstreamIdsFromContext } from '../../middleware/auth.ts';
+import { getRepo } from '../../repo/index.ts';
 import { backgroundSchedulerFromContext } from '../../runtime/background.ts';
 import { getCurrentColo } from '../../runtime/runtime-info.ts';
-import { getInternalModels } from '../providers/registry.ts';
+import { synthesizeListedAliases } from '../models/alias-listing.ts';
+import { enumerateAddressableModelIds, listedRealModels } from '../providers/addressable.ts';
 import type { BackgroundScheduler } from '@floway-dev/platform';
 import type { Fetcher } from '@floway-dev/provider';
 
@@ -56,28 +66,80 @@ const computeCatalog = async (
   fetcherForUpstream: (upstreamId: string) => Fetcher,
   scheduler: BackgroundScheduler,
 ): Promise<CodexCatalog> => {
-  const [catalog, internalModels] = await Promise.all([
+  const [catalog, callerAddressable, gatewayAddressable, aliases] = await Promise.all([
     resolveCodexCatalog(userAgent),
-    getInternalModels(upstreamIds, fetcherForUpstream, scheduler),
+    enumerateAddressableModelIds(upstreamIds, fetcherForUpstream, scheduler),
+    upstreamIds === null
+      ? Promise.resolve(null)
+      : enumerateAddressableModelIds(null, fetcherForUpstream, scheduler),
+    getRepo().modelAliases.list(),
   ]);
-  const slugContextWindow = new Map<string, number>();
-  for (const m of internalModels) {
-    const limit = m.limits.max_context_window_tokens;
-    if (typeof limit === 'number') slugContextWindow.set(m.id, limit);
+  const gatewayAddressableModelIds = gatewayAddressable ?? callerAddressable;
+  const realModels = listedRealModels(callerAddressable);
+  // `registrySlugs` mirrors the caller's listed catalog — the slugs the
+  // codex client would have seen in a regular /v1/models call. The two
+  // addressable maps below feed the synthesizer's metadata-vs-visibility
+  // split: gateway-wide for the alias's context-window intersection (so
+  // every API key sees the same number), caller-scope for "does this
+  // alias appear at all".
+  const registrySlugs = new Set(realModels.map(m => m.id));
+  const gatewayById = new Map(gatewayAddressableModelIds.map(entry => [entry.id, entry] as const));
+  const callerById = new Map(callerAddressable.map(entry => [entry.id, entry] as const));
+
+  // Each alias entry survives in the codex catalog when at least one of
+  // its configured targets is currently addressable AND kind-matches the
+  // alias under the CALLER's cap (this matches `synthesizeListedAliases`'s
+  // visibility rule). The fallback window — used when the operator did
+  // not override `announcedMetadata` — is the min across every GATEWAY-
+  // wide routable target's window, mirroring the safe-lower-bound rule
+  // /v1/models already applies. Selection mode is irrelevant here because
+  // the catalog must publish a single stable window.
+  interface AliasCatalogInfo {
+    readonly routableWindowsMin: number | null;
+    readonly announcedContextWindow: number | undefined;
+  }
+  const aliasCatalogInfo = new Map<string, AliasCatalogInfo>();
+  for (const entry of synthesizeListedAliases({
+    aliases,
+    gatewayAddressableModelIds,
+    callerAddressableModelIds: callerAddressable,
+    narrowTargets: true,
+  })) {
+    const aliasedFrom = entry.aliasedFrom;
+    if (aliasedFrom === undefined) continue;
+    // Use the raw alias record's targets for the window scan — the
+    // entry's `aliasedFrom.targets` is the narrowed projection, which
+    // would understate the gateway-wide min when the caller is scoped.
+    const alias = aliases.find(a => a.name === entry.id);
+    if (alias === undefined) continue;
+    const gatewayRoutable = alias.targets
+      .map(t => gatewayById.get(t.target_model_id))
+      .filter((a): a is NonNullable<typeof a> => a !== undefined && a.model.kind === entry.kind);
+    if (gatewayRoutable.length === 0) continue;
+    const windows = gatewayRoutable
+      .map(a => a.model.limits.max_context_window_tokens)
+      .filter((w): w is number => w !== undefined);
+    aliasCatalogInfo.set(entry.id, {
+      routableWindowsMin: windows.length > 0 ? Math.min(...windows) : null,
+      announcedContextWindow: entry.limits.max_context_window_tokens,
+    });
   }
-  const registrySlugs = new Set(internalModels.map(m => m.id));
+
   const filtered: CodexCatalog = {
-    models: catalog.models.filter(m => {
-      if (registrySlugs.has(m.slug)) return true;
-      if (m.slug === CODEX_AUTO_REVIEW_ALIAS && registrySlugs.has(CODEX_AUTO_REVIEW_TARGET)) return true;
-      return false;
-    }),
+    models: catalog.models.filter(m => registrySlugs.has(m.slug) || aliasCatalogInfo.has(m.slug)),
+  };
+
+  // Alias slug: prefer the alias's announced window (operator override OR
+  // the synthesizer's automatic intersection) so codex's local gating —
+  // auto-compact, context-budget UX — agrees with what /v1/models told
+  // the operator's other tooling. Fallback to the min over routable
+  // targets' windows when the alias publishes no window. Plain slugs read
+  // straight off the registry.
+  const contextWindowOf: ContextWindowResolver = slug => {
+    const info = aliasCatalogInfo.get(slug);
+    if (info !== undefined) return info.announcedContextWindow ?? info.routableWindowsMin;
+    return callerById.get(slug)?.model.limits.max_context_window_tokens ?? null;
   };
-  // codex-auto-review has no upstream of its own and gets rewritten to
-  // CODEX_AUTO_REVIEW_TARGET at request time, so its catalog entry should
-  // advertise the target's actual window — bundled's value would otherwise
-  // leak the OpenAI 1p limits through the alias.
-  const contextWindowOf: ContextWindowResolver = slug => slugContextWindow.get(slug === CODEX_AUTO_REVIEW_ALIAS ? CODEX_AUTO_REVIEW_TARGET : slug) ?? null;
   return applyContextWindowFromRegistry(filtered, contextWindowOf);
 };
 
diff --git a/packages/gateway/src/data-plane/codex/routes_test.ts b/packages/gateway/src/data-plane/codex/routes_test.ts
index ecd0010f3..6691a77a1 100644
--- a/packages/gateway/src/data-plane/codex/routes_test.ts
+++ b/packages/gateway/src/data-plane/codex/routes_test.ts
@@ -5,7 +5,7 @@ import { describe, expect, it } from 'vitest';
 import { mountCodexRoutes } from './routes.ts';
 import { app as gatewayApp } from '../../app.ts';
 import { type AuthVars, authMiddleware } from '../../middleware/auth.ts';
-import { copilotModels, setupAppTest, sseResponsesResponse } from '../../test-helpers.ts';
+import { copilotModels, buildCustomUpstreamRecord, setupAppTest, sseResponsesResponse } from '../../test-helpers.ts';
 import { isStoredResponseId } from '../chat/responses/items/format.ts';
 import { jsonResponse, withMockedFetch } from '@floway-dev/test-utils';
 
@@ -433,13 +433,25 @@ describe('codex 1p namespace', () => {
       const slugs = body.models.map(m => m.slug);
       // The bundled catalog ships with six slugs (gpt-5.5, gpt-5.4,
       // gpt-5.4-mini, gpt-5.3-codex, gpt-5.2, codex-auto-review). Registry
-      // here advertises only gpt-5.5, and codex-auto-review's target
-      // (gpt-5.4) is missing — so the response is just gpt-5.5.
+      // here advertises only gpt-5.5, and no alias is seeded — so the
+      // response is just gpt-5.5.
       expect(slugs).toEqual(['gpt-5.5']);
     });
 
-    it('keeps codex-auto-review when its alias target is in the registry, drops it otherwise, and reports the target window', async () => {
-      const { apiKey } = await setupAppTest();
+    it('keeps codex-auto-review when the seeded alias target is in the registry, drops it otherwise, and reports the target window', async () => {
+      const { apiKey, repo } = await setupAppTest();
+      await repo.modelAliases.insert({
+        name: 'codex-auto-review',
+        kind: 'chat',
+        selection: 'first-available',
+        displayName: 'Codex Auto Review',
+        visibleInModelsList: true,
+        targets: [{ target_model_id: 'gpt-5.4', rules: {} }],
+        announcedMetadata: null,
+        sortOrder: 0,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      });
       const app = buildCodexApp();
       const body = await withMockedFetch(
         copilotFetch([{ id: 'gpt-5.4', maxContextWindowTokens: 272000 }]),
@@ -455,15 +467,165 @@ describe('codex 1p namespace', () => {
       expect(slugs.has('gpt-5.4')).toBe(true);
       expect(slugs.has('codex-auto-review')).toBe(true);
       expect(slugs.has('gpt-5.5')).toBe(false);
-      // codex-auto-review has no registry entry of its own, but it gets
-      // rewritten to gpt-5.4 at request time, so its catalog row reports
-      // gpt-5.4's window — not the bundled 1000000 max that would advertise
-      // a tier the gateway cannot serve.
+      // codex-auto-review has no registry entry of its own; the alias's
+      // first available target is gpt-5.4, so its catalog row reports
+      // gpt-5.4's 272000 window — not the bundled 1000000 max that would
+      // advertise a tier the gateway cannot serve.
       const autoReview = body.models.find(m => m.slug === 'codex-auto-review');
       expect(autoReview?.context_window).toBe(272000);
       expect(autoReview?.max_context_window).toBe(272000);
     });
 
+    it('honors an operator-set announcedMetadata.limits.max_context_window_tokens override on an alias slug', async () => {
+      // /v1/models, /api/models, /v1beta/models all honor the operator's
+      // announced limits override. The codex 1p catalog reads the same
+      // value because the codex client uses `context_window` /
+      // `max_context_window` for its own local gating (auto-compact,
+      // context-budget UX) — operator intent has to agree across all
+      // wire surfaces.
+      const { apiKey, repo } = await setupAppTest();
+      await repo.modelAliases.insert({
+        name: 'codex-auto-review',
+        kind: 'chat',
+        selection: 'first-available',
+        displayName: 'Codex Auto Review',
+        visibleInModelsList: true,
+        targets: [{ target_model_id: 'gpt-5.4', rules: {} }],
+        announcedMetadata: { limits: { max_context_window_tokens: 64000 } },
+        sortOrder: 0,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      });
+      const app = buildCodexApp();
+      const body = await withMockedFetch(
+        copilotFetch([{ id: 'gpt-5.4', maxContextWindowTokens: 272000 }]),
+        async () => {
+          const response = await app.request('/azure-api.codex/models', {
+            headers: { authorization: `Bearer ${apiKey.key}` },
+          });
+          expect(response.status).toBe(200);
+          return await response.json() as CodexModelsResponse;
+        },
+      );
+      const autoReview = body.models.find(m => m.slug === 'codex-auto-review');
+      // The operator pulled the alias's advertised window down to 64000;
+      // the target's true 272000 ceiling is irrelevant to the catalog.
+      expect(autoReview?.context_window).toBe(64000);
+      expect(autoReview?.max_context_window).toBe(64000);
+    });
+
+    it('reports the target window when the alias falls back to slugContextWindow on an unlisted addressable form', async () => {
+      // Trigger path: a multi-target alias whose targets disagree on
+      // `max_context_window_tokens` (one target omits it) — the
+      // automatic intersection drops the field, so the codex catalog has
+      // to fall back to the first routable target's own window via
+      // `slugContextWindow`. The first target is the bare unlisted form
+      // `gpt-5.4` (the listed canonical is `cust/gpt-5.4`), so the
+      // lookup must succeed against the addressable surface — keyed by
+      // listed-only ids it would miss and the catalog would publish a
+      // null window, defaulting back to the bundled tier the gateway
+      // cannot actually serve.
+      const { apiKey, repo } = await setupAppTest();
+      await repo.upstreams.deleteAll();
+      await repo.upstreams.save(buildCustomUpstreamRecord({
+        modelPrefix: { prefix: 'cust/', addressable: ['unprefixed', 'prefixed'], listed: ['prefixed'] },
+      }));
+      await repo.modelAliases.insert({
+        name: 'codex-auto-review',
+        kind: 'chat',
+        selection: 'first-available',
+        displayName: 'Codex Auto Review',
+        visibleInModelsList: true,
+        targets: [
+          { target_model_id: 'gpt-5.4', rules: {} },
+          { target_model_id: 'gpt-5.5', rules: {} },
+        ],
+        announcedMetadata: null,
+        sortOrder: 0,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      });
+      const app = buildCodexApp();
+      const body = await withMockedFetch(
+        request => {
+          const url = new URL(request.url);
+          if (url.hostname === 'custom.example.com' && url.pathname === '/v1/models') {
+            return jsonResponse({
+              object: 'list',
+              data: [
+                {
+                  id: 'gpt-5.4',
+                  supported_endpoints: ['/chat/completions'],
+                  limits: { max_context_window_tokens: 272000 },
+                },
+                {
+                  // No window — intersection drops the field, exposing
+                  // the slugContextWindow fallback path.
+                  id: 'gpt-5.5',
+                  supported_endpoints: ['/chat/completions'],
+                },
+              ],
+            });
+          }
+          throw new Error(`Unhandled fetch ${request.url}`);
+        },
+        async () => {
+          const response = await app.request('/azure-api.codex/models', {
+            headers: { authorization: `Bearer ${apiKey.key}` },
+          });
+          expect(response.status).toBe(200);
+          return await response.json() as CodexModelsResponse;
+        },
+      );
+      const autoReview = body.models.find(m => m.slug === 'codex-auto-review');
+      // Bundled `codex-auto-review` ships with max_context_window=1000000;
+      // a successful resolver lookup pulls it down to gpt-5.4's 272000.
+      expect(autoReview?.max_context_window).toBe(272000);
+      expect(autoReview?.context_window).toBe(272000);
+    });
+
+    it('takes min(window) across all routable targets when the alias publishes no window', async () => {
+      // Multi-target alias with two routable targets advertising different
+      // windows and no announced override (intersection drops the field
+      // because targets disagree); the catalog should pick the safe lower
+      // bound, matching the rule-aware intersection /v1/models already
+      // applies.
+      const { apiKey, repo } = await setupAppTest();
+      await repo.modelAliases.insert({
+        name: 'codex-auto-review',
+        kind: 'chat',
+        selection: 'first-available',
+        displayName: 'Codex Auto Review',
+        visibleInModelsList: true,
+        targets: [
+          { target_model_id: 'gpt-5.4', rules: {} },
+          { target_model_id: 'gpt-5.5', rules: {} },
+        ],
+        announcedMetadata: null,
+        sortOrder: 0,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      });
+      const app = buildCodexApp();
+      const body = await withMockedFetch(
+        copilotFetch([
+          { id: 'gpt-5.4', maxContextWindowTokens: 272000, supported_endpoints: ['/chat/completions'] },
+          { id: 'gpt-5.5', maxContextWindowTokens: 120000, supported_endpoints: ['/chat/completions'] },
+        ]),
+        async () => {
+          const response = await app.request('/azure-api.codex/models', {
+            headers: { authorization: `Bearer ${apiKey.key}` },
+          });
+          expect(response.status).toBe(200);
+          return await response.json() as CodexModelsResponse;
+        },
+      );
+      const autoReview = body.models.find(m => m.slug === 'codex-auto-review');
+      // gpt-5.4 → 272000, gpt-5.5 → 120000. min(272000, 120000) = 120000.
+      expect(autoReview?.max_context_window).toBe(120000);
+      expect(autoReview?.context_window).toBe(120000);
+    });
+
     it('returns an empty catalog when the registry has no overlapping slugs', async () => {
       const { apiKey } = await setupAppTest();
       const app = buildCodexApp();
diff --git a/packages/gateway/src/data-plane/completions/serve.ts b/packages/gateway/src/data-plane/completions/serve.ts
index 2ab560c4b..f26708065 100644
--- a/packages/gateway/src/data-plane/completions/serve.ts
+++ b/packages/gateway/src/data-plane/completions/serve.ts
@@ -10,7 +10,7 @@ import type { Context } from 'hono';
 
 import { tokenUsageFromCompletionsUsage } from './usage.ts';
 import type { TokenUsage } from '../../repo/types.ts';
-import { createGatewayCtxFromHono } from '../chat/shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse } from '../chat/shared/gateway-ctx.ts';
 import { readRequestBody } from '../chat/shared/request-body.ts';
 import { passthroughApiError, passthroughServe } from '../shared/passthrough-serve.ts';
 import { isOpenAIUsageOnlyEventShape, type ProtocolFrame } from '@floway-dev/protocols/common';
@@ -65,8 +65,7 @@ export const completions = async (c: Context): Promise<Response> => {
   });
   if (request.type === 'invalid') {
     ctx.dump?.error('gateway');
-    const response = passthroughApiError(c, request.message, 400);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, passthroughApiError(c, request.message, 400));
   }
 
   ctx.dump?.requestedModel(request.model);
@@ -101,7 +100,7 @@ export const completions = async (c: Context): Promise<Response> => {
     ctx,
     sourceApi: '/completions',
     model: request.model,
-    bindingServesEndpoint: binding => binding.upstreamModel.endpoints.completions !== undefined,
+    endpointKey: 'completions',
     call: (binding, opts) =>
       binding.provider.callCompletions(binding.upstreamModel, upstreamBody, ctx.abortSignal, opts),
     response: request.wantsStream
@@ -115,5 +114,5 @@ export const completions = async (c: Context): Promise<Response> => {
           },
         },
   });
-  return (ctx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(ctx, response);
 };
diff --git a/packages/gateway/src/data-plane/embeddings/serve.ts b/packages/gateway/src/data-plane/embeddings/serve.ts
index 6262546e5..ead9b3f28 100644
--- a/packages/gateway/src/data-plane/embeddings/serve.ts
+++ b/packages/gateway/src/data-plane/embeddings/serve.ts
@@ -3,7 +3,7 @@
 
 import type { Context } from 'hono';
 
-import { createGatewayCtxFromHono } from '../chat/shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse } from '../chat/shared/gateway-ctx.ts';
 import { readRequestBody } from '../chat/shared/request-body.ts';
 import { passthroughApiError, passthroughServe } from '../shared/passthrough-serve.ts';
 import { tokenUsageFromEmbeddingsBody } from '../shared/telemetry/usage.ts';
@@ -49,8 +49,7 @@ export const embeddings = async (c: Context): Promise<Response> => {
   const request = prepareEmbeddingsRequest(requestBody.bytes);
   if (request.type === 'invalid') {
     ctx.dump?.error('gateway');
-    const response = passthroughApiError(c, request.message, 400);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, passthroughApiError(c, request.message, 400));
   }
 
   ctx.dump?.requestedModel(request.model);
@@ -59,12 +58,12 @@ export const embeddings = async (c: Context): Promise<Response> => {
     ctx,
     sourceApi: '/embeddings',
     model: request.model,
-    bindingServesEndpoint: binding => binding.upstreamModel.endpoints.embeddings !== undefined,
+    endpointKey: 'embeddings',
     call: async (binding, opts) => {
       const { model: _model, ...body } = request.body;
       return await binding.provider.callEmbeddings(binding.upstreamModel, body, undefined, opts);
     },
     response: { format: 'json', extractBilling: tokenUsageFromEmbeddingsBody },
   });
-  return (ctx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(ctx, response);
 };
diff --git a/packages/gateway/src/data-plane/images/serve.ts b/packages/gateway/src/data-plane/images/serve.ts
index 405b29b03..c27fbac56 100644
--- a/packages/gateway/src/data-plane/images/serve.ts
+++ b/packages/gateway/src/data-plane/images/serve.ts
@@ -10,7 +10,7 @@
 
 import type { Context } from 'hono';
 
-import { createGatewayCtxFromHono } from '../chat/shared/gateway-ctx.ts';
+import { createGatewayCtxFromHono, finalizeGatewayResponse } from '../chat/shared/gateway-ctx.ts';
 import { readRequestBody } from '../chat/shared/request-body.ts';
 import { passthroughApiError, passthroughServe } from '../shared/passthrough-serve.ts';
 import { tokenUsageFromImagesBody } from '../shared/telemetry/usage.ts';
@@ -48,8 +48,7 @@ export const imagesGenerations = async (c: Context): Promise<Response> => {
   const request = prepareImagesGenerationsRequest(requestBody.bytes);
   if (request.type === 'invalid') {
     ctx.dump?.error('gateway');
-    const response = passthroughApiError(c, request.message, 400);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, passthroughApiError(c, request.message, 400));
   }
 
   ctx.dump?.requestedModel(request.model);
@@ -58,14 +57,14 @@ export const imagesGenerations = async (c: Context): Promise<Response> => {
     ctx,
     sourceApi: '/images/generations',
     model: request.model,
-    bindingServesEndpoint: binding => binding.upstreamModel.endpoints.imagesGenerations !== undefined,
+    endpointKey: 'imagesGenerations',
     call: (binding, opts) => {
       const { model: _model, ...body } = request.body;
       return binding.provider.callImagesGenerations(binding.upstreamModel, body, undefined, opts);
     },
     response: { format: 'json', extractBilling: tokenUsageFromImagesBody },
   });
-  return (ctx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(ctx, response);
 };
 
 export const imagesEdits = async (c: Context): Promise<Response> => {
@@ -82,15 +81,13 @@ export const imagesEdits = async (c: Context): Promise<Response> => {
     // parser's error text. The wording is enough for a client to know
     // they sent the wrong content type or a malformed body.
     ctx.dump?.error('gateway');
-    const response = passthroughApiError(c, 'Image edits request body must be a valid multipart/form-data payload.', 400);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, passthroughApiError(c, 'Image edits request body must be a valid multipart/form-data payload.', 400));
   }
 
   const modelRaw = form.get('model');
   if (typeof modelRaw !== 'string' || modelRaw.length === 0) {
     ctx.dump?.error('gateway');
-    const response = passthroughApiError(c, 'Image edits request body must include a model field.', 400);
-    return (ctx.dump?.finalize(response) ?? response);
+    return finalizeGatewayResponse(ctx, passthroughApiError(c, 'Image edits request body must include a model field.', 400));
   }
 
   ctx.dump?.requestedModel(modelRaw);
@@ -99,7 +96,7 @@ export const imagesEdits = async (c: Context): Promise<Response> => {
     ctx,
     sourceApi: '/images/edits',
     model: modelRaw,
-    bindingServesEndpoint: binding => binding.upstreamModel.endpoints.imagesEdits !== undefined,
+    endpointKey: 'imagesEdits',
     call: (binding, opts) => {
       // ModelProvider.callImagesEdits takes ownership of the FormData and
       // appends the upstream-specific model/deployment id; allocate a fresh
@@ -115,5 +112,5 @@ export const imagesEdits = async (c: Context): Promise<Response> => {
     },
     response: { format: 'json', extractBilling: tokenUsageFromImagesBody },
   });
-  return (ctx.dump?.finalize(response) ?? response);
+  return finalizeGatewayResponse(ctx, response);
 };
diff --git a/packages/gateway/src/data-plane/model-aliases/apply.ts b/packages/gateway/src/data-plane/model-aliases/apply.ts
new file mode 100644
index 000000000..919cbaf1c
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/apply.ts
@@ -0,0 +1,116 @@
+// Per-protocol rule overlay. Alias rules overwrite IR fields they name;
+// fields the target IR cannot express are silently dropped.
+
+import type { ChatCompletionsPayload } from '@floway-dev/protocols/chat-completions';
+import type { AliasRules } from '@floway-dev/protocols/common';
+import type { GeminiPayload } from '@floway-dev/protocols/gemini';
+import type { MessagesPayload } from '@floway-dev/protocols/messages';
+import type { ResponsesPayload } from '@floway-dev/protocols/responses';
+
+const hasReasoning = (rules: AliasRules): rules is AliasRules & { reasoning: NonNullable<AliasRules['reasoning']> } =>
+  rules.reasoning !== undefined;
+
+export const applyChatRulesToChatCompletions = (body: ChatCompletionsPayload, rules: AliasRules): void => {
+  if (hasReasoning(rules)) {
+    const { effort, budget_tokens, adaptive, summary } = rules.reasoning;
+    if (effort !== undefined) body.reasoning_effort = effort;
+    if (budget_tokens !== undefined) body.thinking_budget = budget_tokens;
+    if (adaptive !== undefined) body.adaptive_thinking = adaptive;
+    if (summary !== undefined) body.reasoning_summary = summary;
+  }
+  if (rules.verbosity !== undefined) body.verbosity = rules.verbosity;
+  if (rules.serviceTier !== undefined) body.service_tier = rules.serviceTier;
+};
+
+export const applyChatRulesToResponses = (body: ResponsesPayload, rules: AliasRules): void => {
+  if (hasReasoning(rules)) {
+    const { effort, budget_tokens, adaptive, summary } = rules.reasoning;
+    if (effort !== undefined || summary !== undefined) {
+      const existing = body.reasoning ?? {};
+      body.reasoning = {
+        ...existing,
+        ...(effort !== undefined ? { effort } : {}),
+        ...(summary !== undefined ? { summary } : {}),
+      };
+    }
+    if (budget_tokens !== undefined) body.thinking_budget = budget_tokens;
+    if (adaptive !== undefined) body.adaptive_thinking = adaptive;
+  }
+  if (rules.verbosity !== undefined) {
+    body.text = { ...body.text, verbosity: rules.verbosity };
+  }
+  if (rules.serviceTier !== undefined) body.service_tier = rules.serviceTier;
+};
+
+export const applyChatRulesToMessages = (body: MessagesPayload, rules: AliasRules): void => {
+  if (hasReasoning(rules)) {
+    const { effort, budget_tokens, adaptive } = rules.reasoning;
+    // Anthropic stores explicit effort in `output_config.effort`; budget /
+    // adaptive ride on `thinking.*`. Splitting them so both can be set in
+    // the same overlay (effort fixed + budget pinned, e.g.) without one
+    // erasing the other.
+    if (effort !== undefined) {
+      body.output_config = { ...body.output_config, effort };
+    }
+    if (adaptive === true) {
+      body.thinking = { ...body.thinking, type: 'adaptive' };
+    } else if (budget_tokens !== undefined) {
+      body.thinking = { ...body.thinking, type: 'enabled', budget_tokens };
+    }
+  }
+  if (rules.verbosity !== undefined) body.verbosity = rules.verbosity;
+  if (rules.serviceTier !== undefined) {
+    // The cross-protocol bridge in translate maps `speed: 'fast'` ↔
+    // `service_tier: 'fast'`; on a native Messages target the alias rule
+    // `serviceTier: 'fast'` lands on `speed` so the upstream sees Fast Mode
+    // through its native field. Other tier values pass through on
+    // `service_tier` since Messages's native enum (`auto`/`standard_only`)
+    // doesn't model them. Whichever branch we take, clear the sibling field
+    // so the upstream never sees two tiers in conflict.
+    if (rules.serviceTier === 'fast') {
+      body.speed = 'fast';
+      delete body.service_tier;
+    } else {
+      body.service_tier = rules.serviceTier;
+      delete body.speed;
+    }
+  }
+};
+
+// Discrete effort presets map onto Gemini's `thinkingLevel` enum; unknown
+// values are dropped because Gemini rejects out-of-enum tiers upstream.
+const GEMINI_THINKING_LEVEL_BY_EFFORT: Record<string, 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'> = {
+  none: 'minimal',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+  xhigh: 'xhigh',
+};
+
+export const applyChatRulesToGemini = (body: GeminiPayload, rules: AliasRules): void => {
+  if (hasReasoning(rules)) {
+    const { effort, budget_tokens, adaptive } = rules.reasoning;
+    // Gemini collapses the three reasoning controls onto one `thinkingConfig`
+    // sub-object. Adaptive wins by encoding budget=-1 (Gemini's adaptive
+    // sentinel); an explicit budget pins the count; effort sets the level.
+    const thinkingConfig = { ...body.generationConfig?.thinkingConfig };
+    if (adaptive === true) {
+      thinkingConfig.thinkingBudget = -1;
+    } else if (budget_tokens !== undefined) {
+      thinkingConfig.thinkingBudget = budget_tokens;
+    }
+    if (effort !== undefined) {
+      const level = GEMINI_THINKING_LEVEL_BY_EFFORT[effort];
+      if (level !== undefined) thinkingConfig.thinkingLevel = level;
+    }
+    if (Object.keys(thinkingConfig).length > 0) {
+      body.generationConfig = { ...body.generationConfig, thinkingConfig };
+    }
+  }
+  if (rules.verbosity !== undefined) {
+    body.generationConfig = { ...body.generationConfig, verbosity: rules.verbosity };
+  }
+  if (rules.serviceTier !== undefined) {
+    body.generationConfig = { ...body.generationConfig, serviceTier: rules.serviceTier };
+  }
+};
diff --git a/packages/gateway/src/data-plane/model-aliases/apply_test.ts b/packages/gateway/src/data-plane/model-aliases/apply_test.ts
new file mode 100644
index 000000000..1f6a1c71b
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/apply_test.ts
@@ -0,0 +1,228 @@
+// Behavioral coverage for the per-protocol rule overlay. Each protocol's
+// apply helper is exercised against an inbound payload IR; alias rules are
+// authoritative — an existing IR field is OVERWRITTEN by a matching rule
+// — and rules the IR cannot express are silently dropped.
+
+import { test } from 'vitest';
+
+import { applyChatRulesToChatCompletions, applyChatRulesToGemini, applyChatRulesToMessages, applyChatRulesToResponses } from './apply.ts';
+import type { ChatCompletionsPayload } from '@floway-dev/protocols/chat-completions';
+import type { GeminiPayload } from '@floway-dev/protocols/gemini';
+import type { MessagesPayload } from '@floway-dev/protocols/messages';
+import type { ResponsesPayload } from '@floway-dev/protocols/responses';
+import { assertEquals } from '@floway-dev/test-utils';
+
+const ccPayload = (overrides: Partial<ChatCompletionsPayload> = {}): ChatCompletionsPayload => ({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: 'hi' }],
+  ...overrides,
+});
+
+const resPayload = (overrides: Partial<ResponsesPayload> = {}): ResponsesPayload => ({
+  model: 'gpt-5.4',
+  input: 'hi',
+  ...overrides,
+});
+
+const msgPayload = (overrides: Partial<MessagesPayload> = {}): MessagesPayload => ({
+  model: 'claude-opus-4-7',
+  max_tokens: 32,
+  messages: [{ role: 'user', content: 'hi' }],
+  ...overrides,
+});
+
+const gemPayload = (overrides: Partial<GeminiPayload> = {}): GeminiPayload => ({
+  contents: [{ role: 'user', parts: [{ text: 'hi' }] }],
+  ...overrides,
+});
+
+// ── ChatCompletions ──
+
+test('chat-completions: empty rules leave the payload unchanged', () => {
+  const body = ccPayload({ reasoning_effort: 'high', verbosity: 'low', service_tier: 'priority' });
+  applyChatRulesToChatCompletions(body, {});
+  assertEquals(body.reasoning_effort, 'high');
+  assertEquals(body.verbosity, 'low');
+  assertEquals(body.service_tier, 'priority');
+});
+
+test('chat-completions: rules stamp every supported field onto the IR', () => {
+  const body = ccPayload();
+  applyChatRulesToChatCompletions(body, {
+    reasoning: { effort: 'high', budget_tokens: 1024, adaptive: true, summary: 'detailed' },
+    verbosity: 'low',
+    serviceTier: 'priority',
+  });
+  assertEquals(body.reasoning_effort, 'high');
+  assertEquals(body.thinking_budget, 1024);
+  assertEquals(body.adaptive_thinking, true);
+  assertEquals(body.reasoning_summary, 'detailed');
+  assertEquals(body.verbosity, 'low');
+  assertEquals(body.service_tier, 'priority');
+});
+
+test('chat-completions: alias rules overwrite existing IR fields', () => {
+  const body = ccPayload({ reasoning_effort: 'low', verbosity: 'high', service_tier: 'default' });
+  applyChatRulesToChatCompletions(body, {
+    reasoning: { effort: 'xhigh' },
+    verbosity: 'low',
+    serviceTier: 'priority',
+  });
+  assertEquals(body.reasoning_effort, 'xhigh');
+  assertEquals(body.verbosity, 'low');
+  assertEquals(body.service_tier, 'priority');
+});
+
+// ── Responses ──
+
+test('responses: empty rules leave the payload unchanged', () => {
+  const body = resPayload({ reasoning: { effort: 'high' }, text: { verbosity: 'low' }, service_tier: 'priority' });
+  applyChatRulesToResponses(body, {});
+  assertEquals(body.reasoning?.effort, 'high');
+  assertEquals(body.text?.verbosity, 'low');
+  assertEquals(body.service_tier, 'priority');
+});
+
+test('responses: rules stamp every supported field onto the IR', () => {
+  const body = resPayload();
+  applyChatRulesToResponses(body, {
+    reasoning: { effort: 'high', budget_tokens: 1024, adaptive: true, summary: 'concise' },
+    verbosity: 'medium',
+    serviceTier: 'flex',
+  });
+  assertEquals(body.reasoning?.effort, 'high');
+  assertEquals(body.reasoning?.summary, 'concise');
+  assertEquals(body.thinking_budget, 1024);
+  assertEquals(body.adaptive_thinking, true);
+  assertEquals(body.text?.verbosity, 'medium');
+  assertEquals(body.service_tier, 'flex');
+});
+
+test('responses: alias rules overwrite existing reasoning + service_tier fields', () => {
+  const body = resPayload({ reasoning: { effort: 'low', summary: 'auto' }, service_tier: 'default', text: { verbosity: 'high' } });
+  applyChatRulesToResponses(body, {
+    reasoning: { effort: 'xhigh', summary: 'detailed' },
+    verbosity: 'low',
+    serviceTier: 'priority',
+  });
+  assertEquals(body.reasoning?.effort, 'xhigh');
+  assertEquals(body.reasoning?.summary, 'detailed');
+  assertEquals(body.text?.verbosity, 'low');
+  assertEquals(body.service_tier, 'priority');
+});
+
+// ── Messages ──
+
+test('messages: empty rules leave the payload unchanged', () => {
+  const body = msgPayload({ output_config: { effort: 'high' }, thinking: { type: 'enabled', budget_tokens: 512 }, speed: 'fast' });
+  applyChatRulesToMessages(body, {});
+  assertEquals(body.output_config?.effort, 'high');
+  assertEquals(body.thinking?.budget_tokens, 512);
+  assertEquals(body.speed, 'fast');
+});
+
+test('messages: effort lands on output_config, budget+adaptive land on thinking', () => {
+  const body = msgPayload();
+  applyChatRulesToMessages(body, {
+    reasoning: { effort: 'high', budget_tokens: 2048 },
+    verbosity: 'low',
+  });
+  assertEquals(body.output_config?.effort, 'high');
+  assertEquals(body.thinking?.type, 'enabled');
+  assertEquals(body.thinking?.budget_tokens, 2048);
+  assertEquals(body.verbosity, 'low');
+});
+
+test('messages: summary has no Anthropic-shaped slot — silently dropped', () => {
+  // The Messages IR has no reasoning_summary field; the helper must NOT
+  // surface the value onto thinking/output_config/metadata. Pinning the
+  // drop here so a later contributor doesn't wire summary onto a
+  // protocol that can't carry it.
+  const body = msgPayload();
+  applyChatRulesToMessages(body, { reasoning: { summary: 'detailed' } });
+  assertEquals(body.thinking, undefined);
+  assertEquals(body.output_config, undefined);
+  assertEquals(body.metadata, undefined);
+});
+
+test('messages: adaptive=true sets thinking.type=adaptive and ignores budget_tokens', () => {
+  const body = msgPayload();
+  applyChatRulesToMessages(body, { reasoning: { adaptive: true, budget_tokens: 4096 } });
+  assertEquals(body.thinking?.type, 'adaptive');
+});
+
+test('messages: serviceTier=fast maps to speed=fast (cross-protocol bridge)', () => {
+  const body = msgPayload();
+  applyChatRulesToMessages(body, { serviceTier: 'fast' });
+  assertEquals(body.speed, 'fast');
+  assertEquals(body.service_tier, undefined);
+});
+
+test('messages: non-fast serviceTier lands on service_tier directly', () => {
+  const body = msgPayload();
+  applyChatRulesToMessages(body, { serviceTier: 'priority' });
+  assertEquals(body.service_tier, 'priority');
+  assertEquals(body.speed, undefined);
+});
+
+test('messages: serviceTier=fast clears a pre-existing body.service_tier on the same payload', () => {
+  // Upstream must never see both `speed` and `service_tier` set on the
+  // same request — Anthropic treats them as alternates and the wire
+  // semantics for a conflict are undefined. The overlay clears the
+  // sibling field whichever branch it takes.
+  const body = msgPayload({ service_tier: 'priority' });
+  applyChatRulesToMessages(body, { serviceTier: 'fast' });
+  assertEquals(body.speed, 'fast');
+  assertEquals(body.service_tier, undefined);
+});
+
+test('messages: non-fast serviceTier clears a pre-existing body.speed on the same payload', () => {
+  const body = msgPayload({ speed: 'fast' });
+  applyChatRulesToMessages(body, { serviceTier: 'priority' });
+  assertEquals(body.service_tier, 'priority');
+  assertEquals(body.speed, undefined);
+});
+
+test('messages: alias rules overwrite existing thinking + output_config fields', () => {
+  const body = msgPayload({ output_config: { effort: 'low' }, thinking: { type: 'enabled', budget_tokens: 100 } });
+  applyChatRulesToMessages(body, { reasoning: { effort: 'xhigh', budget_tokens: 9999 } });
+  assertEquals(body.output_config?.effort, 'xhigh');
+  assertEquals(body.thinking?.budget_tokens, 9999);
+});
+
+// ── Gemini ──
+
+test('gemini: empty rules leave the payload unchanged', () => {
+  const body = gemPayload({ generationConfig: { thinkingConfig: { thinkingBudget: 256 }, verbosity: 'low' } });
+  applyChatRulesToGemini(body, {});
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingBudget, 256);
+  assertEquals(body.generationConfig?.verbosity, 'low');
+});
+
+test('gemini: effort maps to thinkingLevel; budget lands on thinkingBudget', () => {
+  const body = gemPayload();
+  applyChatRulesToGemini(body, {
+    reasoning: { effort: 'high', budget_tokens: 1024 },
+    verbosity: 'medium',
+    serviceTier: 'flex',
+  });
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingLevel, 'high');
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingBudget, 1024);
+  assertEquals(body.generationConfig?.verbosity, 'medium');
+  assertEquals(body.generationConfig?.serviceTier, 'flex');
+});
+
+test('gemini: adaptive=true encodes thinkingBudget=-1 and overrides any budget_tokens', () => {
+  const body = gemPayload();
+  applyChatRulesToGemini(body, { reasoning: { adaptive: true, budget_tokens: 9999 } });
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingBudget, -1);
+});
+
+test('gemini: alias rules overwrite existing generationConfig fields', () => {
+  const body = gemPayload({ generationConfig: { thinkingConfig: { thinkingBudget: 100, thinkingLevel: 'low' }, verbosity: 'high', serviceTier: 'default' } });
+  applyChatRulesToGemini(body, { reasoning: { effort: 'xhigh', budget_tokens: 2048 }, verbosity: 'low', serviceTier: 'priority' });
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingLevel, 'xhigh');
+  assertEquals(body.generationConfig?.thinkingConfig?.thinkingBudget, 2048);
+  assertEquals(body.generationConfig?.verbosity, 'low');
+  assertEquals(body.generationConfig?.serviceTier, 'priority');
+});
diff --git a/packages/gateway/src/data-plane/model-aliases/header.ts b/packages/gateway/src/data-plane/model-aliases/header.ts
new file mode 100644
index 000000000..4161de03c
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/header.ts
@@ -0,0 +1,8 @@
+// Per-request response header that names the alias the inbound id resolved
+// through. Downstream observability ties together "client asked for X" /
+// "upstream saw Y" via this header.
+//
+// Standalone so transport-level consumers (the alias-prelude in chat serves,
+// the passthrough seam) can import it without dragging in the rule-overlay
+// helpers from `apply.ts`.
+export const ALIAS_RESPONSE_HEADER = 'x-floway-alias';
diff --git a/packages/gateway/src/data-plane/model-aliases/prelude.ts b/packages/gateway/src/data-plane/model-aliases/prelude.ts
new file mode 100644
index 000000000..ca2e48a6b
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/prelude.ts
@@ -0,0 +1,91 @@
+import { ALIAS_RESPONSE_HEADER } from './header.ts';
+import { AliasNoTargetAvailableError, type AliasResolution } from './resolve.ts';
+import type { GatewayCtx } from '../chat/shared/gateway-ctx.ts';
+import { resolveModelCandidates } from '../providers/registry.ts';
+import type { ModelEndpoints } from '@floway-dev/protocols/common';
+import type { ProviderCandidate } from '@floway-dev/provider';
+
+// Structural shape every protocol's no-target-available renderer accepts.
+// Mirrors `Extract<ChatServeFailure, { kind: 'alias-no-target-available' }>`
+// without binding the alias plumbing to the chat-specific failure union.
+export interface AliasNoTargetFailure {
+  readonly kind: 'alias-no-target-available';
+  readonly message: string;
+}
+
+// Shared serve-side prelude every chat protocol — and the passthrough seam —
+// runs before routing. Resolves candidates against the live registry, runs
+// the alias resolver when the inbound id is an alias, stages the
+// `x-floway-alias` response header on every alias-touched code path
+// (including the no-target 404), and converts
+// `AliasNoTargetAvailableError` to whatever rendered failure the caller's
+// `renderAliasFailure` produces. Chat protocols also overlay rules onto the
+// payload via `applyAlias`; passthrough leaves it undefined because the
+// per-call `binding.upstreamModel.id` rewrite happens at the provider
+// boundary, not on the inbound body.
+//
+// Generic over the resolver's per-protocol target descriptor (chat returns
+// `ChatTargetApi`, passthrough returns `ModelEndpointKey`).
+export interface ResolveCandidatesArgs<TTarget, F> {
+  readonly ctx: GatewayCtx;
+  readonly modelName: string;
+  readonly pickTarget: (endpoints: ModelEndpoints) => TTarget | null;
+  readonly applyAlias?: (resolution: AliasResolution) => void;
+  readonly renderAliasFailure: (failure: AliasNoTargetFailure) => F;
+}
+
+export type ResolveCandidatesOk<TTarget> = {
+  readonly kind: 'ok';
+  readonly candidates: ReadonlyArray<ProviderCandidate & { readonly targetApi: TTarget }>;
+  readonly sawModel: boolean;
+  readonly failedUpstreams: readonly string[];
+  readonly aliasResolution: AliasResolution | null;
+  // The model id every downstream surface should use: the alias's
+  // `target_model_id` when an alias matched, the original inbound id
+  // otherwise. Body-based protocols (chat-completions/messages/responses)
+  // already mutate `payload.model` in their `applyAlias` callback and read
+  // that; path-based protocols (Gemini routes the id in the URL) have
+  // nowhere to mutate and read this field instead.
+  readonly effectiveModelId: string;
+};
+
+export type ResolveCandidatesOutcome<TTarget, F> =
+  | ResolveCandidatesOk<TTarget>
+  | { readonly kind: 'failure'; readonly result: F };
+
+export const resolveCandidatesAndApplyAlias = async <TTarget, F>(args: ResolveCandidatesArgs<TTarget, F>): Promise<ResolveCandidatesOutcome<TTarget, F>> => {
+  const { ctx, modelName, pickTarget, applyAlias, renderAliasFailure } = args;
+  let enumerated;
+  try {
+    enumerated = await resolveModelCandidates({
+      upstreamIds: ctx.upstreamIds,
+      modelName,
+      pickTarget,
+      scheduler: ctx.backgroundScheduler,
+      currentColo: ctx.currentColo,
+    });
+  } catch (error) {
+    if (error instanceof AliasNoTargetAvailableError) {
+      // Header staged on the 404 too — observability ties together "client
+      // asked for X" / "alias X had no routable target" without parsing
+      // the body. finalizeGatewayResponse copies ctx.responseHeaders onto
+      // every outbound response, including rendered failures.
+      ctx.responseHeaders.set(ALIAS_RESPONSE_HEADER, error.aliasName);
+      return { kind: 'failure', result: renderAliasFailure({ kind: 'alias-no-target-available', message: error.message }) };
+    }
+    throw error;
+  }
+  const { candidates, sawModel, failedUpstreams, aliasResolution } = enumerated;
+  if (aliasResolution !== null) {
+    applyAlias?.(aliasResolution);
+    ctx.responseHeaders.set(ALIAS_RESPONSE_HEADER, aliasResolution.aliasName);
+  }
+  return {
+    kind: 'ok',
+    candidates: candidates as ResolveCandidatesOk<TTarget>['candidates'],
+    sawModel,
+    failedUpstreams,
+    aliasResolution,
+    effectiveModelId: aliasResolution?.targetModelId ?? modelName,
+  };
+};
diff --git a/packages/gateway/src/data-plane/model-aliases/resolve.ts b/packages/gateway/src/data-plane/model-aliases/resolve.ts
new file mode 100644
index 000000000..33a71e7ad
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/resolve.ts
@@ -0,0 +1,148 @@
+// Alias resolver. Runs once per request, above prefix routing. The target
+// string it returns is fed verbatim back into the existing prefix-router
+// (enumerateModelInterpretations → resolveModelForProvider); alias names
+// never re-enter the alias layer, so recursion is impossible by
+// construction and the shadow-the-real-model pattern (an alias whose first
+// target is its own name) Just Works.
+//
+// The resolver is endpoint-aware on the pool-narrowing axis but
+// kind-blind on the alias-rejection axis. The caller hands in an
+// `endpointAccepts` predicate that decides whether a candidate target's
+// resolved binding actually serves the inbound endpoint; the pool only
+// keeps targets that satisfy it, so first-available / random pick from a
+// set that the prefix router can serve end-to-end. The resolver does NOT
+// reject an alias just because its kind disagrees with the inbound
+// endpoint — that responsibility stays with the predicate, and a
+// kind-mismatched alias surfaces the natural "no target available" 404.
+
+import type { ModelAliasesRepo, ModelAliasRecord } from '../../repo/types.ts';
+import { collectInterpretationOutcomes, enumerateModelInterpretations } from '../providers/registry.ts';
+import type { BackgroundScheduler } from '@floway-dev/platform';
+import type { AliasRules, ModelEndpoints } from '@floway-dev/protocols/common';
+import type { Fetcher, ModelProviderInstance } from '@floway-dev/provider';
+
+export interface AliasResolution {
+  readonly targetModelId: string;
+  readonly rules: AliasRules;
+  // Original alias name, for the `x-floway-alias` response header and dump
+  // attribution.
+  readonly aliasName: string;
+}
+
+// Why the alias's target pool is empty. The resolver keeps targets whose
+// resolved binding exists AND serves the inbound endpoint (per the caller's
+// `endpointAccepts`); a target lost to either check counts toward its
+// respective bucket here.
+type CandidateRoutability =
+  | { readonly routable: true }
+  | { readonly routable: false; readonly reason: 'no-binding' | 'endpoint-mismatch' };
+
+// Canonical wording for the alias-no-target-available 404. The "every
+// target was endpoint-mismatched" branch is its own message so an
+// embeddings client hitting a chat-only alias (or vice versa) sees a hint
+// pointing at the kind/endpoint instead of the generic "no enabled
+// upstream binding" wording.
+const aliasNoTargetMessage = (params: {
+  readonly aliasName: string;
+  readonly targetCount: number;
+  readonly allEndpointMismatch: boolean;
+}): string => {
+  const stem = `alias '${params.aliasName}' has ${params.targetCount} target(s)`;
+  if (params.allEndpointMismatch) {
+    return `${stem}; none currently serves the inbound endpoint`;
+  }
+  return `${stem}; none currently map to an enabled upstream binding`;
+};
+
+// Thrown when the alias name was found but no target currently resolves to
+// an enabled upstream binding that serves the inbound endpoint. Caught at
+// each protocol's serve seam and surfaced as a 404 in the protocol-specific
+// error envelope.
+export class AliasNoTargetAvailableError extends Error {
+  readonly aliasName: string;
+
+  constructor(params: { aliasName: string; targetCount: number; allEndpointMismatch: boolean }) {
+    super(aliasNoTargetMessage(params));
+    this.name = 'AliasNoTargetAvailableError';
+    this.aliasName = params.aliasName;
+  }
+}
+
+interface ResolveAliasArgs {
+  readonly modelName: string;
+  readonly scheduler: BackgroundScheduler;
+  // The same per-request fetcher and provider list the surrounding model
+  // resolver already built. Sharing them keeps the upstream-list + proxy-
+  // factory cost paid once per request rather than twice.
+  readonly providers: readonly ModelProviderInstance[];
+  readonly fetcherForUpstream: (upstreamId: string) => Fetcher;
+  // Predicate the caller supplies to narrow the pool to targets whose
+  // resolved binding serves the inbound endpoint. Chat callers wrap
+  // `pickTarget`; passthrough callers check the specific endpoint key.
+  // A target enters the pool iff at least one of its resolved bindings
+  // returns true here.
+  readonly endpointAccepts: (endpoints: ModelEndpoints) => boolean;
+  // Injected so tests can hand in a stub; the per-request ctx already owns
+  // a concrete one via `getRepo().modelAliases`.
+  readonly repo: ModelAliasesRepo;
+}
+
+// Reports whether the target id resolves to at least one enabled upstream
+// binding whose endpoint map satisfies the inbound endpoint predicate, and
+// distinguishes the two empty-pool causes so `AliasNoTargetAvailableError`
+// can show the right hint.
+const candidateRoutability = async (
+  targetModelId: string,
+  providers: readonly ModelProviderInstance[],
+  fetcherForUpstream: (upstreamId: string) => Fetcher,
+  scheduler: BackgroundScheduler,
+  endpointAccepts: (endpoints: ModelEndpoints) => boolean,
+): Promise<CandidateRoutability> => {
+  if (providers.length === 0) return { routable: false, reason: 'no-binding' };
+  const interpretations = enumerateModelInterpretations(targetModelId, providers);
+  const { resolutions } = await collectInterpretationOutcomes(interpretations, fetcherForUpstream, scheduler);
+  if (resolutions.length === 0) return { routable: false, reason: 'no-binding' };
+  if (resolutions.some(r => endpointAccepts(r.resolved.binding.upstreamModel.endpoints))) return { routable: true };
+  return { routable: false, reason: 'endpoint-mismatch' };
+};
+
+// Pre-pick the available pool ONCE. Order is preserved so
+// selection=first-available picks deterministically; selection=random picks
+// uniformly within whatever subset survived availability filtering.
+// `rejections` collects the reason every dropped target was dropped, so the
+// caller can pin the failure message when the pool is empty.
+const buildAvailablePool = async (
+  record: ModelAliasRecord,
+  providers: readonly ModelProviderInstance[],
+  fetcherForUpstream: (upstreamId: string) => Fetcher,
+  scheduler: BackgroundScheduler,
+  endpointAccepts: (endpoints: ModelEndpoints) => boolean,
+): Promise<{ readonly pool: ModelAliasRecord['targets']; readonly rejections: readonly ('no-binding' | 'endpoint-mismatch')[] }> => {
+  const outcomes = await Promise.all(record.targets.map(target =>
+    candidateRoutability(target.target_model_id, providers, fetcherForUpstream, scheduler, endpointAccepts)));
+  const pool = record.targets.filter((_, index) => outcomes[index].routable);
+  const rejections = outcomes.flatMap(o => o.routable ? [] : [o.reason]);
+  return { pool, rejections };
+};
+
+export const resolveAlias = async (args: ResolveAliasArgs): Promise<AliasResolution | null> => {
+  const { modelName, providers, fetcherForUpstream, scheduler, endpointAccepts, repo } = args;
+  const record = await repo.getByName(modelName);
+  if (!record) return null;
+
+  const { pool, rejections } = await buildAvailablePool(record, providers, fetcherForUpstream, scheduler, endpointAccepts);
+  if (pool.length === 0) {
+    const allEndpointMismatch = rejections.length > 0 && rejections.every(r => r === 'endpoint-mismatch');
+    throw new AliasNoTargetAvailableError({
+      aliasName: record.name,
+      targetCount: record.targets.length,
+      allEndpointMismatch,
+    });
+  }
+
+  const picked = record.selection === 'first-available'
+    ? pool[0]
+    : pool[Math.floor(Math.random() * pool.length)];
+
+  return { targetModelId: picked.target_model_id, rules: picked.rules, aliasName: record.name };
+};
diff --git a/packages/gateway/src/data-plane/model-aliases/resolve_test.ts b/packages/gateway/src/data-plane/model-aliases/resolve_test.ts
new file mode 100644
index 000000000..7640a2232
--- /dev/null
+++ b/packages/gateway/src/data-plane/model-aliases/resolve_test.ts
@@ -0,0 +1,320 @@
+// Behavioral coverage for the alias resolver. Mocks the lower-layer
+// catalog seam (`enumerateModelInterpretations` + `collectInterpretationOutcomes`
+// out of `providers/registry.ts`) so each test can hand-script which
+// target model ids look routable AND what endpoint map their binding
+// advertises; the resolver itself runs unmocked, so its filter logic
+// (availability via the endpointAccepts predicate, selection strategy)
+// is the thing under test.
+
+import { test, vi } from 'vitest';
+
+import type { ModelAliasRecord, ModelAliasesRepo } from '../../repo/types.ts';
+import type { ModelInterpretation, ProviderModelResolution } from '../providers/registry.ts';
+import type { ModelEndpoints } from '@floway-dev/protocols/common';
+import { directFetcher, type Fetcher } from '@floway-dev/provider';
+import { assert, assertEquals, assertRejects } from '@floway-dev/test-utils';
+
+// id → endpoint map. Absent ids look unroutable; present ids return
+// resolutions whose binding advertises the given endpoints, so the
+// resolver's `endpointAccepts` predicate can filter them.
+const routableModels = new Map<string, ModelEndpoints>();
+
+vi.mock('../providers/registry.ts', () => ({
+  enumerateModelInterpretations: vi.fn((modelId: string, providers: readonly { upstream: string }[]): ModelInterpretation[] =>
+    providers.map(p => ({ provider: p, lookupId: modelId } as unknown as ModelInterpretation))),
+  collectInterpretationOutcomes: vi.fn(async (interpretations: readonly { provider: { upstream: string }; lookupId: string }[]) => ({
+    resolutions: interpretations
+      .filter(i => routableModels.has(i.lookupId))
+      .map(i => ({
+        provider: i.provider,
+        resolved: {
+          id: i.lookupId,
+          model: { id: i.lookupId, endpoints: routableModels.get(i.lookupId) },
+          binding: { upstream: i.provider.upstream, upstreamModel: { id: i.lookupId, endpoints: routableModels.get(i.lookupId) } },
+        } as unknown as ProviderModelResolution,
+      })),
+    failedUpstreams: [],
+  })),
+}));
+
+const { resolveAlias, AliasNoTargetAvailableError } = await import('./resolve.ts');
+
+const stubRepoFor = (record: ModelAliasRecord | null): ModelAliasesRepo => ({
+  list: () => Promise.resolve(record ? [record] : []),
+  getByName: name => Promise.resolve(record?.name === name ? structuredClone(record) : null),
+  insert: () => Promise.reject(new Error('insert should not be called from resolver tests')),
+  update: () => Promise.reject(new Error('update should not be called from resolver tests')),
+  delete: () => Promise.resolve(false),
+  deleteAll: () => Promise.resolve(),
+});
+
+const aliasRecord = (overrides: Partial<ModelAliasRecord> = {}): ModelAliasRecord => ({
+  name: 'gpt-fast',
+  kind: 'chat',
+  selection: 'first-available',
+  displayName: null,
+  visibleInModelsList: true,
+  targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } }],
+  announcedMetadata: null,
+  sortOrder: 0,
+  createdAt: '2026-06-26T00:00:00.000Z',
+  updatedAt: '2026-06-26T00:00:00.000Z',
+  ...overrides,
+});
+
+const fetcherForUpstream: (upstreamId: string) => Fetcher = () => directFetcher;
+const providers = [{ upstream: 'u_test', name: 'u_test', modelPrefix: null }] as unknown as Parameters<typeof resolveAlias>[0]['providers'];
+
+const RESOLVE_DEFAULTS = {
+  providers,
+  fetcherForUpstream,
+  scheduler: () => {},
+};
+
+// Mark these ids routable with the full chat-three endpoint set — most
+// tests only care about availability, not which endpoint surface the
+// binding advertises. Endpoint-aware tests use `setRoutableWith` below.
+const setRoutable = (...ids: string[]): void => {
+  routableModels.clear();
+  for (const id of ids) routableModels.set(id, { chatCompletions: {}, messages: {}, responses: {} });
+};
+
+// Endpoint-aware variant: each id carries the exact endpoint map its
+// binding advertises. Lets a test pin "target A serves /chat/completions,
+// target B only serves /messages" so the resolver's pool-narrowing can
+// be verified.
+const setRoutableWith = (entries: Record<string, ModelEndpoints>): void => {
+  routableModels.clear();
+  for (const [id, endpoints] of Object.entries(entries)) routableModels.set(id, endpoints);
+};
+
+test('returns null when no alias matches the inbound name', async () => {
+  setRoutable('gpt-5.4');
+  const result = await resolveAlias({
+    endpointAccepts: () => true,
+    ...RESOLVE_DEFAULTS,
+    modelName: 'not-an-alias',
+    repo: stubRepoFor(null),
+  });
+  assertEquals(result, null);
+});
+
+test('returns the target and rules when a single target is available', async () => {
+  setRoutable('gpt-5.4');
+  const result = await resolveAlias({
+    endpointAccepts: () => true,
+    ...RESOLVE_DEFAULTS,
+    modelName: 'gpt-fast',
+    repo: stubRepoFor(aliasRecord()),
+  });
+  assert(result !== null);
+  assertEquals(result.targetModelId, 'gpt-5.4');
+  assertEquals(result.aliasName, 'gpt-fast');
+  assertEquals(result.rules, { reasoning: { effort: 'low' } });
+});
+
+test('throws AliasNoTargetAvailableError when the alias exists but no target is currently routable', async () => {
+  setRoutable(); // catalog empty
+  await assertRejects(
+    () => resolveAlias({
+      endpointAccepts: () => true,
+      ...RESOLVE_DEFAULTS,
+      modelName: 'gpt-fast',
+      repo: stubRepoFor(aliasRecord({
+        targets: [
+          { target_model_id: 'gpt-5.4', rules: {} },
+          { target_model_id: 'gpt-5.5', rules: {} },
+        ],
+      })),
+    }),
+    AliasNoTargetAvailableError,
+    "alias 'gpt-fast' has 2 target(s); none currently map to an enabled upstream binding",
+  );
+});
+
+test('first-available skips unroutable rows and picks the first available, not the first listed', async () => {
+  setRoutable('gpt-5.5'); // `gpt-5.4` is not in the catalog
+  const result = await resolveAlias({
+    endpointAccepts: () => true,
+    ...RESOLVE_DEFAULTS,
+    modelName: 'gpt-fast',
+    repo: stubRepoFor(aliasRecord({
+      targets: [
+        { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'high' } } },
+        { target_model_id: 'gpt-5.5', rules: { reasoning: { effort: 'low' } } },
+        { target_model_id: 'gpt-6', rules: {} },
+      ],
+    })),
+  });
+  assert(result !== null);
+  assertEquals(result.targetModelId, 'gpt-5.5');
+  assertEquals(result.rules, { reasoning: { effort: 'low' } });
+});
+
+test('random selection picks every available target across enough iterations', async () => {
+  setRoutable('a', 'b');
+  const seen = new Set<string>();
+  for (let i = 0; i < 100; i += 1) {
+    const result = await resolveAlias({
+      endpointAccepts: () => true,
+      ...RESOLVE_DEFAULTS,
+      modelName: 'gpt-fast',
+      repo: stubRepoFor(aliasRecord({
+        selection: 'random',
+        targets: [
+          { target_model_id: 'a', rules: {} },
+          { target_model_id: 'b', rules: {} },
+        ],
+      })),
+    });
+    assert(result !== null);
+    seen.add(result.targetModelId);
+    if (seen.size === 2) break;
+  }
+  // Two targets, both routable, 100 iterations: hitting only one is a
+  // (1/2)^100 fluke. Treat anything less than two distinct picks as a real
+  // regression in the selection logic, not coincidence.
+  assertEquals(seen.size, 2);
+});
+
+test('shadow pattern: alias whose first target equals its own name picks the real model when present', async () => {
+  setRoutable('codex-auto-review'); // the real model IS in the catalog
+  const result = await resolveAlias({
+    endpointAccepts: () => true,
+    ...RESOLVE_DEFAULTS,
+    modelName: 'codex-auto-review',
+    repo: stubRepoFor(aliasRecord({
+      name: 'codex-auto-review',
+      targets: [
+        { target_model_id: 'codex-auto-review', rules: {} },
+        { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } },
+      ],
+    })),
+  });
+  assert(result !== null);
+  assertEquals(result.targetModelId, 'codex-auto-review');
+  assertEquals(result.rules, {});
+});
+
+test('shadow pattern: alias falls back to the second target when the real model is not in the catalog', async () => {
+  setRoutable('gpt-5.4'); // only the fallback is routable
+  const result = await resolveAlias({
+    endpointAccepts: () => true,
+    ...RESOLVE_DEFAULTS,
+    modelName: 'codex-auto-review',
+    repo: stubRepoFor(aliasRecord({
+      name: 'codex-auto-review',
+      targets: [
+        { target_model_id: 'codex-auto-review', rules: {} },
+        { target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } },
+      ],
+    })),
+  });
+  assert(result !== null);
+  assertEquals(result.targetModelId, 'gpt-5.4');
+  assertEquals(result.rules, { reasoning: { effort: 'low' } });
+});
+
+test('endpoint-aware pool: random selection picks ONLY from targets whose binding serves the inbound endpoint', async () => {
+  // Two targets: A serves /chat/completions; B only serves /messages.
+  // Inbound endpoint = /chat/completions (predicate keeps only A). Run 50
+  // iterations of `random` selection and assert B is never picked — if
+  // the resolver were endpoint-blind, B would surface ~half the time and
+  // the downstream prefix router would 404.
+  setRoutableWith({
+    'serves-cc': { chatCompletions: {} },
+    'serves-messages-only': { messages: {} },
+  });
+  const repo = stubRepoFor(aliasRecord({
+    selection: 'random',
+    targets: [
+      { target_model_id: 'serves-cc', rules: {} },
+      { target_model_id: 'serves-messages-only', rules: {} },
+    ],
+  }));
+  const picks = new Set<string>();
+  for (let i = 0; i < 50; i++) {
+    const result = await resolveAlias({
+      modelName: 'gpt-fast',
+      ...RESOLVE_DEFAULTS,
+      endpointAccepts: endpoints => endpoints.chatCompletions !== undefined,
+      repo,
+    });
+    assert(result !== null);
+    picks.add(result.targetModelId);
+  }
+  assertEquals([...picks], ['serves-cc']);
+});
+
+test('endpoint-aware pool: first-available skips targets whose binding does not serve the inbound endpoint', async () => {
+  // Configured order [A, B]: A only serves /messages, B serves /chat/completions.
+  // Inbound endpoint = /chat/completions. first-available without endpoint
+  // narrowing would pick A and downstream 404. With narrowing the pool
+  // becomes [B], and first-available returns B.
+  setRoutableWith({
+    'messages-only': { messages: {} },
+    'serves-cc': { chatCompletions: {} },
+  });
+  const repo = stubRepoFor(aliasRecord({
+    selection: 'first-available',
+    targets: [
+      { target_model_id: 'messages-only', rules: {} },
+      { target_model_id: 'serves-cc', rules: {} },
+    ],
+  }));
+  const result = await resolveAlias({
+    modelName: 'gpt-fast',
+    ...RESOLVE_DEFAULTS,
+    endpointAccepts: endpoints => endpoints.chatCompletions !== undefined,
+    repo,
+  });
+  assert(result !== null);
+  assertEquals(result.targetModelId, 'serves-cc');
+});
+
+test('endpoint-aware pool: alias with NO target serving the inbound endpoint throws AliasNoTargetAvailableError and pins the endpoint-mismatch wording', async () => {
+  setRoutableWith({
+    'a': { messages: {} },
+    'b': { messages: {} },
+  });
+  const repo = stubRepoFor(aliasRecord({
+    targets: [
+      { target_model_id: 'a', rules: {} },
+      { target_model_id: 'b', rules: {} },
+    ],
+  }));
+  await assertRejects(
+    () => resolveAlias({
+      modelName: 'gpt-fast',
+      ...RESOLVE_DEFAULTS,
+      endpointAccepts: endpoints => endpoints.chatCompletions !== undefined,
+      repo,
+    }),
+    AliasNoTargetAvailableError,
+    'none currently serves the inbound endpoint',
+  );
+});
+
+test('alias with every target unresolvable to any upstream throws AliasNoTargetAvailableError and pins the no-binding wording', async () => {
+  // Empty routable map → no target resolves to any binding at all. The
+  // error message stays on the canonical "no enabled upstream binding"
+  // wording so an operator who removed every binding sees that hint
+  // rather than the endpoint-mismatch one.
+  setRoutableWith({});
+  const repo = stubRepoFor(aliasRecord({
+    targets: [
+      { target_model_id: 'gone-1', rules: {} },
+      { target_model_id: 'gone-2', rules: {} },
+    ],
+  }));
+  await assertRejects(
+    () => resolveAlias({
+      modelName: 'gpt-fast',
+      ...RESOLVE_DEFAULTS,
+      endpointAccepts: () => true,
+      repo,
+    }),
+    AliasNoTargetAvailableError,
+    'none currently map to an enabled upstream binding',
+  );
+});
diff --git a/packages/gateway/src/data-plane/models/alias-listing.ts b/packages/gateway/src/data-plane/models/alias-listing.ts
new file mode 100644
index 000000000..b058ea29b
--- /dev/null
+++ b/packages/gateway/src/data-plane/models/alias-listing.ts
@@ -0,0 +1,353 @@
+// Synthesizes the alias entries that join the real-model catalog inside
+// `/v1/models`. One PublicModel per visible alias. The synthesized entry
+// carries an `aliasedFrom` block so an alias-aware UI can render the
+// alias-of relationship without a second round trip.
+//
+// `limits`, `chat`, `endpoints`, and `cost` are computed against the
+// GATEWAY-WIDE addressable surface — every caller sees the same numbers
+// for the same alias, independent of their data-plane cap. The operator's
+// stored `announced_metadata` override still wins at sub-block
+// granularity (a present `limits` / `chat` replaces the computed
+// counterpart wholesale, not per-leaf). The intersection is the safe
+// lower bound for the inbound request — every reported capability
+// survives no matter which target the resolver picks.
+//
+// The rule-aware part: when an alias's rule pins a value at a target,
+// that target is treated as "unsupported" for the corresponding
+// sub-field for the purposes of the intersection. A pinned rule
+// already fixes whatever value the listing would have advertised, so
+// dropping the sub-field from the announced metadata keeps the wire
+// surface honest about what the operator left for the caller to set.
+//
+// Caller-scope (the addressable surface this specific request can
+// reach) controls only two things: whether the alias appears in this
+// caller's response (at least one target reachable under the cap), and
+// the `aliasedFrom.targets` projection when `narrowTargets` is true.
+//
+// Collision: when an alias's `name` exactly equals a real model id, the
+// alias entry replaces the real entry in the final catalog. Two entries
+// with the same `id` would break OpenAI client deduplication; collapsing
+// to the alias entry preserves the operator's intent (the alias is the
+// reason both rows would have been present). The real entry is removed
+// at the `loadModels` merge step.
+
+import type { ModelAliasRecord } from '../../repo/types.ts';
+import type { AddressableIdEntry } from '../providers/addressable.ts';
+import { unionEndpoints } from '../providers/endpoint-union.ts';
+import { composeAliasDisplayName } from '@floway-dev/protocols/common';
+import type { AliasTarget, AnnouncedMetadata, ChatModelInfo, PublicModel, PublicModelAliasedFrom, PublicModelLimits } from '@floway-dev/protocols/common';
+import type { ResolvedModel } from '@floway-dev/provider';
+
+export interface ListedAliasInputs {
+  readonly aliases: readonly ModelAliasRecord[];
+  // Gateway-wide addressable surface — used for the metadata + endpoints
+  // + cost computations that must be stable across callers. A target
+  // resolvable only via an upstream the current caller cannot reach
+  // STILL contributes to the safe-lower-bound intersection the catalog
+  // publishes, because the same alias must look the same to every
+  // user (admin, non-admin, api key).
+  readonly gatewayAddressableModelIds: readonly AddressableIdEntry[];
+  // Caller-scoped addressable surface. Decides (a) whether this alias
+  // is visible to the caller at all (must have at least one target
+  // reachable under the caller's cap) and (b) the `aliasedFrom.targets`
+  // projection when `narrowTargets` is true. For unrestricted callers
+  // (admin gateway-wide) pass the same array as `gatewayAddressableModelIds`.
+  readonly callerAddressableModelIds: readonly AddressableIdEntry[];
+  // True for callers whose `aliasedFrom.targets` projection must omit
+  // any configured target the addressable surface cannot serve — every
+  // data-plane response, and non-admin control-plane responses. False
+  // for admin sessions on the control plane: the alias-edit dialog
+  // needs to see every target the operator wired, including typos and
+  // targets on upstreams the admin self-restricted out of, so the
+  // configuration is editable end to end.
+  readonly narrowTargets: boolean;
+}
+
+// Result preserves the order of `arrays[0]`. Matters for callers like the
+// reasoning-effort intersection below: when no agreed-default exists, the
+// fallback default is `supported[0]`, so the first input's relative order
+// determines which level wins as the listing's `default`.
+const intersectArrays = <T>(arrays: readonly (readonly T[])[]): T[] => {
+  if (arrays.length === 0) return [];
+  const [head, ...tail] = arrays;
+  return head.filter(value => tail.every(other => other.includes(value)));
+};
+
+// Apply the rule-driven downgrade: a target with a pinned rule reports
+// the corresponding catalog sub-field as unsupported (= undefined) for
+// the purposes of intersection. Fields the rule doesn't touch pass
+// through unchanged.
+const effectiveChatForIntersection = (chat: ChatModelInfo | undefined, target: AliasTarget): ChatModelInfo | undefined => {
+  if (chat === undefined) return undefined;
+  const ruleReasoning = target.rules.reasoning;
+  if (ruleReasoning === undefined) return chat;
+  if (chat.reasoning === undefined) return chat;
+
+  const reasoning: NonNullable<ChatModelInfo['reasoning']> = { ...chat.reasoning };
+  if (ruleReasoning.effort !== undefined) delete reasoning.effort;
+  if (ruleReasoning.budget_tokens !== undefined) delete reasoning.budget_tokens;
+  if (ruleReasoning.adaptive === true) delete reasoning.adaptive;
+
+  return { ...chat, reasoning };
+};
+
+const intersectChat = (chats: readonly ChatModelInfo[]): ChatModelInfo | undefined => {
+  const result: ChatModelInfo = {};
+
+  const modalityChats = chats.filter(c => c.modalities !== undefined);
+  if (modalityChats.length === chats.length) {
+    const input = intersectArrays(modalityChats.map(c => c.modalities!.input));
+    const output = intersectArrays(modalityChats.map(c => c.modalities!.output));
+    // Both halves must survive — an alias that consumes a modality but
+    // promises no output (or the inverse) is incoherent. Omit the block
+    // entirely when either intersection collapses.
+    if (input.length > 0 && output.length > 0) result.modalities = { input, output };
+  }
+
+  const reasoningChats = chats.filter(c => c.reasoning !== undefined);
+  if (reasoningChats.length === chats.length) {
+    const reasoning: NonNullable<ChatModelInfo['reasoning']> = {};
+
+    const effortChats = reasoningChats.filter(c => c.reasoning!.effort !== undefined);
+    if (effortChats.length === reasoningChats.length) {
+      const supported = intersectArrays(effortChats.map(c => c.reasoning!.effort!.supported));
+      const defaults = new Set(effortChats.map(c => c.reasoning!.effort!.default));
+      // Intersection's `default` is the agreed value when every target
+      // names the same one and that value still survives the supported
+      // intersection; otherwise we report supported-only.
+      if (supported.length > 0) {
+        const agreedDefault = defaults.size === 1 ? [...defaults][0] : undefined;
+        reasoning.effort = agreedDefault !== undefined && supported.includes(agreedDefault)
+          ? { supported, default: agreedDefault }
+          : { supported, default: supported[0] };
+      }
+    }
+
+    const budgetChats = reasoningChats.filter(c => c.reasoning!.budget_tokens !== undefined);
+    if (budgetChats.length === reasoningChats.length) {
+      const mins = budgetChats.map(c => c.reasoning!.budget_tokens!.min).filter((v): v is number => v !== undefined);
+      const maxes = budgetChats.map(c => c.reasoning!.budget_tokens!.max).filter((v): v is number => v !== undefined);
+      // Require BOTH min and max to be all-declared, mirroring how
+      // `effort`, `adaptive`, and `mandatory` all collapse the moment one
+      // target leaves a leaf undeclared. A half-declared block (e.g.
+      // `{ min }` with no max) would advertise a capability some target
+      // does not actually report.
+      if (mins.length === budgetChats.length && maxes.length === budgetChats.length) {
+        const min = Math.max(...mins);
+        const max = Math.min(...maxes);
+        // Drop the budget block when the intersected window is empty —
+        // a contradictory range is worse than no advertisement.
+        if (min <= max) reasoning.budget_tokens = { min, max };
+      }
+    }
+
+    const adaptiveAgreed = new Set(reasoningChats.map(c => c.reasoning!.adaptive));
+    if (adaptiveAgreed.size === 1) {
+      const value = [...adaptiveAgreed][0];
+      if (value !== undefined) reasoning.adaptive = value;
+    }
+    const mandatoryAgreed = new Set(reasoningChats.map(c => c.reasoning!.mandatory));
+    if (mandatoryAgreed.size === 1) {
+      const value = [...mandatoryAgreed][0];
+      if (value !== undefined) reasoning.mandatory = value;
+    }
+
+    if (Object.keys(reasoning).length > 0) result.reasoning = reasoning;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+// `limits` intersection: min across targets per field; the field is
+// absent when any target leaves it undeclared. Matches the safe-lower-
+// bound contract — whichever target the resolver picks, the reported
+// window is one every target can actually serve.
+const LIMIT_KEYS = ['max_context_window_tokens', 'max_prompt_tokens', 'max_output_tokens'] as const;
+
+const intersectLimits = (limitsList: readonly PublicModelLimits[]): PublicModelLimits => {
+  if (limitsList.length === 0) return {};
+  const result: PublicModelLimits = {};
+  for (const key of LIMIT_KEYS) {
+    const values = limitsList.map(l => l[key]).filter((v): v is number => v !== undefined);
+    if (values.length === limitsList.length) result[key] = Math.min(...values);
+  }
+  return result;
+};
+
+// `narrowTargets=true` filters `targets` to those the caller's addressable
+// surface can serve — protects non-admin / data-plane callers from seeing
+// operator state (target IDs from upstreams they have no access to, plus
+// typo'd / removed model IDs). `narrowTargets=false` is the admin-debug
+// view: every configured target survives so the dashboard's alias editor
+// can render the full configuration even when the admin self-restricted.
+const buildAliasedFrom = (
+  alias: ModelAliasRecord,
+  addressableModelIds: readonly AddressableIdEntry[],
+  narrowTargets: boolean,
+): PublicModelAliasedFrom => {
+  if (!narrowTargets) {
+    return { name: alias.name, kind: alias.kind, selection: alias.selection, targets: alias.targets };
+  }
+  const addressableSet = new Set(addressableModelIds.map(entry => entry.id));
+  const targets = alias.targets.filter(t => addressableSet.has(t.target_model_id));
+  return { name: alias.name, kind: alias.kind, selection: alias.selection, targets };
+};
+
+// Compute the rule-aware intersection (`limits` + `chat`) over the
+// alias's currently-available targets. Caller decides whether to use
+// the result directly or overlay it under an operator override.
+const computeAutomaticMetadata = (
+  availableTargets: readonly { target: AliasTarget; real: ResolvedModel }[],
+): { limits: PublicModelLimits; chat: ChatModelInfo | undefined } => {
+  const limits = intersectLimits(availableTargets.map(({ real }) => real.limits));
+
+  const effectiveChats = availableTargets
+    .map(({ target, real }) => effectiveChatForIntersection(real.chat, target))
+    .filter((c): c is ChatModelInfo => c !== undefined);
+  // Intersect chat metadata only when every available target carries it
+  // (post-downgrade); a half-declared block would leak the metadata of
+  // whichever subset happened to carry it.
+  const chat = effectiveChats.length === availableTargets.length
+    ? intersectChat(effectiveChats)
+    : undefined;
+
+  return { limits, chat };
+};
+
+// Merge the operator's override on top of the computed payload at the
+// top-level sub-block boundary: a present `limits` / `chat` on the
+// override replaces the computed counterpart wholesale; an omitted
+// sub-block falls back to the computed value. (Merge is intentionally
+// NOT per-leaf — that's the contract `AnnouncedMetadata` advertises.)
+const mergeWithOverride = (
+  computed: { limits: PublicModelLimits; chat: ChatModelInfo | undefined },
+  override: AnnouncedMetadata,
+): { limits: PublicModelLimits; chat: ChatModelInfo | undefined } => ({
+  limits: override.limits ?? computed.limits,
+  chat: override.chat ?? computed.chat,
+});
+
+// Returns null when no target serves this alias on the gateway, OR when the
+// caller cannot reach any of the configured targets — the catalog should
+// never advertise an id the caller would 404 on. The alias itself stays
+// addressable through `resolveAlias`, which surfaces
+// `AliasNoTargetAvailableError` at request time. Callers
+// (`synthesizeListedAliases`) filter the nulls out.
+const synthesizeOne = (
+  alias: ModelAliasRecord,
+  gatewayAddressableModelIds: readonly AddressableIdEntry[],
+  callerAddressableModelIds: readonly AddressableIdEntry[],
+  narrowTargets: boolean,
+): PublicModel | null => {
+  // Gateway-wide kind-matched targets — the basis for stable metadata.
+  // A target reachable only via a prefix-addressable alternate or a
+  // provider-side redirect (Copilot variant id) still counts.
+  const gatewayById = new Map(gatewayAddressableModelIds.map(entry => [entry.id, entry.model] as const));
+  const gatewayAvailable = alias.targets
+    .map(target => ({ target, real: gatewayById.get(target.target_model_id) }))
+    .filter((entry): entry is { target: AliasTarget; real: ResolvedModel } => entry.real !== undefined && entry.real.kind === alias.kind);
+  if (gatewayAvailable.length === 0) return null;
+
+  // Caller-scope visibility: the alias appears only if at least one
+  // gateway-available target sits inside the caller's addressable cap.
+  const callerSet = new Set(callerAddressableModelIds.map(entry => entry.id));
+  const callerHasAny = gatewayAvailable.some(e => callerSet.has(e.target.target_model_id));
+  if (!callerHasAny) return null;
+
+  // Display name precedence: operator-set wins; otherwise derive from the
+  // sole target's id + rules when single-target; multi-target falls back to
+  // the alias's own name because no single target represents the alias.
+  // Uses the configured `alias.targets.length` (stable across callers)
+  // rather than the per-caller reachable count.
+  const displayName = alias.displayName ?? (alias.targets.length === 1
+    ? composeAliasDisplayName(alias.targets[0].target_model_id, alias.targets[0].rules)
+    : alias.name);
+
+  // Metadata + endpoints + cost computed against gateway-wide — every
+  // caller sees the same numbers for the same alias, so a non-admin
+  // restricted to a subset of upstreams never sees a more permissive
+  // limit than the admin who knows the alias's true safe-lower-bound.
+  const computed = computeAutomaticMetadata(gatewayAvailable);
+  const { limits, chat } = alias.announcedMetadata !== null
+    ? mergeWithOverride(computed, alias.announcedMetadata)
+    : computed;
+
+  // Endpoints follow the gateway-wide union — every endpoint reachable
+  // through ANY gateway target is advertised. The resolver's
+  // request-time pool narrows to targets that serve the inbound endpoint;
+  // a caller hitting an endpoint that's only available through an out-of-
+  // cap target gets the natural `AliasNoTargetAvailableError` 404.
+  const endpoints = unionEndpoints(gatewayAvailable.map(({ real }) => real.endpoints));
+
+  const entry: PublicModel = {
+    id: alias.name,
+    object: 'model',
+    type: 'model',
+    display_name: displayName,
+    limits,
+    kind: alias.kind,
+    endpoints,
+    aliasedFrom: buildAliasedFrom(alias, callerAddressableModelIds, narrowTargets),
+  };
+  if (chat !== undefined) entry.chat = chat;
+
+  // Gateway-wide single-target chat pricing rides along when available.
+  // Stable across callers — same alias publishes the same cost
+  // everywhere.
+  if (gatewayAvailable.length === 1) {
+    const [{ real }] = gatewayAvailable;
+    if (real.cost !== undefined) entry.cost = real.cost;
+  }
+
+  return entry;
+};
+
+const sortAliases = (aliases: readonly ModelAliasRecord[]): ModelAliasRecord[] =>
+  [...aliases].sort((a, b) => (a.sortOrder - b.sortOrder) || a.name.localeCompare(b.name));
+
+export const synthesizeListedAliases = (input: ListedAliasInputs): PublicModel[] =>
+  sortAliases(input.aliases)
+    .filter(alias => alias.visibleInModelsList)
+    .map(alias => synthesizeOne(alias, input.gatewayAddressableModelIds, input.callerAddressableModelIds, input.narrowTargets))
+    .filter((entry): entry is PublicModel => entry !== null);
+
+// Compose real-model entries with visible alias entries into a single typed
+// list. Both data-plane `/v1/models` and the dashboard's `/api/models`
+// share the same merge rule: when an alias's `name` collides with a real
+// model id, the alias entry wins and the colliding real entry is dropped
+// — two entries with the same `id` would break OpenAI-client deduplication,
+// and the alias was added by the operator deliberately, so collapsing to
+// it preserves intent. `mapReal` shapes each real model into the caller's
+// row type; `wrapAlias` lifts a synthesized `PublicModel` alias entry into
+// the same row type (the dashboard, for example, adds an empty `upstreams`
+// array since alias rows do not bind to an upstream directly; the Gemini
+// `/v1beta/models` route maps into the upstream's `InternalModel` shape
+// before projecting to Gemini's wire form).
+//
+// `realModels` is the listed projection — what `/v1/models` and the
+// dashboard's default `/api/models` row stream emit (caller-scoped).
+// The two addressable surfaces feed the alias synthesizer's metadata-vs-
+// visibility split; the merge step never promotes addressable-but-not-
+// listed ids to real-model rows.
+export const mergeAliasesIntoModels = <T>(input: {
+  readonly realModels: readonly ResolvedModel[];
+  readonly gatewayAddressableModelIds: readonly AddressableIdEntry[];
+  readonly callerAddressableModelIds: readonly AddressableIdEntry[];
+  readonly aliases: readonly ModelAliasRecord[];
+  readonly narrowTargets: boolean;
+  readonly mapReal: (model: ResolvedModel) => T;
+  readonly wrapAlias: (entry: PublicModel) => T;
+}): T[] => {
+  const { realModels, gatewayAddressableModelIds, callerAddressableModelIds, aliases, narrowTargets, mapReal, wrapAlias } = input;
+  const aliasEntries = synthesizeListedAliases({
+    aliases,
+    gatewayAddressableModelIds,
+    callerAddressableModelIds,
+    narrowTargets,
+  });
+  const aliasIds = new Set(aliasEntries.map(entry => entry.id));
+  return [
+    ...realModels.filter(model => !aliasIds.has(model.id)).map(mapReal),
+    ...aliasEntries.map(wrapAlias),
+  ];
+};
diff --git a/packages/gateway/src/data-plane/models/alias-listing_test.ts b/packages/gateway/src/data-plane/models/alias-listing_test.ts
new file mode 100644
index 000000000..663abdac1
--- /dev/null
+++ b/packages/gateway/src/data-plane/models/alias-listing_test.ts
@@ -0,0 +1,512 @@
+import { describe, expect, test } from 'vitest';
+
+import { synthesizeListedAliases } from './alias-listing.ts';
+import type { ModelAliasRecord } from '../../repo/types.ts';
+import type { AddressableIdEntry } from '../providers/addressable.ts';
+import type { ResolvedModel } from '@floway-dev/provider';
+
+const aliasFixture = (overrides: Partial<ModelAliasRecord> = {}): ModelAliasRecord => ({
+  name: 'gpt-fast',
+  kind: 'chat',
+  selection: 'first-available',
+  displayName: null,
+  visibleInModelsList: true,
+  targets: [{ target_model_id: 'gpt-5.4', rules: {} }],
+  announcedMetadata: null,
+  sortOrder: 0,
+  createdAt: '2026-06-26T00:00:00.000Z',
+  updatedAt: '2026-06-26T00:00:00.000Z',
+  ...overrides,
+});
+
+const realModel = (overrides: Partial<ResolvedModel> & { id: string }): ResolvedModel => ({
+  kind: 'chat',
+  limits: {},
+  endpoints: { chatCompletions: {}, messages: {}, responses: {} },
+  providers: [],
+  ...overrides,
+});
+
+// Adapt the fixtures' "list of real models" view to the addressable surface
+// the synthesizer now consumes — every fixture entry is a listed catalog row.
+const listed = (models: readonly ResolvedModel[]): AddressableIdEntry[] =>
+  models.map(model => ({ id: model.id, unlisted: undefined, model }));
+
+// Test-only addressable surface that pretends a model is reachable through
+// a redirect (e.g. a Copilot variant id). The synthesizer should treat
+// such targets as available even though they never appear in the listed
+// catalog.
+const unlisted = (id: string, model: ResolvedModel): AddressableIdEntry => ({ id, unlisted: true, model });
+
+describe('synthesizeListedAliases', () => {
+  test('single-target alias with a pinned reasoning.effort drops the effort block', () => {
+    const aliases = [aliasFixture({
+      name: 'gpt-fast',
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } }],
+    })];
+    const realModels = [realModel({
+      id: 'gpt-5.4',
+      display_name: 'GPT 5.4',
+      chat: {
+        modalities: { input: ['text', 'image'], output: ['text'] },
+        reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } },
+      },
+    })];
+
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.id).toBe('gpt-fast');
+    expect(entry.display_name).toBe('gpt-5.4 (low effort)');
+    // The rule pins effort, so the announced metadata drops it — the
+    // caller already knows the value because the alias fixes it.
+    expect(entry.chat?.reasoning).toBeUndefined();
+    expect(entry.chat?.modalities).toEqual({ input: ['text', 'image'], output: ['text'] });
+    expect(entry.aliasedFrom).toEqual({
+      name: 'gpt-fast',
+      kind: 'chat',
+      selection: 'first-available',
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } }],
+    });
+  });
+
+  test('single-target alias with a pinned reasoning.budget_tokens drops the budget block', () => {
+    const aliases = [aliasFixture({
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { budget_tokens: 4096 } } }],
+    })];
+    const realModels = [realModel({
+      id: 'gpt-5.4',
+      chat: { reasoning: { budget_tokens: { min: 1024, max: 65536 } } },
+    })];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning).toBeUndefined();
+  });
+
+  test('multi-target alias drops budget_tokens when one target declares only min and another only max', () => {
+    // A half-declared block (e.g. publishing `{ min }` without max) would
+    // advertise a capability some target does not report. The intersection
+    // must collapse to undefined, matching how `effort` / `adaptive` /
+    // `mandatory` already behave.
+    const aliases = [aliasFixture({
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { reasoning: { budget_tokens: { min: 1024 } } } }),
+      realModel({ id: 'b', chat: { reasoning: { budget_tokens: { max: 65536 } } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning).toBeUndefined();
+  });
+
+  test('multi-target alias intersects chat.modalities across every target', () => {
+    const aliases = [aliasFixture({
+      name: 'smart-router',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { modalities: { input: ['text', 'image'], output: ['text'] } } }),
+      realModel({ id: 'b', chat: { modalities: { input: ['text'], output: ['text'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.id).toBe('smart-router');
+    expect(entry.display_name).toBe('smart-router');
+    expect(entry.chat?.modalities).toEqual({ input: ['text'], output: ['text'] });
+  });
+
+  test('multi-target intersection drops capabilities only one target declares', () => {
+    const aliases = [aliasFixture({
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { reasoning: { effort: { supported: ['low'], default: 'low' } } } }),
+      realModel({ id: 'b', chat: {} }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning).toBeUndefined();
+  });
+
+  test('multi-target with disjoint output modalities omits the modalities block entirely', () => {
+    // Both targets share text input but their output modalities do not
+    // overlap. Advertising `{ input: ['text'], output: [] }` would claim a
+    // chat model that consumes text and produces nothing — incoherent —
+    // so the synthesizer omits the modalities block when either half of
+    // the intersection collapses.
+    const aliases = [aliasFixture({
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { modalities: { input: ['text'], output: ['text'] } } }),
+      realModel({ id: 'b', chat: { modalities: { input: ['text'], output: ['image'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.modalities).toBeUndefined();
+  });
+
+  test('multi-target with an unavailable target intersects over the available subset', () => {
+    const aliases = [aliasFixture({
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'gone', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { modalities: { input: ['text', 'image'], output: ['text'] } } }),
+      realModel({ id: 'b', chat: { modalities: { input: ['text'], output: ['text', 'image'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.modalities).toEqual({ input: ['text'], output: ['text'] });
+    // Every configured target — including the unavailable one — survives in aliasedFrom.
+    expect(entry.aliasedFrom?.targets.map(t => t.target_model_id)).toEqual(['a', 'gone', 'b']);
+  });
+
+  test('hidden alias is not emitted', () => {
+    const aliases = [aliasFixture({ visibleInModelsList: false })];
+    const realModels = [realModel({ id: 'gpt-5.4' })];
+    expect(synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false })).toEqual([]);
+  });
+
+  test('alias whose name collides with a real id is emitted (loadModels drops the duplicate real)', () => {
+    const aliases = [aliasFixture({
+      name: 'gpt-5.4',
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } }],
+    })];
+    const realModels = [realModel({ id: 'gpt-5.4', display_name: 'GPT 5.4' })];
+    const entries = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].id).toBe('gpt-5.4');
+    expect(entries[0].aliasedFrom?.name).toBe('gpt-5.4');
+  });
+
+  test('no available targets means the alias is hidden from the listing (resolver still returns 404 for the alias itself)', () => {
+    const aliases = [aliasFixture({
+      name: 'orphan',
+      targets: [{ target_model_id: 'missing', rules: {} }],
+    })];
+    expect(synthesizeListedAliases({ aliases, gatewayAddressableModelIds: [], callerAddressableModelIds: [], narrowTargets: false })).toEqual([]);
+  });
+
+  test('sorts entries by (sort_order, name) so listing order stays stable', () => {
+    const aliases = [
+      aliasFixture({ name: 'late', sortOrder: 1 }),
+      aliasFixture({ name: 'mid-a', sortOrder: 0 }),
+      aliasFixture({ name: 'mid-b', sortOrder: 0 }),
+    ];
+    const realModels = [realModel({ id: 'gpt-5.4' })];
+    const ids = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false }).map(entry => entry.id);
+    expect(ids).toEqual(['mid-a', 'mid-b', 'late']);
+  });
+
+  test('targets whose kind disagrees with the alias are not counted as available', () => {
+    const aliases = [aliasFixture({
+      kind: 'chat',
+      targets: [
+        { target_model_id: 'emb', rules: {} },
+        { target_model_id: 'chat', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'emb', kind: 'embedding' }),
+      realModel({ id: 'chat', chat: { modalities: { input: ['text'], output: ['text'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    // Only the chat target backs the metadata — the embedding row never
+    // enters the intersection / narrowing path.
+    expect(entry.chat?.modalities).toEqual({ input: ['text'], output: ['text'] });
+  });
+
+  test('operator-set display_name wins over the derived form', () => {
+    const aliases = [aliasFixture({
+      displayName: 'My Fast GPT',
+      targets: [{ target_model_id: 'gpt-5.4', rules: { reasoning: { effort: 'low' } } }],
+    })];
+    const realModels = [realModel({ id: 'gpt-5.4' })];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.display_name).toBe('My Fast GPT');
+  });
+
+  test('multi-target alias whose first target pins reasoning.effort drops the alias-wide effort block', () => {
+    // The pinned target counts as unsupported for effort, so the
+    // intersection collapses — effort never makes it onto the listing.
+    const aliases = [aliasFixture({
+      name: 'mixed',
+      targets: [
+        { target_model_id: 'a', rules: { reasoning: { effort: 'low' } } },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } } } }),
+      realModel({ id: 'b', chat: { reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning).toBeUndefined();
+  });
+
+  test('multi-target alias without rules intersects reasoning.effort across targets', () => {
+    const aliases = [aliasFixture({
+      name: 'unfixed',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { reasoning: { effort: { supported: ['low', 'medium', 'high'], default: 'medium' } } } }),
+      realModel({ id: 'b', chat: { reasoning: { effort: { supported: ['medium', 'high'], default: 'medium' } } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning?.effort).toEqual({ supported: ['medium', 'high'], default: 'medium' });
+  });
+
+  test('rules.reasoning.adaptive=true at any target drops adaptive from the announced metadata', () => {
+    const aliases = [aliasFixture({
+      name: 'pinned-adaptive',
+      targets: [
+        { target_model_id: 'a', rules: { reasoning: { adaptive: true } } },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { reasoning: { adaptive: true } } }),
+      realModel({ id: 'b', chat: { reasoning: { adaptive: true } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat?.reasoning).toBeUndefined();
+  });
+
+  test('limits intersection emits min across targets; absent when any target lacks the field', () => {
+    const aliases = [aliasFixture({
+      name: 'multi-limits',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'a', limits: { max_context_window_tokens: 128000, max_output_tokens: 16000 } }),
+      realModel({ id: 'b', limits: { max_context_window_tokens: 200000 } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    // Both targets advertise max_context_window_tokens — emit the min.
+    expect(entry.limits.max_context_window_tokens).toBe(128000);
+    // Only `a` declares max_output_tokens, so it drops out.
+    expect(entry.limits.max_output_tokens).toBeUndefined();
+  });
+
+  test('operator override pins limits.max_output_tokens; chat falls back to computed intersection', () => {
+    const aliases = [aliasFixture({
+      name: 'overridden',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+      announcedMetadata: {
+        limits: { max_output_tokens: 8192 },
+      },
+    })];
+    const realModels = [
+      realModel({ id: 'a', limits: { max_context_window_tokens: 128000 }, chat: { modalities: { input: ['text', 'image'], output: ['text'] } } }),
+      realModel({ id: 'b', limits: { max_context_window_tokens: 200000 }, chat: { modalities: { input: ['text'], output: ['text'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    // The override carries the operator's pinned ceiling verbatim …
+    expect(entry.limits).toEqual({ max_output_tokens: 8192 });
+    // … while chat falls back to the rule-aware intersection.
+    expect(entry.chat?.modalities).toEqual({ input: ['text'], output: ['text'] });
+  });
+
+  test('operator override fully replaces chat when set, regardless of computed', () => {
+    const aliases = [aliasFixture({
+      name: 'chat-override',
+      targets: [{ target_model_id: 'a', rules: {} }],
+      announcedMetadata: {
+        chat: { modalities: { input: ['text'], output: ['text'] } },
+      },
+    })];
+    const realModels = [
+      realModel({ id: 'a', chat: { modalities: { input: ['text', 'image'], output: ['text'] } } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.chat).toEqual({ modalities: { input: ['text'], output: ['text'] } });
+  });
+
+  test('endpoints is the union across available targets — every reachable endpoint surfaces', () => {
+    const aliases = [aliasFixture({
+      name: 'mixed',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const realModels = [
+      // Target a serves the three chat endpoints + /completions.
+      realModel({ id: 'a', endpoints: { chatCompletions: {}, messages: {}, responses: {}, completions: {} } }),
+      // Target b only serves the three chat endpoints.
+      realModel({ id: 'b', endpoints: { chatCompletions: {}, messages: {}, responses: {} } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    // Union: every key surfaces. Resolver narrows to the supporting subset
+    // at request time, so first-available / random stays sound per-endpoint.
+    expect(entry.endpoints).toEqual({
+      chatCompletions: {},
+      messages: {},
+      responses: {},
+      completions: {},
+    });
+  });
+
+  test('endpoints union surfaces both image keys when targets split between generations and edits', () => {
+    const aliases = [aliasFixture({
+      kind: 'image',
+      targets: [
+        { target_model_id: 'gen', rules: {} },
+        { target_model_id: 'edit', rules: {} },
+      ],
+    })];
+    const realModels = [
+      realModel({ id: 'gen', kind: 'image', endpoints: { imagesGenerations: {} } }),
+      realModel({ id: 'edit', kind: 'image', endpoints: { imagesEdits: {} } }),
+    ];
+    const [entry] = synthesizeListedAliases({ aliases, gatewayAddressableModelIds: listed(realModels), callerAddressableModelIds: listed(realModels), narrowTargets: false });
+    expect(entry.endpoints).toEqual({ imagesGenerations: {}, imagesEdits: {} });
+  });
+
+  test('endpoints is an empty list (no entry emitted) when no target is currently available', () => {
+    const aliases = [aliasFixture({
+      name: 'ghost',
+      targets: [{ target_model_id: 'missing', rules: {} }],
+    })];
+    expect(synthesizeListedAliases({ aliases, gatewayAddressableModelIds: [], callerAddressableModelIds: [], narrowTargets: false })).toEqual([]);
+  });
+
+  test('an alias target reachable only via the addressable-but-not-listed surface counts as available', () => {
+    // A Copilot variant id like `claude-opus-4.7-high` collapses to the
+    // canonical public id `claude-opus-4-7` at the resolver layer. The
+    // listing now reads from the same addressable surface, so an alias
+    // that targets the variant id resolves to the canonical model and the
+    // synthesized entry inherits its catalog metadata.
+    const canonical = realModel({
+      id: 'claude-opus-4-7',
+      display_name: 'Claude Opus 4.7',
+      chat: { modalities: { input: ['text', 'image'], output: ['text'] } },
+    });
+    const aliases = [aliasFixture({
+      name: 'fast-claude',
+      targets: [{ target_model_id: 'claude-opus-4.7-high', rules: {} }],
+    })];
+    const addressableModelIds = [
+      ...listed([canonical]),
+      unlisted('claude-opus-4.7-high', canonical),
+    ];
+    const [entry] = synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: addressableModelIds,
+      callerAddressableModelIds: addressableModelIds,
+      narrowTargets: false,
+    });
+    expect(entry.id).toBe('fast-claude');
+    expect(entry.chat?.modalities).toEqual({ input: ['text', 'image'], output: ['text'] });
+    expect(entry.endpoints).toEqual({ chatCompletions: {}, messages: {}, responses: {} });
+  });
+
+  test('metadata is computed gateway-wide — same numbers regardless of caller cap', () => {
+    // The alias has two targets with different windows. Two callers see
+    // the alias: one with full gateway access, one capped to a subset.
+    // Both must read the same `limits.max_context_window_tokens` because
+    // the announced metadata is a stable property of the alias.
+    const aliases = [aliasFixture({
+      name: 'mix',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+      ],
+    })];
+    const a = realModel({ id: 'a', limits: { max_context_window_tokens: 100_000 } });
+    const b = realModel({ id: 'b', limits: { max_context_window_tokens: 200_000 } });
+    const gatewayWide = listed([a, b]);
+    const restricted = listed([b]);
+
+    const [unrestricted] = synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: gatewayWide,
+      callerAddressableModelIds: gatewayWide,
+      narrowTargets: false,
+    });
+    const [scoped] = synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: gatewayWide,
+      callerAddressableModelIds: restricted,
+      narrowTargets: true,
+    });
+
+    // Both callers read the safe-lower-bound min(100k, 200k) = 100k —
+    // even though the scoped caller's resolver would never pick `a`.
+    expect(unrestricted.limits.max_context_window_tokens).toBe(100_000);
+    expect(scoped.limits.max_context_window_tokens).toBe(100_000);
+    // Endpoints union also computed gateway-wide.
+    expect(unrestricted.endpoints).toEqual(scoped.endpoints);
+  });
+
+  test('narrowTargets=true filters `aliasedFrom.targets` to caller-reachable; narrowTargets=false keeps raw config (typos included)', () => {
+    const aliases = [aliasFixture({
+      name: 'mix',
+      targets: [
+        { target_model_id: 'a', rules: {} },
+        { target_model_id: 'b', rules: {} },
+        { target_model_id: 'typo-no-such-model', rules: {} },
+      ],
+    })];
+    const a = realModel({ id: 'a' });
+    const b = realModel({ id: 'b' });
+    const gatewayWide = listed([a, b]);
+    const restricted = listed([b]);
+
+    const [adminView] = synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: gatewayWide,
+      callerAddressableModelIds: gatewayWide,
+      narrowTargets: false,
+    });
+    // Admin (narrowTargets=false) keeps the raw configured list,
+    // including the typo, so the alias-edit dialog can render the full
+    // configuration even when some targets do not currently resolve.
+    expect(adminView.aliasedFrom?.targets.map(t => t.target_model_id)).toEqual(['a', 'b', 'typo-no-such-model']);
+
+    const [scopedView] = synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: gatewayWide,
+      callerAddressableModelIds: restricted,
+      narrowTargets: true,
+    });
+    // Non-admin / data-plane caller (narrowTargets=true) only sees the
+    // targets sitting inside their addressable cap. Out-of-cap target
+    // `a` AND the typo `typo-no-such-model` both drop out — the caller
+    // never learns the operator's full alias configuration.
+    expect(scopedView.aliasedFrom?.targets.map(t => t.target_model_id)).toEqual(['b']);
+  });
+
+  test('alias is omitted when caller cannot reach any of the configured targets', () => {
+    const aliases = [aliasFixture({
+      name: 'mix',
+      targets: [{ target_model_id: 'a', rules: {} }],
+    })];
+    const a = realModel({ id: 'a' });
+    expect(synthesizeListedAliases({
+      aliases,
+      gatewayAddressableModelIds: listed([a]),
+      callerAddressableModelIds: [],  // caller sees nothing
+      narrowTargets: true,
+    })).toEqual([]);
+  });
+});
diff --git a/packages/gateway/src/data-plane/models/gemini.ts b/packages/gateway/src/data-plane/models/gemini.ts
index 93f4b6822..64d565e76 100644
--- a/packages/gateway/src/data-plane/models/gemini.ts
+++ b/packages/gateway/src/data-plane/models/gemini.ts
@@ -1,12 +1,15 @@
 import type { Context } from 'hono';
 
+import { mergeAliasesIntoModels } from './alias-listing.ts';
 import { MODEL_LISTING_FAILURE_MESSAGE } from './shared.ts';
 import { createPerRequestFetcher } from '../../dial/per-request.ts';
 import { effectiveUpstreamIdsFromContext } from '../../middleware/auth.ts';
+import { getRepo } from '../../repo/index.ts';
+import type { ModelAliasesRepo } from '../../repo/types.ts';
 import { backgroundSchedulerFromContext } from '../../runtime/background.ts';
 import { getCurrentColo } from '../../runtime/runtime-info.ts';
 import { geminiStatusForHttpStatus } from '../chat/gemini/errors.ts';
-import { getInternalModels } from '../providers/registry.ts';
+import { enumerateAddressableModelIds, listedRealModels } from '../providers/addressable.ts';
 import type { BackgroundScheduler } from '@floway-dev/platform';
 import type { ModelPricing } from '@floway-dev/protocols/common';
 import { ProviderModelsUnavailableError } from '@floway-dev/provider';
@@ -62,20 +65,50 @@ const geminiModelLoadError = (error: unknown): Response => {
   return geminiError(502, error instanceof Error ? error.message : String(error));
 };
 
+// Real chat models plus chat-kind alias entries; collision and dedupe ride
+// on the shared `mergeAliasesIntoModels` helper so /v1beta/models stays in
+// step with /v1/models and the dashboard's /api/models.
 const loadGeminiModels = async (
   upstreamFilter: readonly string[] | null,
   fetcherForUpstream: (upstreamId: string) => Fetcher,
   scheduler: BackgroundScheduler,
+  aliasRepo: ModelAliasesRepo,
 ): Promise<GeminiModel[]> => {
-  const models = await getInternalModels(upstreamFilter, fetcherForUpstream, scheduler);
-  // Only chat models are representable in the Gemini /models shape.
-  return models.filter(model => model.kind === 'chat').map(toGeminiModel);
+  const [callerAddressable, gatewayAddressable, aliases] = await Promise.all([
+    enumerateAddressableModelIds(upstreamFilter, fetcherForUpstream, scheduler),
+    upstreamFilter === null
+      ? Promise.resolve(null)
+      : enumerateAddressableModelIds(null, fetcherForUpstream, scheduler),
+    aliasRepo.list(),
+  ]);
+  const gatewayAddressableModelIds = gatewayAddressable ?? callerAddressable;
+  const realModels = listedRealModels(callerAddressable);
+  // Gemini surfaces chat-kind models only; filter both the real catalog and
+  // the synthesized alias entries before the merge so the alias collision
+  // step only ever weighs chat-on-chat.
+  const merged = mergeAliasesIntoModels<InternalModel>({
+    realModels: realModels.filter(model => model.kind === 'chat'),
+    gatewayAddressableModelIds: gatewayAddressableModelIds.filter(entry => entry.model.kind === 'chat'),
+    callerAddressableModelIds: callerAddressable.filter(entry => entry.model.kind === 'chat'),
+    aliases: aliases.filter(alias => alias.kind === 'chat'),
+    narrowTargets: true,
+    mapReal: model => model,
+    wrapAlias: entry => ({
+      id: entry.id,
+      display_name: entry.display_name,
+      limits: entry.limits,
+      kind: entry.kind,
+      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),
+      ...(entry.chat !== undefined ? { chat: entry.chat } : {}),
+    }),
+  });
+  return merged.map(toGeminiModel);
 };
 
 export const serveGeminiModels = async (c: Context): Promise<Response> => {
   try {
     const fetcherForUpstream = await createPerRequestFetcher(getCurrentColo(c.req.raw));
-    return Response.json({ models: await loadGeminiModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c)) });
+    return Response.json({ models: await loadGeminiModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c), getRepo().modelAliases) });
   } catch (error) {
     return geminiModelLoadError(error);
   }
@@ -88,7 +121,7 @@ export const serveGeminiModelInfo = async (c: Context): Promise<Response> => {
   const modelId = rawModelId.replace(/^models\//, '');
   try {
     const fetcherForUpstream = await createPerRequestFetcher(getCurrentColo(c.req.raw));
-    const model = (await loadGeminiModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c))).find(candidate => candidate.baseModelId === modelId || candidate.name === `models/${modelId}`);
+    const model = (await loadGeminiModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c), getRepo().modelAliases)).find(candidate => candidate.baseModelId === modelId || candidate.name === `models/${modelId}`);
     if (!model) return geminiError(404, `Model not found: ${modelId}`);
     return Response.json(model);
   } catch (error) {
diff --git a/packages/gateway/src/data-plane/models/load.ts b/packages/gateway/src/data-plane/models/load.ts
index f650e427b..9417028da 100644
--- a/packages/gateway/src/data-plane/models/load.ts
+++ b/packages/gateway/src/data-plane/models/load.ts
@@ -1,9 +1,11 @@
-import { getInternalModels } from '../providers/registry.ts';
+import { mergeAliasesIntoModels } from './alias-listing.ts';
+import type { ModelAliasesRepo } from '../../repo/types.ts';
+import { enumerateAddressableModelIds, listedRealModels } from '../providers/addressable.ts';
 import type { BackgroundScheduler } from '@floway-dev/platform';
 import type { PublicModel, PublicModelsResponse } from '@floway-dev/protocols/common';
-import type { Fetcher, InternalModel } from '@floway-dev/provider';
+import type { Fetcher, ResolvedModel } from '@floway-dev/provider';
 
-export const toPublicModel = (model: InternalModel): PublicModel => {
+export const toPublicModel = (model: ResolvedModel): PublicModel => {
   const info: PublicModel = {
     id: model.id,
     object: 'model',
@@ -11,6 +13,7 @@ export const toPublicModel = (model: InternalModel): PublicModel => {
     display_name: model.display_name ?? model.id,
     limits: { ...model.limits },
     kind: model.kind,
+    endpoints: { ...model.endpoints },
   };
   if (model.owned_by !== undefined) info.owned_by = model.owned_by;
   if (model.created !== undefined) {
@@ -26,8 +29,30 @@ export const loadModels = async (
   upstreamFilter: readonly string[] | null,
   fetcherForUpstream: (upstreamId: string) => Fetcher,
   scheduler: BackgroundScheduler,
+  aliasRepo: ModelAliasesRepo,
 ): Promise<PublicModelsResponse> => {
-  const data = (await getInternalModels(upstreamFilter, fetcherForUpstream, scheduler)).map(toPublicModel);
+  // Data-plane responses always narrow `aliasedFrom.targets` to the
+  // caller's reachable set (and never expose typo'd / removed target
+  // ids), but the alias's metadata is still computed gateway-wide so
+  // every caller sees the same numbers.
+  const [callerAddressable, gatewayAddressable, aliases] = await Promise.all([
+    enumerateAddressableModelIds(upstreamFilter, fetcherForUpstream, scheduler),
+    upstreamFilter === null
+      ? Promise.resolve(null)
+      : enumerateAddressableModelIds(null, fetcherForUpstream, scheduler),
+    aliasRepo.list(),
+  ]);
+  const gatewayAddressableModelIds = gatewayAddressable ?? callerAddressable;
+  const realModels = listedRealModels(callerAddressable);
+  const data = mergeAliasesIntoModels({
+    realModels,
+    gatewayAddressableModelIds,
+    callerAddressableModelIds: callerAddressable,
+    aliases,
+    narrowTargets: true,
+    mapReal: toPublicModel,
+    wrapAlias: entry => entry,
+  });
   return {
     object: 'list',
     has_more: false,
diff --git a/packages/gateway/src/data-plane/models/load_test.ts b/packages/gateway/src/data-plane/models/load_test.ts
index 20560891f..db96d7ac9 100644
--- a/packages/gateway/src/data-plane/models/load_test.ts
+++ b/packages/gateway/src/data-plane/models/load_test.ts
@@ -1,12 +1,14 @@
 import { describe, expect, test } from 'vitest';
 
 import { toPublicModel } from './load.ts';
-import type { InternalModel } from '@floway-dev/provider';
+import type { ResolvedModel } from '@floway-dev/provider';
 
-const base: InternalModel = {
+const base: ResolvedModel = {
   id: 'm1',
   kind: 'chat',
   limits: { max_context_window_tokens: 100000 },
+  endpoints: { chatCompletions: {}, messages: {}, responses: {} },
+  providers: [],
 };
 
 describe('toPublicModel', () => {
@@ -21,4 +23,13 @@ describe('toPublicModel', () => {
     };
     expect(toPublicModel({ ...base, chat }).chat).toEqual(chat);
   });
+
+  test('stamps the upstream endpoint map onto the wire entry verbatim', () => {
+    expect(toPublicModel(base).endpoints).toEqual({ chatCompletions: {}, messages: {}, responses: {} });
+  });
 });
+
+// The alias merge step inside `loadModels` (alias entries follow real
+// entries, alias names winning id collisions) is exercised through the
+// integration suite in `serve_test.ts` so the assertion observes the same
+// `/v1/models` payload a real client would see.
diff --git a/packages/gateway/src/data-plane/models/serve.ts b/packages/gateway/src/data-plane/models/serve.ts
index 9b8b510f9..a66755b6e 100644
--- a/packages/gateway/src/data-plane/models/serve.ts
+++ b/packages/gateway/src/data-plane/models/serve.ts
@@ -7,6 +7,7 @@ import { loadModels } from './load.ts';
 import { MODEL_LISTING_FAILURE_MESSAGE } from './shared.ts';
 import { createPerRequestFetcher } from '../../dial/per-request.ts';
 import { effectiveUpstreamIdsFromContext } from '../../middleware/auth.ts';
+import { getRepo } from '../../repo/index.ts';
 import { backgroundSchedulerFromContext } from '../../runtime/background.ts';
 import { getCurrentColo } from '../../runtime/runtime-info.ts';
 import { ProviderModelsUnavailableError } from '@floway-dev/provider';
@@ -14,7 +15,7 @@ import { ProviderModelsUnavailableError } from '@floway-dev/provider';
 export const models = async (c: Context) => {
   try {
     const fetcherForUpstream = await createPerRequestFetcher(getCurrentColo(c.req.raw));
-    return Response.json(await loadModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c)));
+    return Response.json(await loadModels(effectiveUpstreamIdsFromContext(c), fetcherForUpstream, backgroundSchedulerFromContext(c), getRepo().modelAliases));
   } catch (e) {
     // Upstream HTTP/parse failures squash to a generic message so we do not
     // leak upstream identity. Other registry-thrown errors (e.g. the "no
diff --git a/packages/gateway/src/data-plane/models/serve_test.ts b/packages/gateway/src/data-plane/models/serve_test.ts
index 1408f10a6..ac05ca29f 100644
--- a/packages/gateway/src/data-plane/models/serve_test.ts
+++ b/packages/gateway/src/data-plane/models/serve_test.ts
@@ -119,7 +119,6 @@ test('/v1/models returns merged model list from Copilot and custom upstreams', a
         assertEquals(model.providerKind, undefined);
         assertEquals(model.providers, undefined);
         assertEquals(model.providerData, undefined);
-        assertEquals(model.endpoints, undefined);
         assertEquals(model.upstream, undefined);
         assertEquals(model.upstreamModel, undefined);
         // Copilot-only raw fields never reach the public DTO.
@@ -250,6 +249,7 @@ test('/models returns the same superset payload as /v1/models', async () => {
             display_name: 'Claude Opus 4.7 XHigh',
             limits: {},
             kind: 'chat',
+            endpoints: { messages: {} },
             cost: {
               input: 5,
               output: 25,
@@ -272,6 +272,7 @@ test('/models returns the same superset payload as /v1/models', async () => {
             display_name: 'embedding-only',
             limits: {},
             kind: 'embedding',
+            endpoints: { embeddings: {} },
           },
           {
             id: 'gpt-image-2',
@@ -280,6 +281,7 @@ test('/models returns the same superset payload as /v1/models', async () => {
             display_name: 'gpt-image-2',
             limits: {},
             kind: 'image',
+            endpoints: { imagesGenerations: {}, imagesEdits: {} },
           },
         ],
       });
@@ -586,3 +588,98 @@ test('/v1/models returns the last real error when every account model load fails
     },
   );
 });
+
+test('/v1/models appends visible aliases with their aliasedFrom block and folds alias-id collisions onto the alias entry', async () => {
+  const { repo, apiKey } = await setupAppTest();
+  await repo.modelAliases.deleteAll();
+  await repo.upstreams.save(buildCustomUpstreamRecord({
+    id: 'up_oai',
+    name: 'Test OpenAI',
+    sortOrder: 100,
+    config: {
+      baseUrl: 'https://oai.example.com',
+      authStyle: 'bearer',
+      apiKey: 'sk-test',
+      endpoints: { chatCompletions: {} },
+    },
+  }));
+  // Two aliases: one shadows a real id (`gpt-4o`) so the alias entry must
+  // replace the catalog entry; one points at a real id under a brand-new
+  // name (`gpt-fast`).
+  await repo.modelAliases.insert({
+    name: 'gpt-4o',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: null,
+    visibleInModelsList: true,
+    targets: [{ target_model_id: 'gpt-4o', rules: { reasoning: { effort: 'low' } } }],
+    announcedMetadata: null,
+    sortOrder: 1,
+    createdAt: '2026-06-26T00:00:00.000Z',
+    updatedAt: '2026-06-26T00:00:00.000Z',
+  });
+  await repo.modelAliases.insert({
+    name: 'gpt-fast',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: 'Operator Fast',
+    visibleInModelsList: true,
+    targets: [{ target_model_id: 'gpt-4o-mini', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 0,
+    createdAt: '2026-06-26T00:00:00.000Z',
+    updatedAt: '2026-06-26T00:00:00.000Z',
+  });
+  await repo.modelAliases.insert({
+    name: 'hidden-alias',
+    kind: 'chat',
+    selection: 'first-available',
+    displayName: null,
+    visibleInModelsList: false,
+    targets: [{ target_model_id: 'gpt-4o', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 2,
+    createdAt: '2026-06-26T00:00:00.000Z',
+    updatedAt: '2026-06-26T00:00:00.000Z',
+  });
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+      if (url.pathname === '/copilot_internal/v2/token') {
+        return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+      }
+      if (url.pathname === '/models' && url.hostname === 'api.individual.githubcopilot.com') {
+        return jsonResponse(copilotModels([]));
+      }
+      if (url.pathname === '/v1/models' && url.hostname === 'oai.example.com') {
+        return jsonResponse({ object: 'list', data: [{ id: 'gpt-4o' }, { id: 'gpt-4o-mini' }] });
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const response = await requestApp('/v1/models', { headers: { 'x-api-key': apiKey.key } });
+      assertEquals(response.status, 200);
+      const body = (await response.json()) as { data: Array<{ id: string; display_name: string; aliasedFrom?: { name: string; selection: string } }> };
+      const ids = body.data.map(model => model.id);
+
+      // Real `gpt-4o` is replaced by the alias of the same name; the alias
+      // entry sits where the catalog ordering placed it. `gpt-4o-mini`
+      // (still a real id) stays first, and the two visible aliases land
+      // after the real-only entries.
+      assertEquals(ids.includes('gpt-4o-mini'), true);
+      assertEquals(ids.filter(id => id === 'gpt-4o').length, 1);
+      assertEquals(ids.includes('hidden-alias'), false);
+
+      const collided = body.data.find(model => model.id === 'gpt-4o')!;
+      assertEquals(collided.aliasedFrom?.name, 'gpt-4o');
+      assertEquals(collided.aliasedFrom?.selection, 'first-available');
+      assertEquals(collided.display_name, 'gpt-4o (low effort)');
+
+      const fast = body.data.find(model => model.id === 'gpt-fast')!;
+      assertEquals(fast.aliasedFrom?.name, 'gpt-fast');
+      assertEquals(fast.display_name, 'Operator Fast');
+    },
+  );
+});
diff --git a/packages/gateway/src/data-plane/providers/addressable.ts b/packages/gateway/src/data-plane/providers/addressable.ts
new file mode 100644
index 000000000..46a988512
--- /dev/null
+++ b/packages/gateway/src/data-plane/providers/addressable.ts
@@ -0,0 +1,140 @@
+// One enumeration per (effective upstream cap) of every inbound model id the
+// gateway accepts — the union of the listed catalog surface and the
+// addressable-but-not-listed surface contributed by `modelPrefix.addressable`
+// alternates and by each provider's `resolveRequestedModelId` redirect map.
+// Listing-side availability checks (alias-listing, codex catalog) must see
+// the same set the request-time resolver routes through
+// (`enumerateModelInterpretations` + `resolveRequestedModelId`); recomputing
+// it once here gives every consumer one consistent answer.
+//
+// Each entry carries the `ResolvedModel` the addressable id will route to,
+// so consumers (alias intersection, codex catalog, control-plane DTO) read
+// `limits` / `chat` / `endpoints` directly off the entry without a second
+// registry round trip.
+
+import { fetchUpstreamModelsCached } from './models-cache.ts';
+import { compareModelIds, getModelsFromProviders, listModelProviders } from './registry.ts';
+import type { BackgroundScheduler } from '@floway-dev/platform';
+import type { Fetcher, ResolvedModel } from '@floway-dev/provider';
+
+export interface AddressableIdEntry {
+  // The inbound model id the data plane will accept verbatim.
+  readonly id: string;
+  // Absent on default-listed entries (the public-id surface the listing
+  // already emits); present-and-`true` on entries that are only reachable
+  // through `modelPrefix.addressable` alternates or provider-side redirects.
+  // The negative carry pairs with the `PublicModel.unlisted?: true` wire
+  // shape so a listed entry's wire bytes stay byte-identical.
+  readonly unlisted: true | undefined;
+  // Real catalog row this id routes to. For multi-provider models this is
+  // the same `ResolvedModel` instance `getModels` returns (one row per
+  // public-listed id, with the union-merged endpoints + `providers[]`
+  // already applied).
+  readonly model: ResolvedModel;
+}
+
+// Project the listed (real-catalog) `ResolvedModel`s out of an addressable
+// surface — every listing caller wants this same slice to feed
+// `mergeAliasesIntoModels`'s `realModels` arg.
+export const listedRealModels = (entries: readonly AddressableIdEntry[]): readonly ResolvedModel[] =>
+  entries.filter(entry => entry.unlisted === undefined).map(entry => entry.model);
+
+// Enumerate every inbound id the data plane accepts under `upstreamFilter`,
+// tagged with whether the id participates in the default `/v1/models`
+// listing. Fans out per upstream the same way `collectProviderModels` does,
+// re-uses the SWR cache so the catalog refresh round-trip is shared with
+// `getModels`.
+export const enumerateAddressableModelIds = async (
+  upstreamFilter: readonly string[] | null,
+  fetcherForUpstream: (upstreamId: string) => Fetcher,
+  scheduler: BackgroundScheduler,
+): Promise<readonly AddressableIdEntry[]> => {
+  // Resolve providers once and thread them into the catalog assembly so
+  // the upstreams.list() round-trip and provider-instantiation cost is
+  // paid once per call. `getModelsFromProviders` throws the actionable
+  // "no upstream provider configured" message when the provider list is
+  // empty; surface it the same way here so /v1/models keeps its 502 +
+  // hint behavior on a brand-new gateway.
+  const providers = await listModelProviders(upstreamFilter);
+  const realModels = await getModelsFromProviders(providers, fetcherForUpstream, scheduler);
+  const byId = new Map(realModels.map(model => [model.id, model] as const));
+
+  const entries: AddressableIdEntry[] = [];
+  const seen = new Set<string>();
+  const push = (entry: AddressableIdEntry): void => {
+    if (seen.has(entry.id)) return;
+    seen.add(entry.id);
+    entries.push(entry);
+  };
+
+  for (const model of realModels) {
+    push({ id: model.id, unlisted: undefined, model });
+  }
+
+  // Per-upstream walk: (a) prefix-addressable alternates the listed surface
+  // chose not to publish, then (b) the provider's redirect enumeration. The
+  // catalog round-trip is the same SWR cache the listed surface just
+  // consumed, so this loop never pays a second upstream hit.
+  //
+  // A rejected per-upstream catalog refresh collapses to no addressable-only
+  // contribution from THAT upstream — its listed rows already came (or were
+  // dropped) through `getModels`. Mirrors the `Promise.allSettled` tolerance
+  // there so a transiently-down upstream cannot tank /v1/models on a
+  // cold-start gateway.
+  const perUpstream = await Promise.allSettled(providers.map(async provider => {
+    const cfg = provider.modelPrefix;
+    const addressableOnly = cfg !== null ? cfg.addressable.filter(form => !cfg.listed.includes(form)) : [];
+    if (addressableOnly.length === 0 && provider.enumerateAddressableRedirects === undefined) {
+      return [] as AddressableIdEntry[];
+    }
+
+    const upstreamModels = await fetchUpstreamModelsCached(provider, { scheduler, fetcher: fetcherForUpstream(provider.upstream) });
+    const disabled = new Set(provider.disabledPublicModelIds);
+    const out: AddressableIdEntry[] = [];
+
+    if (cfg !== null && addressableOnly.length > 0) {
+      // The canonical listed form for this upstream — the row the listing
+      // surface emitted, and the row a redirect-only addressable id should
+      // resolve back into so consumers find one consistent `ResolvedModel`.
+      const canonicalForm = cfg.listed.includes('prefixed') ? 'prefixed' : 'unprefixed';
+
+      for (const upstreamModel of upstreamModels) {
+        if (!upstreamModel.id || disabled.has(upstreamModel.id)) continue;
+        const canonicalPublicId = canonicalForm === 'prefixed'
+          ? `${cfg.prefix}${upstreamModel.id}`
+          : upstreamModel.id;
+        const canonical = byId.get(canonicalPublicId);
+        if (canonical === undefined) continue;
+        for (const form of addressableOnly) {
+          const id = form === 'prefixed' ? `${cfg.prefix}${upstreamModel.id}` : upstreamModel.id;
+          out.push({ id, unlisted: true, model: canonical });
+        }
+      }
+    }
+
+    const redirects = provider.enumerateAddressableRedirects?.({ upstreamModels }) ?? [];
+    for (const redirect of redirects) {
+      const target = byId.get(redirect.resolvesTo);
+      if (target === undefined) continue;
+      out.push({ id: redirect.addressable, unlisted: true, model: target });
+    }
+    return out;
+  }));
+
+  for (const result of perUpstream) {
+    if (result.status === 'rejected') {
+      // Cancellation must propagate even from this tolerant fanout — the
+      // per-request abort signal cannot be masked by an upstream's slow
+      // rejection. Other failures (catalog 5xx, parse, transport) collapse
+      // to no addressable-only contribution from that upstream per the
+      // contract above.
+      if (result.reason instanceof Error && result.reason.name === 'AbortError') throw result.reason;
+      continue;
+    }
+    for (const entry of result.value) push(entry);
+  }
+
+  // Stable id ordering matches the listed surface so consumers can rely on
+  // a single comparator across both halves.
+  return entries.sort((a, b) => compareModelIds(a.id, b.id));
+};
diff --git a/packages/gateway/src/data-plane/providers/addressable_test.ts b/packages/gateway/src/data-plane/providers/addressable_test.ts
new file mode 100644
index 000000000..2aace3eee
--- /dev/null
+++ b/packages/gateway/src/data-plane/providers/addressable_test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'vitest';
+
+import { enumerateAddressableModelIds } from './addressable.ts';
+import { clearInFlightForTesting } from './models-cache.ts';
+import { buildCopilotUpstreamRecord, buildCustomUpstreamRecord, copilotModels, setupAppTest } from '../../test-helpers.ts';
+import { directFetcher } from '@floway-dev/provider';
+import { jsonResponse, withMockedFetch } from '@floway-dev/test-utils';
+
+const noBackground = (promise: Promise<unknown>): void => {
+  promise.catch(err => console.error('[background]', err));
+};
+
+describe('enumerateAddressableModelIds', () => {
+  test('returns the listed catalog as listed entries when no provider contributes addressable-only forms', async () => {
+    const { repo } = await setupAppTest();
+    await repo.upstreams.deleteAll();
+    await repo.upstreams.save(buildCustomUpstreamRecord());
+    clearInFlightForTesting();
+
+    await withMockedFetch(
+      request => {
+        const url = new URL(request.url);
+        if (url.hostname === 'custom.example.com' && url.pathname === '/v1/models') {
+          return jsonResponse({ object: 'list', data: [{ id: 'shared-model', supported_endpoints: ['/chat/completions'] }] });
+        }
+        throw new Error(`Unhandled fetch ${request.url}`);
+      },
+      async () => {
+        const surface = await enumerateAddressableModelIds(null, () => directFetcher, noBackground);
+        expect(surface.map(e => ({ id: e.id, unlisted: e.unlisted }))).toEqual([
+          { id: 'shared-model', unlisted: undefined },
+        ]);
+      },
+    );
+  });
+
+  test('emits the addressable-only prefix form whenever modelPrefix.addressable ⊋ modelPrefix.listed', async () => {
+    const { repo } = await setupAppTest();
+    await repo.upstreams.deleteAll();
+    await repo.upstreams.save(buildCustomUpstreamRecord({
+      id: 'up_custom_prefixed',
+      // Listed only as `cust/gpt-5.4`, but the bare `gpt-5.4` form remains
+      // addressable for clients that still talk to the upstream by its raw
+      // public id.
+      modelPrefix: { prefix: 'cust/', addressable: ['unprefixed', 'prefixed'], listed: ['prefixed'] },
+    }));
+    clearInFlightForTesting();
+
+    await withMockedFetch(
+      request => {
+        const url = new URL(request.url);
+        if (url.hostname === 'custom.example.com' && url.pathname === '/v1/models') {
+          return jsonResponse({ object: 'list', data: [{ id: 'gpt-5.4', supported_endpoints: ['/chat/completions'] }] });
+        }
+        throw new Error(`Unhandled fetch ${request.url}`);
+      },
+      async () => {
+        const surface = await enumerateAddressableModelIds(null, () => directFetcher, noBackground);
+        const byId = new Map(surface.map(e => [e.id, e]));
+        expect(byId.get('cust/gpt-5.4')?.unlisted).toBeUndefined();
+        expect(byId.get('gpt-5.4')?.unlisted).toBe(true);
+        // The addressable-only entry still resolves to the same `ResolvedModel`
+        // as the canonical listed id, so consumers find one consistent row.
+        expect(byId.get('gpt-5.4')?.model).toBe(byId.get('cust/gpt-5.4')?.model);
+      },
+    );
+  });
+
+  test('Copilot variant ids surface as addressable-but-not-listed entries pointing at the canonical public model', async () => {
+    const { repo, githubAccount } = await setupAppTest();
+    await repo.upstreams.deleteAll();
+    await repo.upstreams.save(buildCopilotUpstreamRecord(githubAccount));
+    clearInFlightForTesting();
+
+    await withMockedFetch(
+      request => {
+        const url = new URL(request.url);
+        if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+        if (url.pathname === '/copilot_internal/v2/token') {
+          return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+        }
+        if (url.hostname === 'api.individual.githubcopilot.com' && url.pathname === '/models') {
+          return jsonResponse(copilotModels([
+            { id: 'claude-opus-4.7', supported_endpoints: ['/v1/messages'] },
+            { id: 'claude-opus-4.7-high', supported_endpoints: ['/v1/messages'] },
+          ]));
+        }
+        throw new Error(`Unhandled fetch ${request.url}`);
+      },
+      async () => {
+        const surface = await enumerateAddressableModelIds(null, () => directFetcher, noBackground);
+        const byId = new Map(surface.map(e => [e.id, e]));
+        // The canonical merged id is the listed entry.
+        expect(byId.get('claude-opus-4-7')?.unlisted).toBeUndefined();
+        // Both raw variants are addressable-but-not-listed, redirecting to
+        // the canonical model.
+        expect(byId.get('claude-opus-4.7')?.unlisted).toBe(true);
+        expect(byId.get('claude-opus-4.7-high')?.unlisted).toBe(true);
+        expect(byId.get('claude-opus-4.7')?.model).toBe(byId.get('claude-opus-4-7')?.model);
+      },
+    );
+  });
+
+  test('throws "no upstream configured" when the upstream cap is empty — surfacing the same hint /v1/models has always raised', async () => {
+    const { repo } = await setupAppTest();
+    await repo.upstreams.deleteAll();
+    clearInFlightForTesting();
+
+    await expect(enumerateAddressableModelIds(null, () => directFetcher, noBackground))
+      .rejects.toThrow('No upstream provider configured');
+  });
+});
diff --git a/packages/gateway/src/data-plane/providers/endpoint-union.ts b/packages/gateway/src/data-plane/providers/endpoint-union.ts
new file mode 100644
index 000000000..5b968deed
--- /dev/null
+++ b/packages/gateway/src/data-plane/providers/endpoint-union.ts
@@ -0,0 +1,21 @@
+import type { ModelEndpointKey, ModelEndpoints } from '@floway-dev/protocols/common';
+
+// Union N endpoint maps: a key appears in the result whenever ANY input
+// declares it, and its sub-capability flags are OR-ed so a sub-cap
+// advertised by any contributor survives. Used at two layers — the catalog
+// merge collapses multiple upstream surfaces of the same public id into one
+// row, and the alias listing advertises the union across an alias's
+// available targets. The request-time pool narrows to whatever subset
+// actually serves the inbound endpoint, so every endpoint surfaced through
+// the union remains reachable.
+export const unionEndpoints = (endpointsList: readonly ModelEndpoints[]): ModelEndpoints => {
+  const result: ModelEndpoints = {};
+  for (const endpoints of endpointsList) {
+    for (const key of Object.keys(endpoints) as ModelEndpointKey[]) {
+      const incoming = endpoints[key];
+      if (incoming === undefined) continue;
+      result[key] = { ...result[key], ...incoming };
+    }
+  }
+  return result;
+};
diff --git a/packages/gateway/src/data-plane/providers/registry.ts b/packages/gateway/src/data-plane/providers/registry.ts
index 79a4f1c5a..2261059de 100644
--- a/packages/gateway/src/data-plane/providers/registry.ts
+++ b/packages/gateway/src/data-plane/providers/registry.ts
@@ -1,8 +1,11 @@
+import { unionEndpoints } from './endpoint-union.ts';
 import { fetchUpstreamModelsCached } from './models-cache.ts';
+import { createPerRequestFetcher } from '../../dial/per-request.ts';
 import { getRepo } from '../../repo/index.ts';
+import { type AliasResolution, resolveAlias } from '../model-aliases/resolve.ts';
 import type { BackgroundScheduler } from '@floway-dev/platform';
-import { type ModelEndpointKey, type ModelEndpoints, kindForEndpoints } from '@floway-dev/protocols/common';
-import type { InternalModel, ModelProviderInstance, ProviderModelRecord, ResolvedModel, Fetcher, UpstreamModel, UpstreamProviderKind, UpstreamRecord } from '@floway-dev/provider';
+import { type ModelEndpoints, kindForEndpoints } from '@floway-dev/protocols/common';
+import type { ModelProviderInstance, ProviderModelRecord, ResolvedModel, Fetcher, UpstreamModel, UpstreamProviderKind, UpstreamRecord } from '@floway-dev/provider';
 import { createAzureProvider } from '@floway-dev/provider-azure';
 import { createClaudeCodeProvider } from '@floway-dev/provider-claude-code';
 import { createCodexProvider } from '@floway-dev/provider-codex';
@@ -37,10 +40,9 @@ export const createProviderInstance = (record: UpstreamRecord): ModelProviderIns
   providerFactories[record.provider](record);
 
 // The upstream scope is a required argument across the catalog-assembly chain
-// (this, getModels, getInternalModels) so a caller can never omit it and
-// silently receive the full, unscoped catalog — a missing scope is a compile
-// error, not a runtime leak. Pass `null` to deliberately request every enabled
-// upstream.
+// (this, getModels) so a caller can never omit it and silently receive the
+// full, unscoped catalog — a missing scope is a compile error, not a runtime
+// leak. Pass `null` to deliberately request every enabled upstream.
 export const listModelProviders = async (
   upstreamFilter: readonly string[] | null,
 ): Promise<ModelProviderInstance[]> => {
@@ -79,18 +81,6 @@ export const listModelProviders = async (
   return providers;
 };
 
-// Merge two capability maps: a key present in either side is present in the
-// result, and its sub-capability flags are OR-ed so a sub-cap advertised by
-// either provider survives.
-const unionEndpoints = (a: ModelEndpoints, b: ModelEndpoints): ModelEndpoints => {
-  const result: ModelEndpoints = { ...a };
-  for (const key of Object.keys(b) as ModelEndpointKey[]) {
-    const merged = { ...result[key], ...b[key] };
-    (result as Record<ModelEndpointKey, object>)[key] = merged;
-  }
-  return result;
-};
-
 const resolvedFromUpstreamModel = (upstreamModel: UpstreamModel, record: ProviderModelRecord): ResolvedModel => {
   const { providerData: _providerData, endpoints, ...internal } = upstreamModel;
   return {
@@ -126,7 +116,7 @@ const mergeIntoCatalog = (
     byId.set(publicId, resolvedFromUpstreamModel(surfacedModel, record));
     return;
   }
-  const endpoints = unionEndpoints(existing.endpoints, surfacedModel.endpoints);
+  const endpoints = unionEndpoints([existing.endpoints, surfacedModel.endpoints]);
   byId.set(publicId, {
     ...existing,
     endpoints,
@@ -243,14 +233,16 @@ export const compareModelIds = (a: string, b: string): number => {
     || cmp(a, b, -1);
 };
 
-// `fetcherForUpstream` routes each upstream's catalog fetch through its
-// per-upstream proxy chain.
-export const getModels = async (
-  upstreamFilter: readonly string[] | null,
+// Catalog assembly against an already-resolved provider list. Callers that
+// already paid the `listModelProviders` round-trip — `enumerateAddressableModelIds`
+// fans the same list twice, once into the catalog walk and once into the
+// addressable-only loop — pass providers through to avoid the duplicate
+// upstreams.list() DB query.
+export const getModelsFromProviders = async (
+  providers: readonly ModelProviderInstance[],
   fetcherForUpstream: (upstreamId: string) => Fetcher,
   scheduler: BackgroundScheduler,
 ): Promise<ResolvedModel[]> => {
-  const providers = await listModelProviders(upstreamFilter);
   if (providers.length === 0) {
     throw new Error(NO_UPSTREAM_CONFIGURED_MESSAGE);
   }
@@ -262,21 +254,40 @@ export const getModels = async (
   return [];
 };
 
-export const getInternalModels = async (
+// `fetcherForUpstream` routes each upstream's catalog fetch through its
+// per-upstream proxy chain.
+export const getModels = async (
   upstreamFilter: readonly string[] | null,
   fetcherForUpstream: (upstreamId: string) => Fetcher,
   scheduler: BackgroundScheduler,
-): Promise<InternalModel[]> =>
-  (await getModels(upstreamFilter, fetcherForUpstream, scheduler)).map(({ providers: _providers, endpoints: _endpoints, ...model }) => model);
-
-interface ModelResolution {
-  matches: readonly ProviderModelResolution[];
+): Promise<ResolvedModel[]> =>
+  await getModelsFromProviders(await listModelProviders(upstreamFilter), fetcherForUpstream, scheduler);
+
+interface ResolveCandidatesResult<TTarget> {
+  readonly candidates: ReadonlyArray<{
+    readonly provider: ModelProviderInstance;
+    readonly binding: ProviderModelRecord;
+    readonly targetApi: TTarget;
+    readonly fetcher: Fetcher;
+  }>;
+  // True when at least one interpretation resolved against an upstream
+  // catalog — independent of whether `pickTarget` accepted any of them.
+  // Lets a caller distinguish "model is unknown to every configured
+  // upstream" (sawModel=false) from "model exists but no binding serves
+  // this endpoint" (sawModel=true, candidates=[]).
+  readonly sawModel: boolean;
   // Upstream names whose catalog fetch rejected during this resolution.
   // Threaded out so the caller's failure renderer can mention them
   // parenthetically — same data the dashboard's `modelsCache.lastError`
   // surfaces, but inlined into the per-request 404/400 so a client sees
   // why their model might be temporarily missing.
-  failedUpstreams: readonly string[];
+  readonly failedUpstreams: readonly string[];
+  // Set when the inbound id resolved through the alias layer. Callers
+  // stage the `x-floway-alias` response header from this and ignore it
+  // otherwise. `AliasNoTargetAvailableError` is thrown out of
+  // `resolveModelCandidates` itself when the alias exists but has no
+  // routable target, and is caught at each protocol's serve seam.
+  readonly aliasResolution: AliasResolution | null;
 }
 
 export interface ProviderModelResolution {
@@ -317,10 +328,11 @@ export const enumerateModelInterpretations = (
 
 // Fan out per-interpretation against the SWR cache and collect the resolved
 // matches plus a deduped list of upstreams whose catalog fetch rejected.
-// Shared by `resolveModelForRequest` and `enumerateProviderCandidates`; the
-// per-caller divergence (passthrough vs LLM-candidate shape) happens after
-// this returns. Cancellation (`AbortError`) propagates so the per-request
-// abort signal cannot be masked by a slow upstream's rejection.
+// `resolveModelCandidates` consumes this directly; the per-caller divergence
+// (chat-shape `ChatTargetApi` vs passthrough-shape `ModelEndpointKey`) is
+// handled at the `pickTarget` boundary. Cancellation (`AbortError`)
+// propagates so the per-request abort signal cannot be masked by a slow
+// upstream's rejection.
 export const collectInterpretationOutcomes = async (
   interpretations: readonly ModelInterpretation[],
   fetcherForUpstream: (upstreamId: string) => Fetcher,
@@ -358,20 +370,68 @@ export const collectInterpretationOutcomes = async (
   return { resolutions, failedUpstreams };
 };
 
-export const resolveModelForRequest = async (
-  modelId: string,
-  upstreamFilter: readonly string[] | null,
-  fetcherForUpstream: (upstreamId: string) => Fetcher,
-  scheduler: BackgroundScheduler,
-): Promise<ModelResolution> => {
-  const providers = await listModelProviders(upstreamFilter);
+// One resolver wrapper above the shared `resolveAlias` + interpretation +
+// outcome-collection pipeline, generic on the caller's target descriptor.
+// Chat surfaces pass a `pickTarget` returning `ChatTargetApi | null`;
+// passthrough surfaces (embeddings, image generation, /v1/completions) pass
+// one returning `ModelEndpointKey | null`. The endpoint-narrowing predicate
+// the alias resolver needs piggybacks on `pickTarget` — a target whose
+// binding does not serve any acceptable surface is dropped from the alias's
+// first-available / random pool so selection can never pick a binding the
+// downstream serve cannot dispatch on.
+//
+// See resolve.ts for the alias-resolves-once-above-prefix-routing contract.
+// `AliasNoTargetAvailableError` is the alias-only failure mode and surfaces
+// out of this function for the caller to render as a 404.
+export const resolveModelCandidates = async <TTarget>(args: {
+  readonly modelName: string;
+  // null = unrestricted; empty list = no providers visible.
+  readonly upstreamIds: readonly string[] | null;
+  readonly scheduler: BackgroundScheduler;
+  // Current colo for this request — see GatewayCtx.currentColo. Threaded
+  // into the per-request fetcher so colo-scoped fallback entries can be
+  // honoured at dial time.
+  readonly currentColo: string;
+  readonly pickTarget: (endpoints: ModelEndpoints) => TTarget | null;
+}): Promise<ResolveCandidatesResult<TTarget>> => {
+  const { modelName, upstreamIds, scheduler, currentColo, pickTarget } = args;
+  const fetcherForUpstream = await createPerRequestFetcher(currentColo);
+  const providers = await listModelProviders(upstreamIds);
   if (providers.length === 0) {
     throw new Error(NO_UPSTREAM_CONFIGURED_MESSAGE);
   }
 
-  const interpretations = enumerateModelInterpretations(modelId, providers);
+  const aliasResolution = await resolveAlias({
+    modelName,
+    providers,
+    fetcherForUpstream,
+    scheduler,
+    endpointAccepts: endpoints => pickTarget(endpoints) !== null,
+    repo: getRepo().modelAliases,
+  });
+  const effectiveModelId = aliasResolution?.targetModelId ?? modelName;
+
+  const interpretations = enumerateModelInterpretations(effectiveModelId, providers);
   const { resolutions, failedUpstreams } = await collectInterpretationOutcomes(interpretations, fetcherForUpstream, scheduler);
-  return { matches: resolutions.map(r => r.resolved), failedUpstreams };
+
+  const candidates: Array<{
+    provider: ModelProviderInstance;
+    binding: ProviderModelRecord;
+    targetApi: TTarget;
+    fetcher: Fetcher;
+  }> = [];
+  for (const { provider, resolved } of resolutions) {
+    const targetApi = pickTarget(resolved.binding.upstreamModel.endpoints);
+    if (targetApi === null) continue;
+    candidates.push({ provider, binding: resolved.binding, targetApi, fetcher: fetcherForUpstream(provider.upstream) });
+  }
+
+  return {
+    candidates,
+    sawModel: resolutions.length > 0,
+    failedUpstreams,
+    aliasResolution,
+  };
 };
 
 export const resolveModelForProvider = async (
diff --git a/packages/gateway/src/data-plane/providers/registry_test.ts b/packages/gateway/src/data-plane/providers/registry_test.ts
index c330abfee..7926668f2 100644
--- a/packages/gateway/src/data-plane/providers/registry_test.ts
+++ b/packages/gateway/src/data-plane/providers/registry_test.ts
@@ -1,14 +1,31 @@
 import { describe, expect, test } from 'vitest';
 
 import { clearInFlightForTesting } from './models-cache.ts';
-import { compareModelIds, enumerateModelInterpretations, getInternalModels, listModelProviders, resolveModelForProvider, resolveModelForRequest } from './registry.ts';
+import { compareModelIds, enumerateModelInterpretations, getModels, listModelProviders, resolveModelCandidates, resolveModelForProvider } from './registry.ts';
 import { buildCopilotUpstreamRecord, buildCustomUpstreamRecord, copilotModels, setupAppTest } from '../../test-helpers.ts';
-import { directFetcher, type ModelProviderInstance } from '@floway-dev/provider';
+import type { BackgroundScheduler } from '@floway-dev/platform';
+import { directFetcher, type Fetcher, type InternalModel, type ModelProviderInstance } from '@floway-dev/provider';
 import { createCopilotProvider } from '@floway-dev/provider-copilot';
 import { assertEquals, jsonResponse, stubProvider, withMockedFetch } from '@floway-dev/test-utils';
 
+// Test-local projection that strips execution-layer fields, leaving the
+// public-catalog shape the fixtures assert against.
+const getInternalModels = async (
+  upstreamFilter: readonly string[] | null,
+  fetcherForUpstream: (upstreamId: string) => Fetcher,
+  scheduler: BackgroundScheduler,
+): Promise<InternalModel[]> =>
+  (await getModels(upstreamFilter, fetcherForUpstream, scheduler)).map(({ providers: _providers, endpoints: _endpoints, ...model }) => model);
+
 const sortedIds = (ids: readonly string[]): string[] => [...ids].sort(compareModelIds);
 
+// `resolveModelCandidates` requires a target descriptor; tests that just want
+// to verify routing wiring (not endpoint filtering) accept any binding by
+// returning a fixed sentinel string. Every test fixture below declares at
+// least one endpoint on its bindings, so the pick is never asked to reason
+// about an empty `endpoints` map.
+const acceptAnyBinding = () => 'any' as const;
+
 // Drains the background revalidate promise so its rejection surfaces in the
 // test runner instead of being swallowed.
 const testScheduler = (promise: Promise<unknown>): void => {
@@ -189,16 +206,22 @@ test('getInternalModels returns the catalog projection without execution binding
       assertEquals(Object.hasOwn(model!, 'providers'), false);
       assertEquals(Object.hasOwn(model!, 'providerData'), false);
 
-      const resolved = await resolveModelForRequest('shared-model', null, () => directFetcher, testScheduler);
-      assertEquals(resolved.matches.map(m => m.binding.upstream), ['up_copilot', 'up_custom']);
-      // Each match carries its own per-provider endpoints — no merge.
-      assertEquals(resolved.matches[0]?.model.endpoints, { messages: {} });
-      assertEquals(resolved.matches[1]?.model.endpoints, { chatCompletions: {} });
+      const resolved = await resolveModelCandidates({
+        modelName: 'shared-model',
+        upstreamIds: null,
+        scheduler: testScheduler,
+        currentColo: 'TEST',
+        pickTarget: acceptAnyBinding,
+      });
+      assertEquals(resolved.candidates.map(c => c.binding.upstream), ['up_copilot', 'up_custom']);
+      // Each candidate carries its own per-provider endpoints — no merge.
+      assertEquals(resolved.candidates[0]?.binding.upstreamModel.endpoints, { messages: {} });
+      assertEquals(resolved.candidates[1]?.binding.upstreamModel.endpoints, { chatCompletions: {} });
     },
   );
 });
 
-test('resolveModelForRequest applies provider-owned aliases only to that provider', async () => {
+test('resolveModelCandidates applies provider-owned aliases only to that provider', async () => {
   const { repo } = await setupAppTest();
 
   await repo.upstreams.save(
@@ -240,14 +263,20 @@ test('resolveModelForRequest applies provider-owned aliases only to that provide
       throw new Error(`Unhandled fetch ${request.url}`);
     },
     async () => {
-      const resolved = await resolveModelForRequest('claude-opus-4-7-20300101', null, () => directFetcher, testScheduler);
+      const resolved = await resolveModelCandidates({
+        modelName: 'claude-opus-4-7-20300101',
+        upstreamIds: null,
+        scheduler: testScheduler,
+        currentColo: 'TEST',
+        pickTarget: acceptAnyBinding,
+      });
 
       // Only the Copilot upstream's `resolveRequestedModelId` aliases the
       // dated id back to `claude-opus-4-7`; the custom upstream resolves
       // nothing for the dated id, so only one match emerges.
-      assertEquals(resolved.matches.map(m => m.binding.upstream), ['up_copilot']);
-      assertEquals(resolved.matches[0]?.id, 'claude-opus-4-7');
-      assertEquals(resolved.matches[0]?.model.endpoints, { messages: {} });
+      assertEquals(resolved.candidates.map(c => c.binding.upstream), ['up_copilot']);
+      assertEquals(resolved.candidates[0]?.binding.upstreamModel.id, 'claude-opus-4-7');
+      assertEquals(resolved.candidates[0]?.binding.upstreamModel.endpoints, { messages: {} });
     },
   );
 });
@@ -364,16 +393,16 @@ test('disabledPublicModelIds hides models from the catalog and routing, per upst
   assertEquals([...catalog.map(m => m.id)].sort(), ['gpt-keep', 'gpt-shared']);
 
   // The solo and override ids resolve to nothing (hidden + unroutable).
-  assertEquals((await resolveModelForRequest('gpt-solo', null, () => directFetcher, testScheduler)).matches.length, 0);
-  assertEquals((await resolveModelForRequest('gpt-override', null, () => directFetcher, testScheduler)).matches.length, 0);
+  assertEquals((await resolveModelCandidates({ modelName: 'gpt-solo', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding })).candidates.length, 0);
+  assertEquals((await resolveModelCandidates({ modelName: 'gpt-override', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding })).candidates.length, 0);
 
   // The shared id survives because up_b allows it; only up_b binds it.
-  const shared = await resolveModelForRequest('gpt-shared', null, () => directFetcher, testScheduler);
-  assertEquals(shared.matches.map(m => m.binding.upstream), ['up_b']);
+  const shared = await resolveModelCandidates({ modelName: 'gpt-shared', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+  assertEquals(shared.candidates.map(c => c.binding.upstream), ['up_b']);
 
   // The untouched model still routes from up_a.
-  const keep = await resolveModelForRequest('gpt-keep', null, () => directFetcher, testScheduler);
-  assertEquals(keep.matches.map(m => m.binding.upstream), ['up_a']);
+  const keep = await resolveModelCandidates({ modelName: 'gpt-keep', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+  assertEquals(keep.candidates.map(c => c.binding.upstream), ['up_a']);
 });
 
 test('resolveModelForProvider rejects a model id disabled on that upstream (filter parity with the catalog)', async () => {
@@ -532,7 +561,7 @@ test('getInternalModels: a rejected provider does not block other providers', as
 // site asking for a model belonging to one of the *healthy* upstreams must
 // still resolve. The broken upstream's display name flows back via
 // `failedUpstreams` so the eventual error renderer can mention it.
-test('resolveModelForRequest: healthy upstream still resolves alongside a rejecting one, with failedUpstreams reported', async () => {
+test('resolveModelCandidates: healthy upstream still resolves alongside a rejecting one, with failedUpstreams reported', async () => {
   clearInFlightForTesting();
   const { repo } = await setupAppTest();
   await repo.upstreams.deleteAll();
@@ -562,17 +591,17 @@ test('resolveModelForRequest: healthy upstream still resolves alongside a reject
       throw new Error(`Unhandled fetch ${request.url}`);
     },
     async () => {
-      const resolvedExisting = await resolveModelForRequest('ok-model', null, () => directFetcher, testScheduler);
-      assertEquals(resolvedExisting.matches.map(m => m.binding.upstream), ['up_ok']);
-      assertEquals(resolvedExisting.matches[0]?.id, 'ok-model');
+      const resolvedExisting = await resolveModelCandidates({ modelName: 'ok-model', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+      assertEquals(resolvedExisting.candidates.map(c => c.binding.upstream), ['up_ok']);
+      assertEquals(resolvedExisting.candidates[0]?.binding.upstreamModel.id, 'ok-model');
       assertEquals(resolvedExisting.failedUpstreams, ['Broken upstream']);
 
       // A model nobody currently knows about must NOT rethrow the broken
       // upstream's catalog error — the caller's failure renderer is the right
       // place to surface that, parenthetically, alongside the model-missing
       // body.
-      const resolvedMissing = await resolveModelForRequest('unknown-model', null, () => directFetcher, testScheduler);
-      assertEquals(resolvedMissing.matches.length, 0);
+      const resolvedMissing = await resolveModelCandidates({ modelName: 'unknown-model', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+      assertEquals(resolvedMissing.candidates.length, 0);
       assertEquals(resolvedMissing.failedUpstreams, ['Broken upstream']);
     },
   );
@@ -719,14 +748,14 @@ describe('catalog listing under modelPrefix', () => {
         // the prefixed surface, so a byId-based routing lookup against the
         // stripped bare id would miss. Routing must instead consult each
         // scoped upstream's own catalog, where the bare id is always present.
-        const resolved = await resolveModelForRequest('or/gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(resolved.matches.map(m => m.binding.upstream), ['up_prefixed']);
-        assertEquals(resolved.matches[0]?.id, 'gpt-4o');
+        const resolved = await resolveModelCandidates({ modelName: 'or/gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(resolved.candidates.map(c => c.binding.upstream), ['up_prefixed']);
+        assertEquals(resolved.candidates[0]?.binding.upstreamModel.id, 'gpt-4o');
 
         // The bare-id request must NOT route to a prefix-only-addressable
         // upstream, regardless of routing path.
-        const bare = await resolveModelForRequest('gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(bare.matches.length, 0);
+        const bare = await resolveModelCandidates({ modelName: 'gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(bare.candidates.length, 0);
       },
     );
   });
@@ -758,16 +787,16 @@ describe('catalog listing under modelPrefix', () => {
         const catalog = await getInternalModels(null, () => directFetcher, testScheduler);
         assertEquals(catalog.map(m => m.id), ['or/gpt-4o']);
 
-        const bare = await resolveModelForRequest('gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(bare.matches.map(m => m.binding.upstream), ['up_dual_addressable']);
-        assertEquals(bare.matches[0]?.id, 'gpt-4o');
+        const bare = await resolveModelCandidates({ modelName: 'gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(bare.candidates.map(c => c.binding.upstream), ['up_dual_addressable']);
+        assertEquals(bare.candidates[0]?.binding.upstreamModel.id, 'gpt-4o');
 
         // The prefixed request enumerates both forms against `up_dual_addressable`:
         // the unprefixed lookup (`or/gpt-4o`) misses the upstream catalog, and
         // the prefix-stripped lookup (`gpt-4o`) hits — yielding a single match.
-        const prefixed = await resolveModelForRequest('or/gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(prefixed.matches.map(m => m.binding.upstream), ['up_dual_addressable']);
-        assertEquals(prefixed.matches[0]?.id, 'gpt-4o');
+        const prefixed = await resolveModelCandidates({ modelName: 'or/gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(prefixed.candidates.map(c => c.binding.upstream), ['up_dual_addressable']);
+        assertEquals(prefixed.candidates[0]?.binding.upstreamModel.id, 'gpt-4o');
       },
     );
   });
@@ -809,14 +838,14 @@ describe('catalog listing under modelPrefix', () => {
         // Both upstreams enumerate against the bare id: up_plain via its only
         // form, up_dual via the unprefixed interpretation. Order follows the
         // configured sort_order across providers, then FORM_ORDER within one.
-        const bare = await resolveModelForRequest('gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(bare.matches.map(m => m.binding.upstream), ['up_plain', 'up_dual']);
+        const bare = await resolveModelCandidates({ modelName: 'gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(bare.candidates.map(c => c.binding.upstream), ['up_plain', 'up_dual']);
 
         // The prefixed id resolves only against up_dual: up_plain's catalog
         // does not contain `or/gpt-4o`, and up_dual's prefix-stripped lookup
         // hits its catalog's bare `gpt-4o`.
-        const prefixed = await resolveModelForRequest('or/gpt-4o', null, () => directFetcher, testScheduler);
-        assertEquals(prefixed.matches.map(m => m.binding.upstream), ['up_dual']);
+        const prefixed = await resolveModelCandidates({ modelName: 'or/gpt-4o', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(prefixed.candidates.map(c => c.binding.upstream), ['up_dual']);
       },
     );
   });
@@ -899,9 +928,9 @@ describe('catalog listing under modelPrefix', () => {
         throw new Error(`Unhandled fetch ${request.url}`);
       },
       async () => {
-        const resolved = await resolveModelForRequest('aa/bb/gpt-5', null, () => directFetcher, testScheduler);
-        assertEquals(resolved.matches.map(m => m.binding.upstream), ['up_short_prefix', 'up_long_prefix', 'up_bare']);
-        assertEquals(resolved.matches.map(m => m.id), ['bb/gpt-5', 'gpt-5', 'aa/bb/gpt-5']);
+        const resolved = await resolveModelCandidates({ modelName: 'aa/bb/gpt-5', upstreamIds: null, scheduler: testScheduler, currentColo: 'TEST', pickTarget: acceptAnyBinding });
+        assertEquals(resolved.candidates.map(c => c.binding.upstream), ['up_short_prefix', 'up_long_prefix', 'up_bare']);
+        assertEquals(resolved.candidates.map(c => c.binding.upstreamModel.id), ['bb/gpt-5', 'gpt-5', 'aa/bb/gpt-5']);
       },
     );
   });
diff --git a/packages/gateway/src/data-plane/shared/passthrough-serve.ts b/packages/gateway/src/data-plane/shared/passthrough-serve.ts
index 1add1a115..a4dca72a0 100644
--- a/packages/gateway/src/data-plane/shared/passthrough-serve.ts
+++ b/packages/gateway/src/data-plane/shared/passthrough-serve.ts
@@ -19,14 +19,13 @@ import { inboundHeadersForUpstream } from './inbound-headers.ts';
 import type { PerformanceTelemetryContext } from './telemetry/performance.ts';
 import { createUpstreamLatencyRecorder, recordPerformanceError, recordPerformanceLatency, recordRequestPerformance, requireRecordedDurationMs } from './telemetry/performance.ts';
 import { recordTokenUsage } from './telemetry/usage.ts';
-import { createPerRequestFetcher } from '../../dial/per-request.ts';
 import type { AuthedContext } from '../../middleware/auth.ts';
 import type { TokenUsage } from '../../repo/types.ts';
 import type { GatewayCtx } from '../chat/shared/gateway-ctx.ts';
 import { type StreamCompletion, writeSSEFrames } from '../chat/shared/stream/sse.ts';
-import { resolveModelForRequest } from '../providers/registry.ts';
+import { resolveCandidatesAndApplyAlias } from '../model-aliases/prelude.ts';
 import type { BackgroundScheduler } from '@floway-dev/platform';
-import { doneFrame, eventFrame, parseSSEStream, parseTargetStreamFrames, type ProtocolFrame, sseCommentFrame, sseFrame } from '@floway-dev/protocols/common';
+import { doneFrame, eventFrame, type ModelEndpointKey, parseSSEStream, parseTargetStreamFrames, type ProtocolFrame, sseCommentFrame, sseFrame } from '@floway-dev/protocols/common';
 import { httpResponseToResponse, ProviderModelsUnavailableError, toInternalDebugError } from '@floway-dev/provider';
 import type { ProviderCallResult, ProviderModelRecord, UpstreamCallOptions } from '@floway-dev/provider';
 
@@ -102,7 +101,13 @@ interface PassthroughServeContext {
   // resolves it against the provider registry; if no upstream serves the
   // id, the client sees a 404 with the standard wording.
   readonly model: string;
-  readonly bindingServesEndpoint: (binding: ProviderModelRecord) => boolean;
+  // The single ModelEndpoints key this passthrough call needs the
+  // upstream binding to advertise. Used to filter the resolver's
+  // candidate matches AND to narrow the alias resolver's first-
+  // available / random pool to targets whose binding actually serves
+  // this endpoint, so an alias with mixed endpoint coverage never
+  // routes to a target that 404s downstream.
+  readonly endpointKey: ModelEndpointKey;
   // Performs the upstream HTTP call for the chosen binding. Any throw here
   // is preserved and becomes a 502 with the internal-debug envelope —
   // exceptions thrown from the actual fetch must not be silently swallowed.
@@ -118,143 +123,155 @@ export const passthroughApiError = (c: Context, message: string, status: Content
   c.json({ error: { message, type: 'api_error' } }, status);
 
 export const passthroughServe = async (input: PassthroughServeContext): Promise<Response> => {
-  const { c, ctx, sourceApi, model, bindingServesEndpoint, call, response: responseHandling } = input;
+  const { c, ctx, sourceApi, model, endpointKey, call, response: responseHandling } = input;
   const requestStartedAt = performance.now();
   let lastPerformance: PerformanceTelemetryContext | undefined;
 
   try {
-    const fetcherForUpstream = await createPerRequestFetcher(ctx.currentColo);
-    // Each match is one (upstream, upstream-catalog id) pair that interprets
-    // the inbound public id. Iteration order follows configured sort_order
-    // across upstreams, with the unprefixed interpretation pushed before the
-    // prefixed one within a single upstream. The first match whose binding
-    // satisfies the endpoint capability wins.
-    const { matches, failedUpstreams } = await resolveModelForRequest(model, ctx.upstreamIds, fetcherForUpstream, ctx.backgroundScheduler);
-    if (matches.length === 0) {
+    // Each candidate is one (upstream, upstream-catalog id) pair that
+    // interprets the inbound public id AND advertises this passthrough's
+    // endpoint. Iteration order follows configured sort_order across
+    // upstreams, with the unprefixed interpretation pushed before the
+    // prefixed one within a single upstream. The first candidate wins.
+    // See resolve.ts for the alias-resolves-once-above-prefix-routing
+    // contract; `resolveCandidatesAndApplyAlias` runs it, stages the
+    // `x-floway-alias` response header on every alias-touched path
+    // (including the 404), and surfaces a rendered failure when the
+    // alias resolver has no routable target.
+    const resolved = await resolveCandidatesAndApplyAlias({
+      ctx,
+      modelName: model,
+      pickTarget: endpoints => endpoints[endpointKey] !== undefined ? endpointKey : null,
+      renderAliasFailure: failure => {
+        ctx.dump?.error('gateway');
+        return passthroughApiError(c, failure.message, 404);
+      },
+    });
+    if (resolved.kind === 'failure') return resolved.result;
+    const { candidates, sawModel, failedUpstreams } = resolved;
+    if (!sawModel) {
       ctx.dump?.error('gateway');
       return passthroughApiError(c, appendFailedUpstreams(`Model ${model} is not available on any configured upstream.`, failedUpstreams), 404);
     }
+    const [candidate] = candidates;
+    if (candidate === undefined) {
+      ctx.dump?.error('gateway');
+      return passthroughApiError(c, appendFailedUpstreams(`Model ${model} does not support the ${sourceApi} endpoint.`, failedUpstreams), 400);
+    }
 
-    for (const match of matches) {
-      if (!bindingServesEndpoint(match.binding)) continue;
+    const recorder = createUpstreamLatencyRecorder();
+    const { response, modelKey } = await call(candidate.binding, {
+      fetcher: candidate.fetcher,
+      recordUpstreamLatency: recorder.record,
+      waitUntil: ctx.backgroundScheduler,
+      headers: inboundHeadersForUpstream(c),
+    });
+    const upstreamDurationMs = requireRecordedDurationMs(recorder, 'passthrough upstream call');
+    // Telemetry keys on the upstream's bare catalog id; user-facing
+    // error bodies echo the inbound `model`.
+    const identity = {
+      model: candidate.binding.upstreamModel.id,
+      upstream: candidate.binding.upstream,
+      modelKey,
+      cost: candidate.binding.provider.getPricingForModelKey(modelKey),
+    };
+    const performanceContext: PerformanceTelemetryContext = {
+      keyId: ctx.apiKeyId,
+      ...identity,
+      stream: responseHandling.format === 'sse',
+      runtimeLocation: ctx.runtimeLocation,
+    };
+    lastPerformance = performanceContext;
 
-      const recorder = createUpstreamLatencyRecorder();
-      const { response, modelKey } = await call(match.binding, {
-        fetcher: fetcherForUpstream(match.binding.upstream),
-        recordUpstreamLatency: recorder.record,
-        waitUntil: ctx.backgroundScheduler,
-        headers: inboundHeadersForUpstream(c),
-      });
-      const upstreamDurationMs = requireRecordedDurationMs(recorder, 'passthrough upstream call');
-      // Telemetry keys on `match.id` (the upstream's bare catalog id);
-      // user-facing error bodies echo the inbound `model`.
-      const identity = {
-        model: match.id,
-        upstream: match.binding.upstream,
-        modelKey,
-        cost: match.binding.provider.getPricingForModelKey(modelKey),
-      };
-      const performanceContext: PerformanceTelemetryContext = {
-        keyId: ctx.apiKeyId,
-        ...identity,
-        stream: responseHandling.format === 'sse',
-        runtimeLocation: ctx.runtimeLocation,
-      };
-      lastPerformance = performanceContext;
+    if (!response.ok) {
+      recordUpstreamPerformance(ctx.backgroundScheduler, performanceContext, true, upstreamDurationMs);
+      recordRequestPerformance(ctx.backgroundScheduler, performanceContext, true, performance.now() - requestStartedAt);
+      ctx.dump?.error('upstream', candidate.binding.upstream);
+      return forwardUpstreamResponse(response);
+    }
 
-      if (!response.ok) {
-        recordUpstreamPerformance(ctx.backgroundScheduler, performanceContext, true, upstreamDurationMs);
-        recordRequestPerformance(ctx.backgroundScheduler, performanceContext, true, performance.now() - requestStartedAt);
-        ctx.dump?.error('upstream', match.binding.upstream);
-        return forwardUpstreamResponse(response);
-      }
+    recordUpstreamPerformance(ctx.backgroundScheduler, performanceContext, false, upstreamDurationMs);
 
-      recordUpstreamPerformance(ctx.backgroundScheduler, performanceContext, false, upstreamDurationMs);
+    if (responseHandling.format === 'json') {
+      // A 2xx body that fails to parse must not 502 a client whose
+      // upstream call already succeeded; we skip usage extraction and
+      // log so missing rows stay traceable.
+      let parsed: unknown;
+      try {
+        parsed = await response.clone().json();
+      } catch (e) {
+        console.warn(`passthrough-serve: failed to parse 2xx upstream body for ${sourceApi}; usage row will be skipped`, e instanceof Error ? e.message : String(e));
+        parsed = undefined;
+      }
+      const usage = parsed !== undefined ? responseHandling.extractBilling(parsed) : null;
+      ctx.dump?.success(identity, usage);
+      if (usage) {
+        scheduleUsageRecord(ctx.backgroundScheduler, recordTokenUsage(ctx.apiKeyId, identity, usage));
+      }
+      recordRequestPerformance(ctx.backgroundScheduler, performanceContext, false, performance.now() - requestStartedAt);
+      return forwardUpstreamResponse(response);
+    }
 
-      if (responseHandling.format === 'json') {
-        // A 2xx body that fails to parse must not 502 a client whose
-        // upstream call already succeeded; we skip usage extraction and
-        // log so missing rows stay traceable.
-        let parsed: unknown;
-        try {
-          parsed = await response.clone().json();
-        } catch (e) {
-          console.warn(`passthrough-serve: failed to parse 2xx upstream body for ${sourceApi}; usage row will be skipped`, e instanceof Error ? e.message : String(e));
-          parsed = undefined;
+    // Hono's streamSSE owns the response — forwardable upstream
+    // headers must be staged on `c` *before* the streamSSE call so
+    // they survive its internal newResponse.
+    const upstreamBody = response.body;
+    if (!upstreamBody) {
+      ctx.dump?.failed(`${sourceApi} streaming upstream returned no body`);
+      recordRequestPerformance(ctx.backgroundScheduler, performanceContext, true, performance.now() - requestStartedAt);
+      // Preserve upstream correlation headers (x-request-id, cf-ray, ...)
+      // on the synthesized 502 so this rare edge case is still traceable.
+      stageForwardedResponseHeaders(c, response);
+      return passthroughApiError(c, 'Upstream returned a streaming response with no body.', 502);
+    }
+    stageForwardedResponseHeaders(c, response);
+    return streamSSE(c, async stream => {
+      let completion: StreamCompletion = 'error';
+      let streamError: unknown;
+      // Tracks whether the upstream's terminal (`done`) frame arrived
+      // before the writer settled. A client cancel after the terminal
+      // frame is graceful (upstream already finished its work); a
+      // mid-stream cancel or EOF without terminal is a real failure.
+      // Mirrors SourceStreamState.failedAfter on the chat endpoints.
+      let terminalFrameSeen = false;
+      try {
+        const frames = (async function* () {
+          const sseFramesIn = parseSSEStream(upstreamBody, { signal: ctx.abortSignal });
+          for await (const parsed of parseTargetStreamFrames<unknown>(sseFramesIn, { protocol: sourceApi })) {
+            const inputFrame: ProtocolFrame<unknown> = parsed.type === 'done' ? doneFrame() : eventFrame(parsed.data);
+            // Dump pre-transform, so forensics see upstream truth even
+            // when the caller drops a frame from the client-facing stream.
+            ctx.dump?.frame(inputFrame);
+            if (inputFrame.type === 'done') terminalFrameSeen = true;
+            const outputFrame = responseHandling.transformFrame(inputFrame);
+            if (outputFrame === null) continue;
+            yield outputFrame.type === 'done' ? sseFrame('[DONE]') : sseFrame(JSON.stringify(outputFrame.event));
+          }
+        })();
+        completion = await writeSSEFrames(stream, frames, {
+          keepAlive: { frame: sseCommentFrame('keepalive') },
+          downstreamAbortController: ctx.downstreamAbortController,
+        });
+      } catch (e) {
+        streamError = e;
+      } finally {
+        const usage = responseHandling.settleUsage();
+        const failed = streamError !== undefined || completion === 'error' || !terminalFrameSeen;
+        if (failed) {
+          ctx.dump?.failed(streamError ?? `${sourceApi} stream ended with completion=${completion}`);
+        } else {
+          ctx.dump?.success(identity, usage);
         }
-        const usage = parsed !== undefined ? responseHandling.extractBilling(parsed) : null;
-        ctx.dump?.success(identity, usage);
+        // Record any accumulated usage regardless of the failed flag —
+        // tokens already metered upstream should bill even when the
+        // downstream half of the round-trip turned out badly. The chat
+        // streaming endpoints follow the same rule.
         if (usage) {
           scheduleUsageRecord(ctx.backgroundScheduler, recordTokenUsage(ctx.apiKeyId, identity, usage));
         }
-        recordRequestPerformance(ctx.backgroundScheduler, performanceContext, false, performance.now() - requestStartedAt);
-        return forwardUpstreamResponse(response);
-      }
-
-      // Hono's streamSSE owns the response — forwardable upstream
-      // headers must be staged on `c` *before* the streamSSE call so
-      // they survive its internal newResponse.
-      const upstreamBody = response.body;
-      if (!upstreamBody) {
-        ctx.dump?.failed(`${sourceApi} streaming upstream returned no body`);
-        recordRequestPerformance(ctx.backgroundScheduler, performanceContext, true, performance.now() - requestStartedAt);
-        // Preserve upstream correlation headers (x-request-id, cf-ray, ...)
-        // on the synthesized 502 so this rare edge case is still traceable.
-        stageForwardedResponseHeaders(c, response);
-        return passthroughApiError(c, 'Upstream returned a streaming response with no body.', 502);
+        recordRequestPerformance(ctx.backgroundScheduler, performanceContext, failed, performance.now() - requestStartedAt);
       }
-      stageForwardedResponseHeaders(c, response);
-      return streamSSE(c, async stream => {
-        let completion: StreamCompletion = 'error';
-        let streamError: unknown;
-        // Tracks whether the upstream's terminal (`done`) frame arrived
-        // before the writer settled. A client cancel after the terminal
-        // frame is graceful (upstream already finished its work); a
-        // mid-stream cancel or EOF without terminal is a real failure.
-        // Mirrors SourceStreamState.failedAfter on the chat endpoints.
-        let terminalFrameSeen = false;
-        try {
-          const frames = (async function* () {
-            const sseFramesIn = parseSSEStream(upstreamBody, { signal: ctx.abortSignal });
-            for await (const parsed of parseTargetStreamFrames<unknown>(sseFramesIn, { protocol: sourceApi })) {
-              const inputFrame: ProtocolFrame<unknown> = parsed.type === 'done' ? doneFrame() : eventFrame(parsed.data);
-              // Dump pre-transform, so forensics see upstream truth even
-              // when the caller drops a frame from the client-facing stream.
-              ctx.dump?.frame(inputFrame);
-              if (inputFrame.type === 'done') terminalFrameSeen = true;
-              const outputFrame = responseHandling.transformFrame(inputFrame);
-              if (outputFrame === null) continue;
-              yield outputFrame.type === 'done' ? sseFrame('[DONE]') : sseFrame(JSON.stringify(outputFrame.event));
-            }
-          })();
-          completion = await writeSSEFrames(stream, frames, {
-            keepAlive: { frame: sseCommentFrame('keepalive') },
-            downstreamAbortController: ctx.downstreamAbortController,
-          });
-        } catch (e) {
-          streamError = e;
-        } finally {
-          const usage = responseHandling.settleUsage();
-          const failed = streamError !== undefined || completion === 'error' || !terminalFrameSeen;
-          if (failed) {
-            ctx.dump?.failed(streamError ?? `${sourceApi} stream ended with completion=${completion}`);
-          } else {
-            ctx.dump?.success(identity, usage);
-          }
-          // Record any accumulated usage regardless of the failed flag —
-          // tokens already metered upstream should bill even when the
-          // downstream half of the round-trip turned out badly. The chat
-          // streaming endpoints follow the same rule.
-          if (usage) {
-            scheduleUsageRecord(ctx.backgroundScheduler, recordTokenUsage(ctx.apiKeyId, identity, usage));
-          }
-          recordRequestPerformance(ctx.backgroundScheduler, performanceContext, failed, performance.now() - requestStartedAt);
-        }
-      });
-    }
-
-    ctx.dump?.error('gateway');
-    return passthroughApiError(c, appendFailedUpstreams(`Model ${model} does not support the ${sourceApi} endpoint.`, failedUpstreams), 400);
+    });
   } catch (e) {
     if (e instanceof ProviderModelsUnavailableError) {
       const forwarded = httpResponseToResponse(e.httpResponse);
diff --git a/packages/gateway/src/data-plane/shared/passthrough-serve_test.ts b/packages/gateway/src/data-plane/shared/passthrough-serve_test.ts
index 6fbf01d90..a14a77795 100644
--- a/packages/gateway/src/data-plane/shared/passthrough-serve_test.ts
+++ b/packages/gateway/src/data-plane/shared/passthrough-serve_test.ts
@@ -180,3 +180,53 @@ test('passthrough-serve: response header allow-list forwards expected headers an
     },
   );
 });
+
+test('passthrough-serve: alias resolves to no routable target — 404 envelope + x-floway-alias header', async () => {
+  // Mirrors the four chat-protocol serve_test cases: when the alias
+  // resolver throws `AliasNoTargetAvailableError`, the shared prelude
+  // converts it to a passthrough-shaped 404 and stages the
+  // `x-floway-alias` correlation header. No upstream call should fire.
+  const { apiKey, repo } = await setupAppTest();
+  await registerEmbeddingsUpstream(repo);
+  // Seed an alias whose only target id does not exist in any upstream
+  // catalog, so the resolver builds an empty available pool and throws.
+  await repo.modelAliases.insert({
+    name: 'embed-fast',
+    kind: 'embedding',
+    selection: 'first-available',
+    displayName: null,
+    visibleInModelsList: true,
+    targets: [{ target_model_id: 'unknown-embed', rules: {} }],
+    announcedMetadata: null,
+    sortOrder: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  });
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'passthrough.example.com' && url.pathname === '/v1/models') {
+        return jsonResponse({ object: 'list', data: [{ id: 'custom-embed-model' }] });
+      }
+      if (url.hostname === 'passthrough.example.com' && url.pathname === '/v1/embeddings') {
+        throw new Error('passthrough-serve: upstream must not be called when alias has no routable target');
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const response = await requestApp('/v1/embeddings', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-api-key': apiKey.key },
+        body: JSON.stringify({ model: 'embed-fast', input: 'hi' }),
+      });
+
+      assertEquals(response.status, 404);
+      assertEquals(response.headers.get('x-floway-alias'), 'embed-fast');
+      const body = await response.json() as { error: { message: string; type: string } };
+      assertEquals(body.error.type, 'api_error');
+      // The canonical wording carries the alias name + configured count.
+      assertEquals(body.error.message.includes("alias 'embed-fast'"), true);
+    },
+  );
+});
diff --git a/packages/gateway/src/repo/memory.ts b/packages/gateway/src/repo/memory.ts
index 5a85dba39..6e832d67b 100644
--- a/packages/gateway/src/repo/memory.ts
+++ b/packages/gateway/src/repo/memory.ts
@@ -13,6 +13,8 @@ import type {
   ApiKeyRepo,
   BackoffRow,
   CachedModelsRow,
+  ModelAliasesRepo,
+  ModelAliasRecord,
   ModelsCacheRepo,
   PerformanceDimensions,
   PerformanceErrorSample,
@@ -882,6 +884,54 @@ class MemoryProxyBackoffRepo implements ProxyBackoffRepo {
 
 const cloneBackoffRow = (row: BackoffRow): BackoffRow => ({ ...row });
 
+const cloneModelAliasRecord = (record: ModelAliasRecord): ModelAliasRecord => ({
+  ...record,
+  targets: structuredClone(record.targets),
+  announcedMetadata: record.announcedMetadata === null ? null : structuredClone(record.announcedMetadata),
+});
+
+class MemoryModelAliasesRepo implements ModelAliasesRepo {
+  private store = new Map<string, ModelAliasRecord>();
+
+  list(): Promise<ModelAliasRecord[]> {
+    return Promise.resolve(
+      [...this.store.values()]
+        .map(cloneModelAliasRecord)
+        .sort((a, b) => a.sortOrder - b.sortOrder || a.createdAt.localeCompare(b.createdAt)),
+    );
+  }
+
+  getByName(name: string): Promise<ModelAliasRecord | null> {
+    const found = this.store.get(name);
+    return Promise.resolve(found ? cloneModelAliasRecord(found) : null);
+  }
+
+  insert(record: ModelAliasRecord): Promise<void> {
+    if (this.store.has(record.name)) throw new Error(`alias ${record.name} already exists`);
+    this.store.set(record.name, cloneModelAliasRecord(record));
+    return Promise.resolve();
+  }
+
+  update(oldName: string, record: ModelAliasRecord): Promise<void> {
+    if (!this.store.has(oldName)) throw new Error(`alias ${oldName} not found`);
+    if (oldName !== record.name && this.store.has(record.name)) {
+      throw new Error(`alias ${record.name} already exists`);
+    }
+    this.store.delete(oldName);
+    this.store.set(record.name, cloneModelAliasRecord(record));
+    return Promise.resolve();
+  }
+
+  delete(name: string): Promise<boolean> {
+    return Promise.resolve(this.store.delete(name));
+  }
+
+  deleteAll(): Promise<void> {
+    this.store.clear();
+    return Promise.resolve();
+  }
+}
+
 export class InMemoryRepo implements Repo {
   apiKeys: ApiKeyRepo;
   users: UsersRepo;
@@ -894,6 +944,7 @@ export class InMemoryRepo implements Repo {
   upstreams: UpstreamRepo;
   proxies: ProxyRepo;
   proxyBackoffs: ProxyBackoffRepo;
+  modelAliases: ModelAliasesRepo;
   responsesItems: ResponsesItemsRepo;
   responsesSnapshots: ResponsesSnapshotsRepo;
 
@@ -909,6 +960,7 @@ export class InMemoryRepo implements Repo {
     this.upstreams = new MemoryUpstreamRepo();
     this.proxies = new MemoryProxyRepo(this.upstreams);
     this.proxyBackoffs = new MemoryProxyBackoffRepo();
+    this.modelAliases = new MemoryModelAliasesRepo();
     this.responsesItems = new MemoryResponsesItemsRepo();
     this.responsesSnapshots = new MemoryResponsesSnapshotsRepo();
   }
diff --git a/packages/gateway/src/repo/sql.ts b/packages/gateway/src/repo/sql.ts
index b716d07e4..623a63cd1 100644
--- a/packages/gateway/src/repo/sql.ts
+++ b/packages/gateway/src/repo/sql.ts
@@ -7,6 +7,8 @@ import type {
   ApiKeyRepo,
   BackoffRow,
   CachedModelsRow,
+  ModelAliasesRepo,
+  ModelAliasRecord,
   ModelsCacheRepo,
   PerformanceDimensions,
   PerformanceErrorSample,
@@ -38,7 +40,7 @@ import { latencyBucketForMs } from '../shared/performance-histogram.ts';
 import { generateSessionToken } from '../shared/session-tokens.ts';
 import { assertWebSearchProviderName } from '../shared/web-search-providers.ts';
 import type { SqlDatabase, SqlPreparedStatement, SqlResult } from '@floway-dev/platform';
-import { BILLING_DIMENSIONS, type BillingDimension, type ModelPricing, resolveEffectivePricing, unitPriceForDimension } from '@floway-dev/protocols/common';
+import { BILLING_DIMENSIONS, type AliasKind, type AliasSelection, type AliasTarget, type AnnouncedMetadata, type BillingDimension, type ModelPricing, resolveEffectivePricing, unitPriceForDimension } from '@floway-dev/protocols/common';
 import type { ProxyFallbackEntry, ModelPrefixConfig, UpstreamModel, UpstreamProviderKind, UpstreamRecord } from '@floway-dev/provider';
 import { normalizeModelPrefix } from '@floway-dev/provider';
 
@@ -1585,6 +1587,167 @@ const toBackoffRow = (row: BackoffRowDb): BackoffRow => ({
   lastErrorAt: row.last_error_at,
 });
 
+interface ModelAliasRow {
+  name: string;
+  kind: string;
+  selection: string;
+  display_name: string | null;
+  visible_in_models_list: number;
+  targets: string;
+  announced_metadata_json: string | null;
+  sort_order: number;
+  created_at: string;
+  updated_at: string;
+}
+
+const MODEL_ALIAS_COLUMNS = 'name, kind, selection, display_name, visible_in_models_list, targets, announced_metadata_json, sort_order, created_at, updated_at';
+
+const parseAliasTargets = (raw: string, name: string): AliasTarget[] => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`model_aliases.targets JSON is malformed for ${name}`, { cause });
+  }
+  if (!Array.isArray(parsed)) throw new Error(`model_aliases.targets is not an array for ${name}`);
+  return parsed as AliasTarget[];
+};
+
+const parseAnnouncedMetadata = (raw: string | null, name: string): AnnouncedMetadata | null => {
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw) as AnnouncedMetadata;
+  } catch (cause) {
+    throw new Error(`model_aliases.announced_metadata_json is malformed for ${name}`, { cause });
+  }
+};
+
+const toModelAliasRecord = (row: ModelAliasRow): ModelAliasRecord => ({
+  name: row.name,
+  kind: row.kind as AliasKind,
+  selection: row.selection as AliasSelection,
+  displayName: row.display_name,
+  visibleInModelsList: row.visible_in_models_list !== 0,
+  targets: parseAliasTargets(row.targets, row.name),
+  announcedMetadata: parseAnnouncedMetadata(row.announced_metadata_json, row.name),
+  sortOrder: row.sort_order,
+  createdAt: row.created_at,
+  updatedAt: row.updated_at,
+});
+
+const announcedMetadataBind = (value: AnnouncedMetadata | null): string | null =>
+  value === null ? null : JSON.stringify(value);
+
+class SqlModelAliasesRepo implements ModelAliasesRepo {
+  constructor(private db: SqlDatabase) {}
+
+  async list(): Promise<ModelAliasRecord[]> {
+    const { results } = await this.db
+      .prepare(`SELECT ${MODEL_ALIAS_COLUMNS} FROM model_aliases ORDER BY sort_order, created_at`)
+      .all<ModelAliasRow>();
+    return results.map(toModelAliasRecord);
+  }
+
+  async getByName(name: string): Promise<ModelAliasRecord | null> {
+    const row = await this.db
+      .prepare(`SELECT ${MODEL_ALIAS_COLUMNS} FROM model_aliases WHERE name = ?`)
+      .bind(name)
+      .first<ModelAliasRow>();
+    return row ? toModelAliasRecord(row) : null;
+  }
+
+  async insert(record: ModelAliasRecord): Promise<void> {
+    await this.db
+      .prepare(
+        `INSERT INTO model_aliases (${MODEL_ALIAS_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .bind(
+        record.name,
+        record.kind,
+        record.selection,
+        record.displayName,
+        record.visibleInModelsList ? 1 : 0,
+        JSON.stringify(record.targets),
+        announcedMetadataBind(record.announcedMetadata),
+        record.sortOrder,
+        record.createdAt,
+        record.updatedAt,
+      )
+      .run();
+  }
+
+  async update(oldName: string, record: ModelAliasRecord): Promise<void> {
+    if (oldName === record.name) {
+      const result = await this.db
+        .prepare(
+          `UPDATE model_aliases SET
+             kind = ?,
+             selection = ?,
+             display_name = ?,
+             visible_in_models_list = ?,
+             targets = ?,
+             announced_metadata_json = ?,
+             sort_order = ?,
+             created_at = ?,
+             updated_at = ?
+           WHERE name = ?`,
+        )
+        .bind(
+          record.kind,
+          record.selection,
+          record.displayName,
+          record.visibleInModelsList ? 1 : 0,
+          JSON.stringify(record.targets),
+          announcedMetadataBind(record.announcedMetadata),
+          record.sortOrder,
+          record.createdAt,
+          record.updatedAt,
+          oldName,
+        )
+        .run();
+      if ((result.meta.changes ?? 0) === 0) throw new Error(`alias ${oldName} not found`);
+      return;
+    }
+
+    // Rename. Verify the source row exists first, then INSERT(new) +
+    // DELETE(old) atomically through the batch primitive — a PK collision
+    // against `record.name` bubbles up from the INSERT, which the route
+    // layer translates to 409.
+    const existing = await this.getByName(oldName);
+    if (!existing) throw new Error(`alias ${oldName} not found`);
+
+    await runStatements(this.db, [
+      this.db
+        .prepare(`INSERT INTO model_aliases (${MODEL_ALIAS_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .bind(
+          record.name,
+          record.kind,
+          record.selection,
+          record.displayName,
+          record.visibleInModelsList ? 1 : 0,
+          JSON.stringify(record.targets),
+          announcedMetadataBind(record.announcedMetadata),
+          record.sortOrder,
+          record.createdAt,
+          record.updatedAt,
+        ),
+      this.db.prepare('DELETE FROM model_aliases WHERE name = ?').bind(oldName),
+    ]);
+  }
+
+  async delete(name: string): Promise<boolean> {
+    const result = await this.db
+      .prepare('DELETE FROM model_aliases WHERE name = ?')
+      .bind(name)
+      .run();
+    return (result.meta.changes ?? 0) > 0;
+  }
+
+  async deleteAll(): Promise<void> {
+    await this.db.prepare('DELETE FROM model_aliases').run();
+  }
+}
+
 export class SqlRepo implements Repo {
   users: UsersRepo;
   sessions: SessionsRepo;
@@ -1597,6 +1760,7 @@ export class SqlRepo implements Repo {
   upstreams: UpstreamRepo;
   proxies: ProxyRepo;
   proxyBackoffs: ProxyBackoffRepo;
+  modelAliases: ModelAliasesRepo;
   responsesItems: ResponsesItemsRepo;
   responsesSnapshots: ResponsesSnapshotsRepo;
 
@@ -1612,6 +1776,7 @@ export class SqlRepo implements Repo {
     this.upstreams = new SqlUpstreamRepo(db);
     this.proxies = new SqlProxyRepo(db);
     this.proxyBackoffs = new SqlProxyBackoffRepo(db);
+    this.modelAliases = new SqlModelAliasesRepo(db);
     this.responsesItems = new SqlResponsesItemsRepo(db);
     this.responsesSnapshots = new SqlResponsesSnapshotsRepo(db);
   }
diff --git a/packages/gateway/src/repo/types.ts b/packages/gateway/src/repo/types.ts
index 0341d41ef..77d168fb5 100644
--- a/packages/gateway/src/repo/types.ts
+++ b/packages/gateway/src/repo/types.ts
@@ -1,6 +1,6 @@
 import type { HistogramBucket } from '../shared/performance-histogram.ts';
 import type { WebSearchProviderName } from '../shared/web-search-providers.ts';
-import type { BillingDimension, ModelPricing } from '@floway-dev/protocols/common';
+import type { AliasKind, AliasSelection, AliasTarget, AnnouncedMetadata, BillingDimension, ModelPricing } from '@floway-dev/protocols/common';
 import type { UpstreamModel, UpstreamRecord } from '@floway-dev/provider';
 
 export interface ApiKey {
@@ -264,6 +264,45 @@ export interface ProxyBackoffRepo {
   deleteAll(): Promise<void>;
 }
 
+// One alias row. The wire DTO (`ModelAlias` in @floway-dev/protocols/common)
+// is the snake_case projection of this record; conversion lives in
+// control-plane/model-aliases/serialize.ts.
+export interface ModelAliasRecord {
+  name: string;
+  kind: AliasKind;
+  selection: AliasSelection;
+  // null = derive at render time from targets + rules.
+  displayName: string | null;
+  visibleInModelsList: boolean;
+  // Order is meaningful for selection=first-available; preserved (but
+  // ignored) for selection=random.
+  targets: AliasTarget[];
+  // null = compute the announced /v1/models payload automatically from
+  // targets + rules at listing time. A non-null payload replaces the
+  // computed value at the top-level sub-block boundary (`limits` /
+  // `chat`); omitted sub-blocks fall back to the computation but a
+  // present sub-block wins wholesale (it does not merge per-leaf).
+  announcedMetadata: AnnouncedMetadata | null;
+  sortOrder: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ModelAliasesRepo {
+  list(): Promise<ModelAliasRecord[]>;
+  getByName(name: string): Promise<ModelAliasRecord | null>;
+  // Throws on primary-key collision so the route layer can surface a 409.
+  insert(record: ModelAliasRecord): Promise<void>;
+  // Replaces the row keyed by `oldName`. When oldName === record.name the
+  // call is a plain UPDATE; when they differ this is a rename, executed as
+  // INSERT(new) + DELETE(old) inside one transaction so dependent reads
+  // stay consistent. Throws when `oldName` does not exist, or when the
+  // rename target already collides with a different row.
+  update(oldName: string, record: ModelAliasRecord): Promise<void>;
+  delete(name: string): Promise<boolean>;
+  deleteAll(): Promise<void>;
+}
+
 export interface StoredResponsesItem {
   id: string;
   apiKeyId: string | null;
@@ -330,6 +369,7 @@ export interface Repo {
   upstreams: UpstreamRepo;
   proxies: ProxyRepo;
   proxyBackoffs: ProxyBackoffRepo;
+  modelAliases: ModelAliasesRepo;
   responsesItems: ResponsesItemsRepo;
   responsesSnapshots: ResponsesSnapshotsRepo;
 }
diff --git a/packages/gateway/src/test-helpers/gateway-ctx.ts b/packages/gateway/src/test-helpers/gateway-ctx.ts
index 3a19af303..3ebf1f474 100644
--- a/packages/gateway/src/test-helpers/gateway-ctx.ts
+++ b/packages/gateway/src/test-helpers/gateway-ctx.ts
@@ -15,5 +15,6 @@ export const mockGatewayCtx = (overrides: Partial<GatewayCtx> = {}): GatewayCtx
   dump: null,
   backgroundScheduler: promise => { void promise; },
   requestStartedAt: 0,
+  responseHeaders: new Headers(),
   ...overrides,
 });
diff --git a/packages/protocols/package.json b/packages/protocols/package.json
index 5ada835f0..1a8409de0 100644
--- a/packages/protocols/package.json
+++ b/packages/protocols/package.json
@@ -12,7 +12,8 @@
     "./messages": { "import": "./src/messages/index.ts", "types": "./src/messages/index.ts" },
     "./gemini": { "import": "./src/gemini/index.ts", "types": "./src/gemini/index.ts" },
     "./embeddings": { "import": "./src/embeddings/index.ts", "types": "./src/embeddings/index.ts" },
-    "./images": { "import": "./src/images/index.ts", "types": "./src/images/index.ts" }
+    "./images": { "import": "./src/images/index.ts", "types": "./src/images/index.ts" },
+    "./extensions": { "import": "./src/extensions/index.ts", "types": "./src/extensions/index.ts" }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
diff --git a/packages/protocols/src/chat-completions/index.ts b/packages/protocols/src/chat-completions/index.ts
index 582381555..07a502ff5 100644
--- a/packages/protocols/src/chat-completions/index.ts
+++ b/packages/protocols/src/chat-completions/index.ts
@@ -18,6 +18,11 @@ export interface ChatCompletionsPayload {
   parallel_tool_calls?: boolean | null;
   response_format?: Record<string, unknown> | null;
   reasoning_effort?: string | null;
+  // GPT-5-family response-length control. Native OpenAI Chat field; Floway
+  // mirrors it onto Responses `text.verbosity` and exposes it as an
+  // extension on Messages / Gemini IRs.
+  // Reference: https://platform.openai.com/docs/api-reference/chat/create
+  verbosity?: string | null;
   prompt_cache_key?: string | null;
   safety_identifier?: string | null;
   service_tier?: 'default' | 'auto' | 'flex' | 'priority' | 'scale' | (string & {}) | null;
@@ -25,6 +30,12 @@ export interface ChatCompletionsPayload {
   tool_choice?: 'none' | 'auto' | 'required' | { type: 'function'; function: { name: string } } | null;
   /** Request usage stats in streaming responses */
   stream_options?: { include_usage: boolean } | null;
+  /** Floway protocol extension. Translated to Anthropic `thinking.budget_tokens` / Gemini `thinkingConfig.thinkingBudget` when routed to those upstreams; dropped on OpenAI Chat/Responses targets. */
+  thinking_budget?: number;
+  /** Floway protocol extension. Translated to Anthropic `thinking.type: "adaptive"` / Gemini `thinkingConfig.thinkingBudget: -1` when routed to those upstreams; dropped on OpenAI Chat/Responses targets. */
+  adaptive_thinking?: boolean;
+  /** Floway protocol extension. Translated to OpenAI Responses `reasoning.summary` / Anthropic `thinking.display` / Gemini `thinkingConfig.includeThoughts` when routed to those upstreams; dropped on OpenAI Chat targets. */
+  reasoning_summary?: string;
 }
 
 export interface ChatCompletionsTool {
diff --git a/packages/protocols/src/common/aliases.ts b/packages/protocols/src/common/aliases.ts
new file mode 100644
index 000000000..7a0f37936
--- /dev/null
+++ b/packages/protocols/src/common/aliases.ts
@@ -0,0 +1,165 @@
+// Wire-level types for model aliases. Lives in @floway-dev/protocols because
+// both the gateway control plane and the dashboard SPA need the same DTO
+// shape — keeping it here means a single source of truth for snake_case
+// field names and the JSON-serializable rule shapes.
+//
+// An alias is a named virtual model id that resolves at request time to one
+// of N target model ids, optionally overlaying protocol-rule overrides
+// (reasoning effort, verbosity, service tier, ...) onto the request IR.
+// Resolution runs above prefix routing and never re-enters itself, which
+// makes recursive aliasing impossible by construction.
+
+import type { ChatModelInfo, PublicModelLimits } from './models.ts';
+
+// Endpoint family the alias serves. An alias belongs to exactly one kind;
+// rules are only allowed when the kind admits them (today that is `chat`).
+export type AliasKind = 'chat' | 'embedding' | 'image';
+
+// Target-picking strategy applied to the pool of currently-routable targets:
+//
+// - `first-available` — pick the first target in declaration order whose
+//   target_model_id resolves to an enabled upstream binding.
+// - `random` — pick uniformly at random from the same pool.
+//
+// When the pool is empty both strategies surface the same 404 to the caller.
+export type AliasSelection = 'random' | 'first-available';
+
+// Discrete reasoning-effort presets understood across upstreams. The literal
+// union surfaces the canonical presets to editor autocomplete while the
+// `(string & {})` arm keeps the type open — the gateway forwards rule values
+// verbatim and never enum-gates them at the wire boundary, so an operator
+// can pin any string the upstream understands.
+export type ReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | (string & {});
+
+// Reasoning-summary verbosity hint emitted on the Responses / Chat surface.
+// Same open-literal shape as `ReasoningEffort`.
+export type ReasoningSummary = 'auto' | 'concise' | 'detailed' | 'none' | (string & {});
+
+// Output verbosity hint (OpenAI Responses `verbosity`). Same open-literal
+// shape as `ReasoningEffort`.
+export type Verbosity = 'low' | 'medium' | 'high' | (string & {});
+
+// Per-request service tier the upstream advertises. Same open-literal shape
+// as `ReasoningEffort`.
+export type ServiceTier = 'default' | 'flex' | 'priority' | 'scale' | 'fast' | (string & {});
+
+// Rule overlay applied to a chat-kind alias target. Every field is optional;
+// an absent field leaves the inbound request value untouched. Rule values
+// are forwarded verbatim to the upstream — the gateway does not narrow them
+// against the target's advertised capability metadata.
+export interface ChatAliasRules {
+  reasoning?: {
+    effort?: ReasoningEffort;
+    budget_tokens?: number;
+    adaptive?: boolean;
+    summary?: ReasoningSummary;
+  };
+  verbosity?: Verbosity;
+  serviceTier?: ServiceTier;
+}
+
+// Rule overlay payload. Today only chat-kind aliases carry rules — embedding
+// and image targets pass `{}`, which already satisfies `ChatAliasRules`
+// because every field is optional. The type is a single alias rather than a
+// union so consumers can read `rules.reasoning?.effort` directly without an
+// unchecked cast.
+export type AliasRules = ChatAliasRules;
+
+// One target row inside an alias's `targets` list. Order is meaningful for
+// `first-available` selection and preserved (but ignored) for `random`.
+export interface AliasTarget {
+  target_model_id: string;
+  rules: AliasRules;
+}
+
+// Operator-set override for the alias's announced /v1/models payload —
+// the `limits` + `chat.*` block the listing surfaces to clients. Sparse:
+// any top-level sub-block (`limits` / `chat`) the operator leaves unset
+// falls back wholesale to the rule-aware intersection across the alias's
+// available targets. Fallback is at the sub-block boundary, not per-leaf:
+// posting `{ limits: { max_output_tokens: 8192 } }` replaces `limits`
+// entirely, so other limit keys disappear from the announced metadata
+// unless the override re-states them. (The dashboard hides this by
+// seeding the buffer from the full computed snapshot at the moment the
+// "Enable override" switch flips on.) `kind` and the supported endpoint
+// set are not part of this payload; they follow from the alias row
+// (`kind`) and the target union (endpoints).
+export interface AnnouncedMetadata {
+  limits?: PublicModelLimits;
+  chat?: ChatModelInfo;
+}
+
+// Wire DTO returned by `/api/aliases`. snake_case to match the rest of the
+// control plane; `display_name === null` means "derive at render time";
+// `announced_metadata === null` means "compute the announced payload from
+// targets + rules at listing time".
+export interface ModelAlias {
+  name: string;
+  kind: AliasKind;
+  selection: AliasSelection;
+  display_name: string | null;
+  visible_in_models_list: boolean;
+  targets: AliasTarget[];
+  announced_metadata: AnnouncedMetadata | null;
+  sort_order: number;
+  created_at: string;
+  updated_at: string;
+}
+
+// One badge per configured rule field, in the canonical order. `field`
+// names the specific rule slot the badge describes so consumers (the
+// dashboard's `ModelInfoBar`, alias-of multi-target collapse) can group
+// by field without parsing the human-readable label. `value` is reserved
+// for callers that want to render a separate value pill alongside the
+// label; today every part already self-describes through `label`, so
+// `value` stays undefined.
+export type AliasRuleBadgeField =
+  | 'reasoning.effort'
+  | 'reasoning.budget_tokens'
+  | 'reasoning.adaptive'
+  | 'reasoning.summary'
+  | 'verbosity'
+  | 'serviceTier';
+
+export interface AliasRuleBadge {
+  label: string;
+  field: AliasRuleBadgeField;
+  value?: string;
+}
+
+// Inline-prose parts for an alias's rules, in the canonical field order. The
+// same builder backs `formatAliasRulesInline` (joins labels with `, ` for a
+// single summary string) and `formatAliasRuleBadges` (emits badge rows).
+// Keeping every surface — inline copy, badge sequence, parenthesized
+// suffix in the derived display name — on a single ordered walk means an
+// operator who configures `effort + verbosity` sees them in the same order
+// whether the dashboard renders badges or a comma-joined caption.
+const aliasRuleParts = (rules: AliasRules): AliasRuleBadge[] => {
+  const parts: AliasRuleBadge[] = [];
+  if (rules.reasoning?.effort !== undefined) parts.push({ field: 'reasoning.effort', label: `${rules.reasoning.effort} effort` });
+  if (rules.reasoning?.budget_tokens !== undefined) parts.push({ field: 'reasoning.budget_tokens', label: `${rules.reasoning.budget_tokens}tok budget` });
+  if (rules.reasoning?.adaptive === true) parts.push({ field: 'reasoning.adaptive', label: 'adaptive' });
+  else if (rules.reasoning?.adaptive === false) parts.push({ field: 'reasoning.adaptive', label: 'non-adaptive' });
+  if (rules.reasoning?.summary !== undefined) parts.push({ field: 'reasoning.summary', label: `summary: ${rules.reasoning.summary}` });
+  if (rules.verbosity !== undefined) parts.push({ field: 'verbosity', label: `${rules.verbosity} verbosity` });
+  if (rules.serviceTier !== undefined) parts.push({ field: 'serviceTier', label: `${rules.serviceTier} tier` });
+  return parts;
+};
+
+export const formatAliasRuleBadges = (rules: AliasRules): AliasRuleBadge[] => aliasRuleParts(rules);
+
+// Comma-joined version of the same ordered parts. Empty string when no
+// rule applies — callers should drop the line entirely rather than render
+// blank.
+export const formatAliasRulesInline = (rules: AliasRules): string =>
+  aliasRuleParts(rules).map(p => p.label).join(', ');
+
+// Derived display name for a single-target alias whose operator did not set
+// `display_name`. Bare `target_model_id` when no rule is configured; with
+// rules, the inline summary is parenthesized. Multi-target aliases skip
+// this helper entirely — the listing falls back to the alias's own name
+// because no single target represents the alias.
+export const composeAliasDisplayName = (targetModelId: string, rules: AliasRules): string => {
+  const inline = formatAliasRulesInline(rules);
+  return inline === '' ? targetModelId : `${targetModelId} (${inline})`;
+};
diff --git a/packages/protocols/src/common/aliases_test.ts b/packages/protocols/src/common/aliases_test.ts
new file mode 100644
index 000000000..adb380af5
--- /dev/null
+++ b/packages/protocols/src/common/aliases_test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'vitest';
+
+import { composeAliasDisplayName, formatAliasRuleBadges, formatAliasRulesInline } from './aliases.ts';
+
+describe('composeAliasDisplayName', () => {
+  test('bare target id when no rules apply', () => {
+    expect(composeAliasDisplayName('gpt-5.4', {})).toBe('gpt-5.4');
+  });
+
+  test('parenthesizes the inline summary when a rule is set', () => {
+    expect(composeAliasDisplayName('gpt-5.4', { reasoning: { effort: 'low' } })).toBe('gpt-5.4 (low effort)');
+  });
+});
+
+describe('formatAliasRulesInline', () => {
+  test('returns empty string when no rule is set', () => {
+    expect(formatAliasRulesInline({})).toBe('');
+  });
+
+  test('joins configured parts in the canonical order', () => {
+    expect(formatAliasRulesInline({
+      reasoning: { effort: 'high' },
+      verbosity: 'low',
+      serviceTier: 'priority',
+    })).toBe('high effort, low verbosity, priority tier');
+  });
+
+  test('renders boolean reasoning toggles in their dedicated wording', () => {
+    expect(formatAliasRulesInline({
+      reasoning: { adaptive: false, summary: 'concise' },
+    })).toBe('non-adaptive, summary: concise');
+  });
+
+  test('emits adaptive when reasoning.adaptive is true and budget_tokens when set', () => {
+    expect(formatAliasRulesInline({
+      reasoning: { budget_tokens: 4096, adaptive: true },
+    })).toBe('4096tok budget, adaptive');
+  });
+});
+
+describe('formatAliasRuleBadges', () => {
+  test('returns one badge per configured part in the canonical order with explicit field keys', () => {
+    expect(formatAliasRuleBadges({
+      reasoning: { effort: 'high', budget_tokens: 2048 },
+      verbosity: 'medium',
+    })).toEqual([
+      { field: 'reasoning.effort', label: 'high effort' },
+      { field: 'reasoning.budget_tokens', label: '2048tok budget' },
+      { field: 'verbosity', label: 'medium verbosity' },
+    ]);
+  });
+
+  test('returns an empty array when no rule is set', () => {
+    expect(formatAliasRuleBadges({})).toEqual([]);
+  });
+});
diff --git a/packages/protocols/src/common/index.ts b/packages/protocols/src/common/index.ts
index 51f8ef53b..1af2533bb 100644
--- a/packages/protocols/src/common/index.ts
+++ b/packages/protocols/src/common/index.ts
@@ -1,3 +1,4 @@
+export * from './aliases.ts';
 export * from './capabilities.ts';
 export * from './models.ts';
 export * from './openai-stream.ts';
diff --git a/packages/protocols/src/common/models.ts b/packages/protocols/src/common/models.ts
index 54243d56d..a48023307 100644
--- a/packages/protocols/src/common/models.ts
+++ b/packages/protocols/src/common/models.ts
@@ -1,3 +1,6 @@
+import type { AliasKind, AliasSelection, AliasTarget } from './aliases.ts';
+import type { ModelEndpoints } from './capabilities.ts';
+
 // Disjoint billing dimensions a single request can be charged on. Every count
 // keyed by these is non-overlapping: a prompt token is counted under exactly
 // one of `input`, `input_cache_read`, `input_cache_write`,
@@ -113,6 +116,28 @@ export interface ChatModelInfo {
   };
 }
 
+// Alias provenance attached to a `/v1/models` entry that the gateway
+// synthesized from an operator-defined alias rather than fetched from an
+// upstream catalog. `targets` carries every configured target — including
+// targets the live catalog currently can not serve — so the dashboard can
+// show the full configuration and warn about unavailable ones without a
+// second control-plane round trip.
+export interface PublicModelAliasedFrom {
+  name: string;
+  kind: AliasKind;
+  selection: AliasSelection;
+  targets: AliasTarget[];
+}
+
+// Operator-set context-window / prompt / output token limits the gateway
+// surfaces on /v1/models. Pure data — every field is optional so a
+// partially-known upstream still produces a sensible row.
+export interface PublicModelLimits {
+  max_output_tokens?: number;
+  max_context_window_tokens?: number;
+  max_prompt_tokens?: number;
+}
+
 // Public DTO served at /v1/models and /models. Single superset shape — OpenAI's
 // and Anthropic's /models field names do not overlap, so one payload satisfies
 // both client shapes.
@@ -127,14 +152,37 @@ export interface PublicModel {
   display_name: string;
   created_at?: string;
   // Non-standard extra fields below.
-  limits: {
-    max_output_tokens?: number;
-    max_context_window_tokens?: number;
-    max_prompt_tokens?: number;
-  };
+  limits: PublicModelLimits;
   kind: ModelKind;
+  // Public-facing endpoint surface. Mirrors the upstream-side ModelEndpoints
+  // verbatim — by the time a model reaches this DTO, the provider layer
+  // (e.g. provider-ollama, provider-copilot) has already projected the raw
+  // upstream catalog into the public-facing shape: the three chat endpoints
+  // (chatCompletions / messages / responses) appear together because the
+  // gateway translates between them, while `completions`, `embeddings`,
+  // `imagesGenerations`, and `imagesEdits` only appear when the upstream
+  // natively serves them. Alias entries surface the UNION of every
+  // currently-available target's endpoint map — at request time the
+  // resolver narrows the pool to targets that serve the inbound endpoint,
+  // so any endpoint advertised here is reachable through at least one
+  // target.
+  endpoints: ModelEndpoints;
   cost?: ModelPricing;
   chat?: ChatModelInfo;
+  // Present only on entries the gateway synthesized from an operator-defined
+  // alias; absent for entries that came from an upstream catalog.
+  aliasedFrom?: PublicModelAliasedFrom;
+  // Sidecar flag carried only on entries that are addressable-but-not-
+  // listed: ids the data plane accepts (via `modelPrefix.addressable`
+  // alternates or per-provider `resolveRequestedModelId` redirects) but
+  // that do NOT appear in the default `/v1/models` payload. Absent on
+  // every default-listed row and on alias rows — both are part of the
+  // public catalog. The field surfaces only on
+  // `/api/models?include_unlisted=true` rows that the dashboard's alias
+  // edit combobox shows alongside the listed catalog. Wire shape is
+  // intentionally `unlisted?: true` — boolean would add a wire byte to
+  // every listed row for no caller benefit.
+  unlisted?: true;
 }
 
 export interface PublicModelsResponse {
diff --git a/packages/protocols/src/extensions/index.ts b/packages/protocols/src/extensions/index.ts
new file mode 100644
index 000000000..5d64f0e46
--- /dev/null
+++ b/packages/protocols/src/extensions/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Closed enumeration of Floway protocol extension fields that the gateway
+ * adds to each inbound IR on top of the host protocol's own schema. The
+ * per-upstream sanitizer in the gateway reads this manifest to strip any
+ * extension residue before the upstream HTTP call.
+ */
+export const FLOWAY_EXTENSION_FIELDS = {
+  chatCompletions: ['thinking_budget', 'adaptive_thinking', 'reasoning_summary'] as const,
+  responses: ['thinking_budget', 'adaptive_thinking'] as const,
+  messages: ['verbosity'] as const,
+} as const;
diff --git a/packages/protocols/src/gemini/index.ts b/packages/protocols/src/gemini/index.ts
index 1530fd2f5..c102e3668 100644
--- a/packages/protocols/src/gemini/index.ts
+++ b/packages/protocols/src/gemini/index.ts
@@ -38,11 +38,15 @@ export interface GeminiGenerationConfig {
   responseMimeType?: string;
   responseSchema?: unknown;
   thinkingConfig?: GeminiThinkingConfig;
+  /** Floway protocol extension. Translated to OpenAI Chat `verbosity` / Responses `text.verbosity` when routed to those upstreams; dropped on Anthropic Messages and Gemini targets. */
+  verbosity?: string;
+  /** Floway protocol extension. Translated to OpenAI Chat `service_tier` / Responses `service_tier` / Anthropic `service_tier` when routed to those upstreams; dropped on Gemini targets. */
+  serviceTier?: string;
 }
 
 export interface GeminiThinkingConfig {
   thinkingBudget?: number;
-  thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high' | string;
+  thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | string;
   includeThoughts?: boolean;
 }
 
diff --git a/packages/protocols/src/index.ts b/packages/protocols/src/index.ts
index 981d4fda1..ceaa785f6 100644
--- a/packages/protocols/src/index.ts
+++ b/packages/protocols/src/index.ts
@@ -2,6 +2,7 @@ export * from './common/index.ts';
 export * from './completions/index.ts';
 export * from './chat-completions/index.ts';
 export * from './embeddings/index.ts';
+export * from './extensions/index.ts';
 export * from './gemini/index.ts';
 export * from './messages/index.ts';
 export * from './responses/index.ts';
diff --git a/packages/protocols/src/messages/index.ts b/packages/protocols/src/messages/index.ts
index bbe392170..43ed05197 100644
--- a/packages/protocols/src/messages/index.ts
+++ b/packages/protocols/src/messages/index.ts
@@ -56,6 +56,8 @@ export interface MessagesPayload {
   // protocol layer because the gateway treats `speed: 'fast'` as the canonical
   // client signal regardless of which upstream serves it.
   speed?: 'standard' | 'fast' | (string & {});
+  /** Floway protocol extension. Translated to OpenAI Chat `verbosity` / Responses `text.verbosity` when routed to those upstreams; dropped on Anthropic Messages and Gemini targets. */
+  verbosity?: string;
 }
 
 export interface MessagesSearchResultLocationCitation {
diff --git a/packages/protocols/src/responses/index.ts b/packages/protocols/src/responses/index.ts
index 0c10ec087..b16d2a25e 100644
--- a/packages/protocols/src/responses/index.ts
+++ b/packages/protocols/src/responses/index.ts
@@ -26,13 +26,21 @@ export interface ResponsesPayload {
   parallel_tool_calls?: boolean | null;
   reasoning?: {
     effort?: string;
-    summary?: 'detailed' | 'auto' | 'concise';
+    summary?: 'detailed' | 'auto' | 'concise' | (string & {});
   };
   include?: string[];
-  text?: { format?: Record<string, unknown> | null } | null;
+  // `text.verbosity` is a native GPT-5-family Responses field that controls
+  // response length; `text.format` carries structured-output schemas. Both
+  // ride on the same `text` object.
+  // Reference: https://platform.openai.com/docs/api-reference/responses/create
+  text?: { format?: Record<string, unknown> | null; verbosity?: string | null } | null;
   prompt_cache_key?: string | null;
   safety_identifier?: string | null;
   service_tier?: 'default' | 'auto' | 'flex' | 'priority' | 'scale' | (string & {}) | null;
+  /** Floway protocol extension. Translated to Anthropic `thinking.budget_tokens` / Gemini `thinkingConfig.thinkingBudget` when routed to those upstreams; dropped on OpenAI Chat/Responses targets. */
+  thinking_budget?: number;
+  /** Floway protocol extension. Translated to Anthropic `thinking.type: "adaptive"` / Gemini `thinkingConfig.thinkingBudget: -1` when routed to those upstreams; dropped on OpenAI Chat/Responses targets. */
+  adaptive_thinking?: boolean;
 }
 
 // Narrower payload for `/responses/compact`. The official endpoint accepts a
diff --git a/packages/provider-claude-code/src/provider.ts b/packages/provider-claude-code/src/provider.ts
index af4a771b7..aa5b816c7 100644
--- a/packages/provider-claude-code/src/provider.ts
+++ b/packages/provider-claude-code/src/provider.ts
@@ -107,6 +107,13 @@ export const createClaudeCodeProvider = async (record: UpstreamRecord): Promise<
     provider,
     supportsResponsesItemReference: false,
     resolveRequestedModelId: claudeCodeResolveRequestedModelId,
+    // Claude Code's redirect rule collapses any `<base>-YYYYMMDD` id to its
+    // de-dated base. The date axis is unbounded, so there is no finite
+    // enumeration to publish — the canonical de-dated id is already in the
+    // catalog, and a power-user dated form still routes through the
+    // `resolveRequestedModelId` path at request time without showing up in
+    // the addressable surface.
+    enumerateAddressableRedirects: () => [],
   };
 };
 
diff --git a/packages/provider-claude-code/src/provider_test.ts b/packages/provider-claude-code/src/provider_test.ts
index 1b35625d2..5c71a38ed 100644
--- a/packages/provider-claude-code/src/provider_test.ts
+++ b/packages/provider-claude-code/src/provider_test.ts
@@ -150,6 +150,13 @@ describe('createClaudeCodeProvider — factory surface', () => {
     expect(instance.resolveRequestedModelId?.('claude-sonnet-4-5-20250929')).toBe('claude-sonnet-4-5');
     expect(instance.resolveRequestedModelId?.('claude-sonnet-4-5')).toBeUndefined();
   });
+
+  test('enumerateAddressableRedirects returns []: the dated-id domain is unbounded so the hook intentionally publishes nothing', async () => {
+    stubModelsListFetch();
+    const instance = await createClaudeCodeProvider(currentRecord);
+    const upstreamModels = await instance.provider.getProvidedModels(noopUpstreamCallOptions().fetcher);
+    expect(instance.enumerateAddressableRedirects?.({ upstreamModels })).toEqual([]);
+  });
 });
 
 describe('createClaudeCodeProvider — callMessages routes through chain', () => {
diff --git a/packages/provider-copilot/src/provider.ts b/packages/provider-copilot/src/provider.ts
index d3d122107..f3aa2fe98 100644
--- a/packages/provider-copilot/src/provider.ts
+++ b/packages/provider-copilot/src/provider.ts
@@ -20,7 +20,7 @@ import { parseChatCompletionsStream, type ChatCompletionsPayload, type ChatCompl
 import { type ModelEndpointKey, type ModelEndpoints, type ProtocolFrame, kindForEndpoints } from '@floway-dev/protocols/common';
 import { parseAnthropicBetaHeader, parseMessagesStream, type MessagesPayload, type MessagesStreamEvent } from '@floway-dev/protocols/messages';
 import { parseResponsesStream, type ResponsesInputItem, type ResponsesPayload, type ResponsesResult } from '@floway-dev/protocols/responses';
-import { COMPACTION_TRIGGER, compactionResponse, eventResult, getProviderRepo, readUpstreamApiError, streamingProviderCall, apiErrorToResponse, defaultsForProvider, resolveEffectiveFlags, type ExecuteResult, type ModelProvider, type ModelProviderInstance, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type TelemetryModelIdentity, type UpstreamCallOptions, type UpstreamFetchOptions, type UpstreamModel, type UpstreamRecord } from '@floway-dev/provider';
+import { COMPACTION_TRIGGER, compactionResponse, eventResult, getProviderRepo, readUpstreamApiError, streamingProviderCall, apiErrorToResponse, defaultsForProvider, resolveEffectiveFlags, type AddressableRedirect, type ExecuteResult, type ModelProvider, type ModelProviderInstance, type ProviderCallResult, type ProviderResponsesResult, type ProviderStreamResult, type TelemetryModelIdentity, type UpstreamCallOptions, type UpstreamFetchOptions, type UpstreamModel, type UpstreamRecord } from '@floway-dev/provider';
 
 interface CopilotProviderData {
   rawModels: CopilotRawModel[];
@@ -457,5 +457,26 @@ export const createCopilotProvider = async (record: UpstreamRecord): Promise<Mod
     provider,
     supportsResponsesItemReference: false,
     resolveRequestedModelId: copilotRequestedModelAliasTarget,
+    // Copilot publishes every Claude variant (`-high`, `-xhigh`, `-1m`,
+    // `-fast`) as its own upstream id but collapses them under one canonical
+    // public id; the dated `claude-*-YYYYMMDD` form is also accepted and
+    // redirects to the same canonical. Walk the upstream catalog stored on
+    // `providerData.rawModels`, run each raw id through `copilotPublicModelId`,
+    // and emit the redirect whenever the canonical id differs.
+    enumerateAddressableRedirects: ({ upstreamModels }) => {
+      const out: AddressableRedirect[] = [];
+      const seen = new Set<string>();
+      for (const model of upstreamModels) {
+        const data = model.providerData as CopilotProviderData | undefined;
+        for (const raw of data?.rawModels ?? []) {
+          const publicId = copilotPublicModelId(raw.id);
+          if (publicId === raw.id) continue;
+          if (seen.has(raw.id)) continue;
+          seen.add(raw.id);
+          out.push({ addressable: raw.id, resolvesTo: publicId });
+        }
+      }
+      return out;
+    },
   };
 };
diff --git a/packages/provider-copilot/src/provider_test.ts b/packages/provider-copilot/src/provider_test.ts
index afa2d53fe..291036cca 100644
--- a/packages/provider-copilot/src/provider_test.ts
+++ b/packages/provider-copilot/src/provider_test.ts
@@ -1171,3 +1171,67 @@ test('Copilot chat field: no capabilities → no chat field', async () => {
   ]);
   assertEquals(model.chat, undefined);
 });
+
+test('enumerateAddressableRedirects emits every raw variant id whose public id differs from itself', async () => {
+  const { copilotUpstream } = await setupCopilotTest();
+  const instance = await createCopilotProvider(copilotUpstream);
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+      if (url.pathname === '/copilot_internal/v2/token') {
+        return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+      }
+      if (url.pathname === '/models') {
+        return jsonResponse(copilotModels([
+          // Base + variants. Copilot reports Claude ids with dotted version
+          // ("4.7"), but the public id rewrites them to "4-7"; every raw
+          // id therefore differs from its canonical public id and counts
+          // as an addressable redirect.
+          { id: 'claude-opus-4.7', supported_endpoints: ['/v1/messages'] },
+          { id: 'claude-opus-4.7-high', supported_endpoints: ['/v1/messages'], reasoningEfforts: ['high'] },
+          { id: 'claude-opus-4.7-xhigh', supported_endpoints: ['/v1/messages'], reasoningEfforts: ['xhigh'] },
+          // Non-claude id stays unchanged — no redirect.
+          { id: 'gpt-5.4', supported_endpoints: ['/chat/completions'] },
+        ]));
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const upstreamModels = await instance.provider.getProvidedModels(directFetcher);
+      const redirects = instance.enumerateAddressableRedirects!({ upstreamModels });
+      assertEquals(redirects, [
+        { addressable: 'claude-opus-4.7', resolvesTo: 'claude-opus-4-7' },
+        { addressable: 'claude-opus-4.7-high', resolvesTo: 'claude-opus-4-7' },
+        { addressable: 'claude-opus-4.7-xhigh', resolvesTo: 'claude-opus-4-7' },
+      ]);
+    },
+  );
+});
+
+test('enumerateAddressableRedirects returns [] when no raw variants need collapsing', async () => {
+  const { copilotUpstream } = await setupCopilotTest();
+  const instance = await createCopilotProvider(copilotUpstream);
+
+  await withMockedFetch(
+    request => {
+      const url = new URL(request.url);
+      if (url.hostname === 'update.code.visualstudio.com') return jsonResponse(['1.110.1']);
+      if (url.pathname === '/copilot_internal/v2/token') {
+        return jsonResponse({ token: 'copilot-access-token', expires_at: 4102444800, refresh_in: 3600, endpoints: { api: 'https://api.individual.githubcopilot.com' } });
+      }
+      if (url.pathname === '/models') {
+        return jsonResponse(copilotModels([
+          { id: 'gpt-5.4', supported_endpoints: ['/chat/completions'] },
+          { id: 'gpt-5.5', supported_endpoints: ['/chat/completions'] },
+        ]));
+      }
+      throw new Error(`Unhandled fetch ${request.url}`);
+    },
+    async () => {
+      const upstreamModels = await instance.provider.getProvidedModels(directFetcher);
+      assertEquals(instance.enumerateAddressableRedirects!({ upstreamModels }), []);
+    },
+  );
+});
diff --git a/packages/provider/src/index.ts b/packages/provider/src/index.ts
index fa63620d5..e1babba06 100644
--- a/packages/provider/src/index.ts
+++ b/packages/provider/src/index.ts
@@ -42,6 +42,7 @@ export type { AddressableForm, ModelPrefixConfig } from './model-prefix.ts';
 export { MODEL_PREFIX_MAX_LENGTH, MODEL_PREFIX_REGEX, normalizeModelPrefix } from './model-prefix.ts';
 
 export type {
+  AddressableRedirect,
   ModelProvider,
   ModelProviderInstance,
   ProviderCallResult,
diff --git a/packages/provider/src/provider.ts b/packages/provider/src/provider.ts
index c8d005ec4..36ad4cd23 100644
--- a/packages/provider/src/provider.ts
+++ b/packages/provider/src/provider.ts
@@ -32,6 +32,15 @@ export interface ResolvedModel extends InternalModel {
   providers: readonly ProviderModelRecord[];
 }
 
+export interface AddressableRedirect {
+  // Inbound id the provider would silently redirect through
+  // `resolveRequestedModelId` to a different real catalog id.
+  readonly addressable: string;
+  // Real catalog id the redirect resolves to. Must appear in the
+  // provider's own `getProvidedModels` output for the entry to be useful.
+  readonly resolvesTo: string;
+}
+
 export interface ModelProviderInstance {
   upstream: string;
   providerKind: UpstreamProviderKind;
@@ -45,6 +54,24 @@ export interface ModelProviderInstance {
   provider: ModelProvider;
   supportsResponsesItemReference: boolean;
   resolveRequestedModelId?(modelId: string): string | undefined;
+  // Enumerate the finite set of inbound ids this provider would accept
+  // through `resolveRequestedModelId` that are NOT already part of the
+  // public-listed catalog. Each entry pairs the addressable id with the
+  // real catalog id it resolves to. The catalog-addressable surface
+  // enumeration uses this to mark prefix-variant / collapsed-id forms as
+  // routable without forcing every consumer to walk the provider's
+  // redirect rule by hand.
+  //
+  // Implementations whose redirect domain is unbounded (e.g. arbitrary
+  // date suffixes that collapse to the same base id) return `[]` — the
+  // base id is still listed in the catalog, so the addressable surface
+  // already covers the canonical entry. The hook receives the SWR-cached
+  // upstream catalog the caller already fetched so the same upstream
+  // round-trip feeds both the listed projection and the redirect
+  // enumeration.
+  enumerateAddressableRedirects?(args: {
+    readonly upstreamModels: readonly UpstreamModel[];
+  }): readonly AddressableRedirect[];
 }
 
 export interface ProviderCallResult {
diff --git a/packages/translate/package.json b/packages/translate/package.json
index 462bf2d1c..e18d7f564 100644
--- a/packages/translate/package.json
+++ b/packages/translate/package.json
@@ -5,7 +5,8 @@
   "type": "module",
   "exports": {
     ".": { "import": "./src/index.ts", "types": "./src/index.ts" },
-    "./via-responses/responses-items": { "import": "./src/shared/via-responses/responses-items.ts", "types": "./src/shared/via-responses/responses-items.ts" }
+    "./via-responses/responses-items": { "import": "./src/shared/via-responses/responses-items.ts", "types": "./src/shared/via-responses/responses-items.ts" },
+    "./via-messages/anthropic-extensions": { "import": "./src/shared/via-messages/anthropic-extensions.ts", "types": "./src/shared/via-messages/anthropic-extensions.ts" }
   },
   "scripts": {
     "typecheck": "tsc --noEmit"
diff --git a/packages/translate/src/chat-completions-via-messages/request.ts b/packages/translate/src/chat-completions-via-messages/request.ts
index 7882788df..91118ff4a 100644
--- a/packages/translate/src/chat-completions-via-messages/request.ts
+++ b/packages/translate/src/chat-completions-via-messages/request.ts
@@ -1,5 +1,6 @@
 import { messagesThinkingBlockFromChatCompletionsScalarReasoning } from '../shared/chat-completions-and-messages/reasoning.ts';
 import { parseToolArgumentsObject } from '../shared/messages/tool-arguments.ts';
+import { buildMessagesThinkingFromExtensions } from '../shared/via-messages/anthropic-extensions.ts';
 import { applyLastMessageCacheBreakpoint, applyLastToolCacheBreakpoint } from '../shared/via-messages/cache-breakpoints.ts';
 import { fetchRemoteImage, type RemoteImageLoader, resolveImageUrlToMessagesImage } from '../shared/via-messages/remote-images.ts';
 import type { ChatCompletionsPayload, ChatCompletionsContentPart, ChatCompletionsMessage, ChatCompletionsTool } from '@floway-dev/protocols/chat-completions';
@@ -188,6 +189,14 @@ export const translateChatCompletionsToMessages = async (payload: ChatCompletion
   if (formatSchema) outputConfig.format = { type: 'json_schema', schema: formatSchema };
   const hasOutputConfig = Object.keys(outputConfig).length > 0;
 
+  // Materialize the Floway extension fields onto their Messages-natural
+  // slots.
+  const thinking = buildMessagesThinkingFromExtensions({
+    thinkingBudget: payload.thinking_budget,
+    adaptiveThinking: payload.adaptive_thinking,
+    reasoningSummary: payload.reasoning_summary,
+  });
+
   // `service_tier: 'fast'` from the Chat Completions caller maps to
   // Anthropic's `speed: 'fast'`; all other defined service_tier values
   // pass through as `service_tier` on the Messages wire.
@@ -215,6 +224,7 @@ export const translateChatCompletionsToMessages = async (payload: ChatCompletion
     ...(tools ? { tools } : {}),
     ...(payload.tool_choice != null ? { tool_choice: translateChatCompletionsToolChoice(payload.tool_choice) } : {}),
     ...(hasOutputConfig ? { output_config: outputConfig } : {}),
+    ...(thinking ? { thinking } : {}),
     ...serviceTierFields,
   };
 };
diff --git a/packages/translate/src/chat-completions-via-messages/request_test.ts b/packages/translate/src/chat-completions-via-messages/request_test.ts
index 8f1a51367..7f47b100d 100644
--- a/packages/translate/src/chat-completions-via-messages/request_test.ts
+++ b/packages/translate/src/chat-completions-via-messages/request_test.ts
@@ -1209,3 +1209,77 @@ test('translateChatCompletionsToMessages rejects an unknown user content part ty
     'does not accept video_url content parts',
   );
 });
+
+// ── Floway extension emission ──
+
+test('translateChatCompletionsToMessages emits thinking_budget extension onto thinking.{enabled, budget_tokens}', async () => {
+  const result = await translateChatCompletionsToMessages(
+    mkPayload({
+      messages: [{ role: 'user', content: 'hi' }],
+      thinking_budget: 4096,
+    }),
+  );
+
+  assertEquals(result.thinking, { type: 'enabled', budget_tokens: 4096 });
+});
+
+test('translateChatCompletionsToMessages emits adaptive_thinking extension onto thinking.{adaptive} (wins over budget)', async () => {
+  const result = await translateChatCompletionsToMessages(
+    mkPayload({
+      messages: [{ role: 'user', content: 'hi' }],
+      thinking_budget: 4096,
+      adaptive_thinking: true,
+    }),
+  );
+
+  assertEquals(result.thinking, { type: 'adaptive' });
+});
+
+test('translateChatCompletionsToMessages maps reasoning_summary onto thinking.display via concise|detailed → summarized', async () => {
+  const concise = await translateChatCompletionsToMessages(mkPayload({ messages: [{ role: 'user', content: 'hi' }], reasoning_summary: 'concise' }));
+  const detailed = await translateChatCompletionsToMessages(mkPayload({ messages: [{ role: 'user', content: 'hi' }], reasoning_summary: 'detailed' }));
+  const omitted = await translateChatCompletionsToMessages(mkPayload({ messages: [{ role: 'user', content: 'hi' }], reasoning_summary: 'omitted' }));
+  const auto = await translateChatCompletionsToMessages(mkPayload({ messages: [{ role: 'user', content: 'hi' }], reasoning_summary: 'auto' }));
+
+  assertEquals(concise.thinking, { type: 'enabled', display: 'summarized' });
+  assertEquals(detailed.thinking, { type: 'enabled', display: 'summarized' });
+  assertEquals(omitted.thinking, { type: 'enabled', display: 'omitted' });
+  // `auto` returns undefined display so Anthropic's account-default applies;
+  // with no budget/adaptive signal there is no thinking block to attach to.
+  assertEquals(auto.thinking, undefined);
+});
+
+test('translateChatCompletionsToMessages merges reasoning_summary onto budget-driven thinking block', async () => {
+  const result = await translateChatCompletionsToMessages(
+    mkPayload({
+      messages: [{ role: 'user', content: 'hi' }],
+      thinking_budget: 2048,
+      reasoning_summary: 'concise',
+    }),
+  );
+
+  assertEquals(result.thinking, { type: 'enabled', budget_tokens: 2048, display: 'summarized' });
+});
+
+test('translateChatCompletionsToMessages forwards service_tier verbatim', async () => {
+  const result = await translateChatCompletionsToMessages(
+    mkPayload({
+      messages: [{ role: 'user', content: 'hi' }],
+      service_tier: 'priority',
+    }),
+  );
+
+  assertEquals(result.service_tier, 'priority');
+});
+
+test('translateChatCompletionsToMessages does not emit Messages-protocol fields when the extension is unset', async () => {
+  const result = await translateChatCompletionsToMessages(
+    mkPayload({
+      messages: [{ role: 'user', content: 'hi' }],
+    }),
+  );
+
+  assertEquals(result.thinking, undefined);
+  assertEquals(result.speed, undefined);
+  assertEquals(result.service_tier, undefined);
+});
diff --git a/packages/translate/src/chat-completions-via-responses/request.ts b/packages/translate/src/chat-completions-via-responses/request.ts
index 6efd82c34..8d33b9e8a 100644
--- a/packages/translate/src/chat-completions-via-responses/request.ts
+++ b/packages/translate/src/chat-completions-via-responses/request.ts
@@ -112,6 +112,19 @@ export const translateChatCompletionsToResponses = (payload: ChatCompletionsPayl
 
   const responseTextConfig = payload.response_format === undefined ? undefined : payload.response_format === null ? null : { format: payload.response_format };
 
+  // `reasoning_summary` is the inbound CC extension that materializes onto
+  // the Responses-native `reasoning.summary` slot. Co-emit alongside
+  // `reasoning.effort` so a single `reasoning` object captures both knobs.
+  const reasoningEffort = payload.reasoning_effort ?? undefined;
+  const reasoningSummary = payload.reasoning_summary;
+  const reasoning =
+    reasoningEffort !== undefined || reasoningSummary !== undefined
+      ? {
+          ...(reasoningEffort !== undefined ? { effort: reasoningEffort } : {}),
+          ...(reasoningSummary !== undefined ? { summary: reasoningSummary } : {}),
+        }
+      : undefined;
+
   return {
     model: payload.model,
     input,
@@ -134,7 +147,7 @@ export const translateChatCompletionsToResponses = (payload: ChatCompletionsPayl
     // https://developers.openai.com/api/docs/guides/migrate-to-responses
     ...(payload.store !== undefined ? { store: payload.store } : {}),
     ...(payload.parallel_tool_calls !== undefined ? { parallel_tool_calls: payload.parallel_tool_calls } : {}),
-    ...(payload.reasoning_effort != null ? { reasoning: { effort: payload.reasoning_effort } } : {}),
+    ...(reasoning ? { reasoning } : {}),
     ...(responseTextConfig !== undefined ? { text: responseTextConfig } : {}),
     ...(payload.prompt_cache_key !== undefined ? { prompt_cache_key: payload.prompt_cache_key } : {}),
     ...(payload.safety_identifier !== undefined ? { safety_identifier: payload.safety_identifier } : {}),
diff --git a/packages/translate/src/chat-completions-via-responses/request_test.ts b/packages/translate/src/chat-completions-via-responses/request_test.ts
index 3c753a35c..00a78203c 100644
--- a/packages/translate/src/chat-completions-via-responses/request_test.ts
+++ b/packages/translate/src/chat-completions-via-responses/request_test.ts
@@ -431,3 +431,52 @@ test('translateChatCompletionsToResponses rejects an unknown message role', () =
     'does not accept function messages',
   );
 });
+
+// ── Floway extension emission ──
+
+test('translateChatCompletionsToResponses maps reasoning_summary onto reasoning.summary', () => {
+  const result = translateChatCompletionsToResponses({
+    model: 'gpt-test',
+    messages: [{ role: 'user', content: 'hi' }],
+    reasoning_summary: 'detailed',
+  });
+
+  assertEquals(result.reasoning, { summary: 'detailed' });
+});
+
+test('translateChatCompletionsToResponses co-emits reasoning_effort and reasoning_summary on the same reasoning object', () => {
+  const result = translateChatCompletionsToResponses({
+    model: 'gpt-test',
+    messages: [{ role: 'user', content: 'hi' }],
+    reasoning_effort: 'xhigh',
+    reasoning_summary: 'concise',
+  });
+
+  assertEquals(result.reasoning, { effort: 'xhigh', summary: 'concise' });
+});
+
+test('translateChatCompletionsToResponses leaves Messages-only extensions as inbound residue', () => {
+  const result = translateChatCompletionsToResponses({
+    model: 'gpt-test',
+    messages: [{ role: 'user', content: 'hi' }],
+    thinking_budget: 4096,
+    adaptive_thinking: true,
+  });
+
+  // Responses has no slot for any of these; the sanitizer strips the
+  // residue. Translate must not invent a target field.
+  assertEquals('thinking_budget' in result, false);
+  assertEquals('adaptive_thinking' in result, false);
+});
+
+test('translateChatCompletionsToResponses passes a fully extension-free payload through unchanged from prior behavior', () => {
+  const result = translateChatCompletionsToResponses({
+    model: 'gpt-test',
+    messages: [{ role: 'user', content: 'hi' }],
+    reasoning_effort: 'medium',
+    service_tier: 'priority',
+  });
+
+  assertEquals(result.reasoning, { effort: 'medium' });
+  assertEquals(result.service_tier, 'priority');
+});
diff --git a/packages/translate/src/gemini-via-chat-completions/request.ts b/packages/translate/src/gemini-via-chat-completions/request.ts
index 6f490dc25..07cc8bdce 100644
--- a/packages/translate/src/gemini-via-chat-completions/request.ts
+++ b/packages/translate/src/gemini-via-chat-completions/request.ts
@@ -188,6 +188,11 @@ const applyGenerationConfig = (request: ChatCompletionsPayload, generationConfig
 
   const reasoningEffort = geminiReasoningEffort(generationConfig.thinkingConfig);
   if (reasoningEffort) request.reasoning_effort = reasoningEffort;
+
+  // Extension fields landed on CC: `verbosity` flows verbatim; `serviceTier`
+  // crosses naming conventions (camelCase Gemini → snake_case OpenAI).
+  if (generationConfig.verbosity != null) request.verbosity = generationConfig.verbosity;
+  if (generationConfig.serviceTier != null) request.service_tier = generationConfig.serviceTier;
 };
 
 const buildTools = (payload: GeminiPayload): ChatCompletionsTool[] | undefined => {
diff --git a/packages/translate/src/gemini-via-chat-completions/request_test.ts b/packages/translate/src/gemini-via-chat-completions/request_test.ts
index 7b9c8403f..7fecec34c 100644
--- a/packages/translate/src/gemini-via-chat-completions/request_test.ts
+++ b/packages/translate/src/gemini-via-chat-completions/request_test.ts
@@ -477,3 +477,42 @@ test('buildTargetRequest rejects a part with no recognized content field', () =>
     'has no recognized content',
   );
 });
+
+// ── Floway extension emission ──
+
+test('buildTargetRequest emits generationConfig.verbosity onto Chat verbosity', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { verbosity: 'low' } },
+    'gpt-test',
+  );
+
+  assertEquals(result.verbosity, 'low');
+});
+
+test('buildTargetRequest emits generationConfig.serviceTier onto Chat service_tier (camelCase → snake_case)', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { serviceTier: 'priority' } },
+    'gpt-test',
+  );
+
+  assertEquals(result.service_tier, 'priority');
+});
+
+test('buildTargetRequest extends reasoning_effort enum to recognize xhigh and max', () => {
+  const xhigh = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { thinkingConfig: { thinkingLevel: 'xhigh' } } },
+    'gpt-test',
+  );
+  const max = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { thinkingConfig: { thinkingLevel: 'max' } } },
+    'gpt-test',
+  );
+  const minimal = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { thinkingConfig: { thinkingLevel: 'minimal' } } },
+    'gpt-test',
+  );
+
+  assertEquals(xhigh.reasoning_effort, 'xhigh');
+  assertEquals(max.reasoning_effort, 'max');
+  assertEquals(minimal.reasoning_effort, 'minimal');
+});
diff --git a/packages/translate/src/gemini-via-messages/request.ts b/packages/translate/src/gemini-via-messages/request.ts
index 29dd7c066..f8a0fa0c1 100644
--- a/packages/translate/src/gemini-via-messages/request.ts
+++ b/packages/translate/src/gemini-via-messages/request.ts
@@ -196,6 +196,11 @@ const applyGenerationConfig = (request: MessagesPayload, generationConfig: Gemin
     };
   }
 
+  // `serviceTier` extension flows verbatim onto the Messages-native slot;
+  // `verbosity` has no Anthropic equivalent and stays as inbound residue
+  // that the sanitizer strips after translation.
+  if (generationConfig.serviceTier != null) request.service_tier = generationConfig.serviceTier;
+
   applyThinkingConfig(request, generationConfig.thinkingConfig);
 };
 
diff --git a/packages/translate/src/gemini-via-messages/request_test.ts b/packages/translate/src/gemini-via-messages/request_test.ts
index 2bfd96510..619e739e5 100644
--- a/packages/translate/src/gemini-via-messages/request_test.ts
+++ b/packages/translate/src/gemini-via-messages/request_test.ts
@@ -405,3 +405,25 @@ test('buildTargetRequest rejects a part with no recognized content field', () =>
     'has no recognized content',
   );
 });
+
+// ── Floway extension emission ──
+
+test('buildTargetRequest emits generationConfig.serviceTier onto Messages service_tier', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { serviceTier: 'priority' } },
+    'claude-test',
+    noOptions,
+  );
+
+  assertEquals(result.service_tier, 'priority');
+});
+
+test('buildTargetRequest drops verbosity extension on Messages (no slot)', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { verbosity: 'low' } },
+    'claude-test',
+    noOptions,
+  );
+
+  assertEquals('verbosity' in result, false);
+});
diff --git a/packages/translate/src/gemini-via-responses/request.ts b/packages/translate/src/gemini-via-responses/request.ts
index 62d67c827..36ceb37f0 100644
--- a/packages/translate/src/gemini-via-responses/request.ts
+++ b/packages/translate/src/gemini-via-responses/request.ts
@@ -132,6 +132,7 @@ const applyGenerationConfig = (request: ResponsesPayload, generationConfig?: Gem
 
   if (generationConfig.responseSchema !== undefined) {
     request.text = {
+      ...request.text,
       format: {
         type: 'json_schema',
         json_schema: {
@@ -141,9 +142,15 @@ const applyGenerationConfig = (request: ResponsesPayload, generationConfig?: Gem
       },
     };
   } else if (generationConfig.responseMimeType === 'application/json') {
-    request.text = { format: { type: 'json_object' } };
+    request.text = { ...request.text, format: { type: 'json_object' } };
   }
 
+  // `verbosity` extension rides under `text` alongside the structured-output
+  // format, matching the native Responses placement.
+  if (generationConfig.verbosity != null) request.text = { ...request.text, verbosity: generationConfig.verbosity };
+
+  if (generationConfig.serviceTier != null) request.service_tier = generationConfig.serviceTier;
+
   const effort = geminiReasoningEffort(generationConfig.thinkingConfig);
   if (!effort) return;
 
diff --git a/packages/translate/src/gemini-via-responses/request_test.ts b/packages/translate/src/gemini-via-responses/request_test.ts
index e140d715c..459b8d510 100644
--- a/packages/translate/src/gemini-via-responses/request_test.ts
+++ b/packages/translate/src/gemini-via-responses/request_test.ts
@@ -411,3 +411,23 @@ test('buildTargetRequest rejects a part with no recognized content field', () =>
     'has no recognized content',
   );
 });
+
+// ── Floway extension emission ──
+
+test('buildTargetRequest emits generationConfig.verbosity onto text.verbosity', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { verbosity: 'medium' } },
+    'gpt-test',
+  );
+
+  assertEquals(result.text?.verbosity, 'medium');
+});
+
+test('buildTargetRequest emits generationConfig.serviceTier onto Responses service_tier', () => {
+  const result = buildTargetRequest(
+    { contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { serviceTier: 'priority' } },
+    'gpt-test',
+  );
+
+  assertEquals(result.service_tier, 'priority');
+});
diff --git a/packages/translate/src/messages-via-chat-completions/request.ts b/packages/translate/src/messages-via-chat-completions/request.ts
index 603dd78db..0b050af13 100644
--- a/packages/translate/src/messages-via-chat-completions/request.ts
+++ b/packages/translate/src/messages-via-chat-completions/request.ts
@@ -296,6 +296,7 @@ export const translateMessagesToChatCompletions = (payload: MessagesPayload): Ch
     tools: translateMessagesTools(clientTools),
     tool_choice: translateMessagesToolChoice(payload.tool_choice, clientTools),
     ...(responseFormat ? { response_format: responseFormat } : {}),
+    ...(payload.verbosity != null ? { verbosity: payload.verbosity } : {}),
     ...(serviceTier !== undefined ? { service_tier: serviceTier } : {}),
   };
 };
diff --git a/packages/translate/src/messages-via-chat-completions/request_test.ts b/packages/translate/src/messages-via-chat-completions/request_test.ts
index d15f43283..4cc6f81bb 100644
--- a/packages/translate/src/messages-via-chat-completions/request_test.ts
+++ b/packages/translate/src/messages-via-chat-completions/request_test.ts
@@ -481,6 +481,48 @@ test('translateMessagesToChatCompletions rejects an unknown message role', () =>
   );
 });
 
+// ── Floway extension emission ──
+
+test('translateMessagesToChatCompletions emits verbosity extension verbatim', () => {
+  const result = translateMessagesToChatCompletions({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+    verbosity: 'low',
+  });
+
+  assertEquals(result.verbosity, 'low');
+});
+
+test('translateMessagesToChatCompletions drops Anthropic-only knobs that have no Chat-completions slot', () => {
+  const result = translateMessagesToChatCompletions({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+    thinking: { type: 'enabled', budget_tokens: 4096, display: 'summarized' },
+  });
+
+  // Only the OpenAI-canonical effort axis survives; budget_tokens and display
+  // have no Chat-completions equivalent and the translate function emits
+  // nothing for them. (The sanitizer would strip anything anyway.) `speed`
+  // has its own bridge test below and is intentionally excluded here.
+  assertEquals(result.reasoning_effort, 'medium');
+  assertEquals('thinking_budget' in result, false);
+  assertEquals('reasoning_summary' in result, false);
+});
+
+test('translateMessagesToChatCompletions does not emit verbosity when the extension is unset', () => {
+  const result = translateMessagesToChatCompletions({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+  });
+
+  assertEquals('verbosity' in result, false);
+});
+
+// ── speed ↔ service_tier bridge ──
+
 test('translateMessagesToChatCompletions maps speed:fast to service_tier:fast on the outbound Chat Completions payload', () => {
   const result = translateMessagesToChatCompletions({
     model: 'gpt-test',
diff --git a/packages/translate/src/messages-via-responses/request.ts b/packages/translate/src/messages-via-responses/request.ts
index 95721088c..56aa5d7f7 100644
--- a/packages/translate/src/messages-via-responses/request.ts
+++ b/packages/translate/src/messages-via-responses/request.ts
@@ -211,7 +211,9 @@ export const translateMessagesToResponses = (payload: MessagesPayload): Response
   const clientTools = getClientTools(payload.tools);
   const instructions = translateSystemPrompt(payload.system);
   const jsonSchema = openAiJsonSchemaCoreFromMessagesFormat(payload.output_config?.format);
-  const text = jsonSchema ? { format: { type: 'json_schema' as const, ...jsonSchema } } : undefined;
+  const formatPart = jsonSchema ? { format: { type: 'json_schema' as const, ...jsonSchema } } : undefined;
+  const verbosityPart = payload.verbosity != null ? { verbosity: payload.verbosity } : undefined;
+  const text = formatPart || verbosityPart ? { ...formatPart, ...verbosityPart } : undefined;
 
   // `speed: 'fast'` maps to Responses `service_tier: 'fast'`; other non-fast
   // `speed` values have no OpenAI equivalent and are dropped. When `speed` is
diff --git a/packages/translate/src/messages-via-responses/request_test.ts b/packages/translate/src/messages-via-responses/request_test.ts
index 796b341d1..94fd4a744 100644
--- a/packages/translate/src/messages-via-responses/request_test.ts
+++ b/packages/translate/src/messages-via-responses/request_test.ts
@@ -503,6 +503,49 @@ test('translateMessagesToResponses rejects an unknown message role', () => {
   );
 });
 
+// ── Floway extension emission ──
+
+test('translateMessagesToResponses emits verbosity onto text.verbosity', () => {
+  const result = translateMessagesToResponses({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+    verbosity: 'medium',
+  });
+
+  assertEquals(result.text?.verbosity, 'medium');
+});
+
+test('translateMessagesToResponses co-emits verbosity with json_schema format under text', () => {
+  const result = translateMessagesToResponses({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+    verbosity: 'low',
+    output_config: { format: { type: 'json_schema', schema: { type: 'object', properties: {} } } },
+  });
+
+  assertEquals(result.text?.verbosity, 'low');
+  assertEquals(result.text?.format?.type, 'json_schema');
+});
+
+test('translateMessagesToResponses drops Anthropic-only mode knobs the Responses wire cannot express', () => {
+  const result = translateMessagesToResponses({
+    model: 'gpt-test',
+    max_tokens: 256,
+    messages: [{ role: 'user', content: 'hi' }],
+    thinking: { type: 'enabled', budget_tokens: 4096 },
+  });
+
+  // budget_tokens and adaptive have no Responses slot; translate emits
+  // nothing for them. The sanitizer drops residue. `speed` has its own
+  // bridge test below and is intentionally excluded here.
+  assertEquals('thinking_budget' in result, false);
+  assertEquals('adaptive_thinking' in result, false);
+});
+
+// ── speed ↔ service_tier bridge ──
+
 test('translateMessagesToResponses maps speed:fast to service_tier:fast on the outbound Responses payload', () => {
   const result = translateMessagesToResponses({
     model: 'gpt-test',
diff --git a/packages/translate/src/responses-via-chat-completions/request.ts b/packages/translate/src/responses-via-chat-completions/request.ts
index 6d0230db3..e7d23486f 100644
--- a/packages/translate/src/responses-via-chat-completions/request.ts
+++ b/packages/translate/src/responses-via-chat-completions/request.ts
@@ -242,6 +242,7 @@ export const translateResponsesToChatCompletions = (payload: ResponsesPayload):
     ...(payload.prompt_cache_key !== undefined ? { prompt_cache_key: payload.prompt_cache_key } : {}),
     ...(payload.safety_identifier !== undefined ? { safety_identifier: payload.safety_identifier } : {}),
     ...(payload.reasoning?.effort != null ? { reasoning_effort: payload.reasoning.effort } : {}),
+    ...(payload.text?.verbosity != null ? { verbosity: payload.text.verbosity } : {}),
     ...(payload.service_tier !== undefined ? { service_tier: payload.service_tier } : {}),
     // Chat Completions has no request-level counterpart for Responses
     // `reasoning`; only explicit reasoning items survive this translation.
diff --git a/packages/translate/src/responses-via-chat-completions/request_test.ts b/packages/translate/src/responses-via-chat-completions/request_test.ts
index f708f5929..c24a2544b 100644
--- a/packages/translate/src/responses-via-chat-completions/request_test.ts
+++ b/packages/translate/src/responses-via-chat-completions/request_test.ts
@@ -1455,3 +1455,50 @@ test('translateResponsesToChatCompletions maps multimodal function_call_output i
     { type: 'image_url', image_url: { url: 'data:image/png;base64,AQID', detail: 'high' } },
   ]);
 });
+
+// ── Floway extension emission ──
+
+test('translateResponsesToChatCompletions maps text.verbosity onto verbosity', () => {
+  const result = translateResponsesToChatCompletions({
+    model: 'gpt-test',
+    input: [{ type: 'message', role: 'user', content: 'hi' }],
+    text: { verbosity: 'low' },
+  });
+
+  assertEquals(result.target.verbosity, 'low');
+});
+
+test('translateResponsesToChatCompletions co-emits reasoning.effort onto reasoning_effort and service_tier verbatim', () => {
+  const result = translateResponsesToChatCompletions({
+    model: 'gpt-test',
+    input: [{ type: 'message', role: 'user', content: 'hi' }],
+    reasoning: { effort: 'xhigh' },
+    service_tier: 'priority',
+  });
+
+  assertEquals(result.target.reasoning_effort, 'xhigh');
+  assertEquals(result.target.service_tier, 'priority');
+});
+
+test('translateResponsesToChatCompletions leaves Messages-only extensions as inbound residue (CC has no slot)', () => {
+  const result = translateResponsesToChatCompletions({
+    model: 'gpt-test',
+    input: [{ type: 'message', role: 'user', content: 'hi' }],
+    thinking_budget: 4096,
+    adaptive_thinking: true,
+  });
+
+  assertEquals('thinking_budget' in result.target, false);
+  assertEquals('adaptive_thinking' in result.target, false);
+});
+
+test('translateResponsesToChatCompletions drops reasoning.summary (Chat has no slot)', () => {
+  const result = translateResponsesToChatCompletions({
+    model: 'gpt-test',
+    input: [{ type: 'message', role: 'user', content: 'hi' }],
+    reasoning: { effort: 'medium', summary: 'concise' },
+  });
+
+  assertEquals(result.target.reasoning_effort, 'medium');
+  assertEquals('reasoning_summary' in result.target, false);
+});
diff --git a/packages/translate/src/responses-via-messages/request.ts b/packages/translate/src/responses-via-messages/request.ts
index c5443f4a5..61b5edd57 100644
--- a/packages/translate/src/responses-via-messages/request.ts
+++ b/packages/translate/src/responses-via-messages/request.ts
@@ -1,6 +1,7 @@
 import { parseToolArgumentsObject } from '../shared/messages/tool-arguments.ts';
 import { responsesReasoningToMessagesUpstreamBlock } from '../shared/messages-and-responses/reasoning.ts';
 import { buildCustomToolInputSchema } from '../shared/responses-via/custom-tool-wrap.ts';
+import { buildMessagesThinkingFromExtensions } from '../shared/via-messages/anthropic-extensions.ts';
 import { applyLastMessageCacheBreakpoint, applyLastToolCacheBreakpoint, EPHEMERAL_CACHE_CONTROL } from '../shared/via-messages/cache-breakpoints.ts';
 import { fetchRemoteImage, type RemoteImageLoader, resolveImageUrlToMessagesImage } from '../shared/via-messages/remote-images.ts';
 import {
@@ -331,6 +332,18 @@ export const translateResponsesToMessages = async (payload: ResponsesPayload, op
   if (formatSchema) outputConfig.format = { type: 'json_schema', schema: formatSchema };
   const hasOutputConfig = Object.keys(outputConfig).length > 0;
 
+  // Extension-driven thinking (`thinking_budget`, `adaptive_thinking`)
+  // takes precedence over the `effort === 'none'` disable shortcut, so the
+  // alias overlay's structured thinking write survives. Native
+  // `reasoning.summary` does not surface onto Messages — the Responses IR
+  // keeps its native translation contract and rides the upstream sanitizer.
+  const extensionThinking = buildMessagesThinkingFromExtensions({
+    thinkingBudget: payload.thinking_budget,
+    adaptiveThinking: payload.adaptive_thinking,
+  });
+  const disabledThinking = effort === 'none' ? { type: 'disabled' as const } : undefined;
+  const thinking = extensionThinking ?? disabledThinking;
+
   // `service_tier: 'fast'` from the Responses caller maps to Anthropic's
   // `speed: 'fast'`; all other defined service_tier values pass through as
   // `service_tier` on the Messages wire (Anthropic accepts 'auto',
@@ -355,7 +368,7 @@ export const translateResponsesToMessages = async (payload: ResponsesPayload, op
     stream: true,
     tools,
     tool_choice: translateToolChoice(payload.tool_choice),
-    ...(effort === 'none' ? { thinking: { type: 'disabled' as const } } : {}),
+    ...(thinking ? { thinking } : {}),
     ...(hasOutputConfig ? { output_config: outputConfig } : {}),
     ...serviceTierFields,
   };
diff --git a/packages/translate/src/responses-via-messages/request_test.ts b/packages/translate/src/responses-via-messages/request_test.ts
index 3b0eff986..bcd891764 100644
--- a/packages/translate/src/responses-via-messages/request_test.ts
+++ b/packages/translate/src/responses-via-messages/request_test.ts
@@ -51,7 +51,7 @@ test('translateResponsesToMessages omits both speed and service_tier when servic
   assertFalse('service_tier' in result.target);
 });
 
-test('translateResponsesToMessages maps reasoning.effort none to thinking.disabled', async () => {
+test('translateResponsesToMessages maps reasoning.effort none to thinking.disabled (summary ignored when reasoning is disabled)', async () => {
   const result = await translateResponsesToMessages({
     model: 'claude-test',
     input: [{ type: 'message', role: 'user', content: 'hi' }],
@@ -86,7 +86,7 @@ test('translateResponsesToMessages maps reasoning.effort directly to output_conf
     stream: null,
     store: false,
     parallel_tool_calls: true,
-    reasoning: { effort: 'minimal', summary: 'detailed' },
+    reasoning: { effort: 'minimal' },
   });
 
   assertEquals(result.target.output_config, { effort: 'minimal' });
@@ -690,3 +690,21 @@ test('translateResponsesToMessages keeps payload.instructions as the Messages to
   assertEquals(result.target.messages[0], { role: 'system', content: 'mid-array note' });
   assertEquals(result.target.messages[1].role, 'user');
 });
+
+// ── Floway extension emission ──
+
+const minimalResponsesPayload = (overrides: Record<string, unknown>) => ({
+  model: 'claude-test' as const,
+  input: [{ type: 'message' as const, role: 'user' as const, content: 'hi' }],
+  ...overrides,
+});
+
+test('translateResponsesToMessages emits thinking_budget onto thinking.{enabled, budget_tokens}', async () => {
+  const result = await translateResponsesToMessages(minimalResponsesPayload({ thinking_budget: 8192 }));
+  assertEquals(result.target.thinking, { type: 'enabled', budget_tokens: 8192 });
+});
+
+test('translateResponsesToMessages emits adaptive_thinking onto thinking.{adaptive}', async () => {
+  const result = await translateResponsesToMessages(minimalResponsesPayload({ adaptive_thinking: true }));
+  assertEquals(result.target.thinking, { type: 'adaptive' });
+});
diff --git a/packages/translate/src/shared/gemini-via/gemini.ts b/packages/translate/src/shared/gemini-via/gemini.ts
index a5b4993ea..636e7f9b6 100644
--- a/packages/translate/src/shared/gemini-via/gemini.ts
+++ b/packages/translate/src/shared/gemini-via/gemini.ts
@@ -117,21 +117,31 @@ export const geminiFunctionResponsePart = (part: GeminiPart, ids: GeminiToolCall
   return { response, id: unmatched?.shift() ?? id };
 };
 
-export const geminiThinkingLevelEffort = (thinkingConfig?: GeminiThinkingConfig): 'low' | 'medium' | 'high' | undefined => {
+// Reasoning effort is freeform on the inbound IRs — the gateway never
+// enum-gates these values at the wire boundary — so the translate-side
+// mappers below return whatever Gemini surfaced for `thinkingLevel` /
+// derived from `thinkingBudget` verbatim.
+
+export const geminiThinkingLevelEffort = (thinkingConfig?: GeminiThinkingConfig): string | undefined => {
   switch (thinkingConfig?.thinkingLevel) {
   case 'minimal':
+    return 'minimal';
   case 'low':
     return 'low';
   case 'medium':
     return 'medium';
   case 'high':
     return 'high';
+  case 'xhigh':
+    return 'xhigh';
+  case 'max':
+    return 'max';
   default:
     return undefined;
   }
 };
 
-export const geminiReasoningEffort = (thinkingConfig?: GeminiThinkingConfig): 'none' | 'low' | 'medium' | 'high' | null => {
+export const geminiReasoningEffort = (thinkingConfig?: GeminiThinkingConfig): string | null => {
   if (!thinkingConfig) return null;
 
   if (thinkingConfig.thinkingBudget !== undefined) {
diff --git a/packages/translate/src/shared/via-messages/anthropic-extensions.ts b/packages/translate/src/shared/via-messages/anthropic-extensions.ts
new file mode 100644
index 000000000..1f1bc153f
--- /dev/null
+++ b/packages/translate/src/shared/via-messages/anthropic-extensions.ts
@@ -0,0 +1,54 @@
+import type { MessagesPayload, MessagesThinkingDisplay } from '@floway-dev/protocols/messages';
+
+// Build a Messages `thinking` block from the Floway extension fields a
+// non-Messages inbound carries (`thinking_budget`, `adaptive_thinking`,
+// `reasoning_summary`). The alias write-side validator enforces single-facet
+// selection, so `adaptive_thinking` and `thinking_budget` should not co-occur;
+// when both still arrive the adaptive choice wins.
+//
+// The summary mapping collapses the OpenAI-style {auto|concise|detailed|
+// omitted} vocabulary onto Anthropic's structured `thinking.display`
+// enumeration: concise + detailed both surface a redacted summary, so they
+// collapse to `summarized`; `omitted` is the canonical hide-everything
+// spelling; `auto` returns undefined so Anthropic's account default takes
+// over. Operator-typed values that match neither vocabulary pass through
+// verbatim — Anthropic rejects unknown values at the wire, which is the
+// explicit-failure path.
+//
+// `reasoningSummary` synthesizes `thinking.{type:'enabled', display}` when
+// the inbound carries summary but no budget/adaptive signal — without an
+// explicit thinking mode Anthropic would otherwise discard the display
+// field.
+export const buildMessagesThinkingFromExtensions = (input: {
+  thinkingBudget?: number;
+  adaptiveThinking?: boolean;
+  reasoningSummary?: string;
+}): MessagesPayload['thinking'] | undefined => {
+  const display = input.reasoningSummary !== undefined ? mapSummary(input.reasoningSummary) : undefined;
+  const displayPart = display !== undefined ? { display: display as MessagesThinkingDisplay } : {};
+
+  if (input.adaptiveThinking === true) {
+    return { type: 'adaptive', ...displayPart };
+  }
+  if (input.thinkingBudget !== undefined) {
+    return { type: 'enabled', budget_tokens: input.thinkingBudget, ...displayPart };
+  }
+  if (input.reasoningSummary !== undefined && display !== undefined) {
+    return { type: 'enabled', ...displayPart };
+  }
+  return undefined;
+};
+
+const mapSummary = (summary: string): MessagesThinkingDisplay | string | undefined => {
+  switch (summary) {
+  case 'concise':
+  case 'detailed':
+    return 'summarized';
+  case 'omitted':
+    return 'omitted';
+  case 'auto':
+    return undefined;
+  default:
+    return summary;
+  }
+};
diff --git a/packages/ui/src/Combobox.vue b/packages/ui/src/Combobox.vue
new file mode 100644
index 000000000..9b06058bc
--- /dev/null
+++ b/packages/ui/src/Combobox.vue
@@ -0,0 +1,200 @@
+<script setup lang="ts">
+// Single-select combobox with free-form input. The operator can type a value
+// the suggestion list does not contain and the typed string becomes the
+// model value verbatim — useful for fields the gateway forwards verbatim and
+// does not enum-gate.
+//
+// Visual contract matches Select.vue / TagCombobox.vue (dark popover,
+// surface-700 trigger). HTML5 `<input list>` + `<datalist>` would have
+// been one line but the browser-rendered popover is white-on-dark-only
+// on every major browser, which is jarring inside the dashboard's dark
+// theme.
+import {
+  ComboboxAnchor, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput,
+  ComboboxItem, ComboboxItemIndicator, ComboboxPortal, ComboboxRoot, ComboboxTrigger,
+  ComboboxViewport, useFilter,
+} from 'reka-ui';
+import { computed, nextTick, ref, watch } from 'vue';
+
+interface Item {
+  value: string;
+  label?: string;
+}
+
+// Post-normalize shape: `label` is always set (defaults to `value`), so the
+// template can read `item.label` directly instead of falling back per row.
+interface NormalizedItem {
+  value: string;
+  label: string;
+}
+
+const value = defineModel<string>({ required: true });
+
+const props = withDefaults(defineProps<{
+  /** Suggestion list. Each item's `value` is what gets committed; `label` is the visible row text. */
+  items: readonly (string | Item)[];
+  placeholder?: string;
+  disabled?: boolean;
+  inputmode?: 'text' | 'numeric' | 'decimal';
+  /** Tailwind classes applied to the trigger input (e.g. `font-mono`). */
+  inputClass?: string;
+  /** Override the default "no matches" copy shown when the typed value already matches nothing. */
+  emptyText?: string;
+  /**
+   * Drop the bordered surface-700 shell so the input blends into its parent
+   * row. Used when the combobox is embedded in an already-bordered container
+   * (e.g. a Card row title) where a second border would double up.
+   */
+  borderless?: boolean;
+  /**
+   * Hide the right-edge chevron that toggles the dropdown. The popover still
+   * opens on focus / click because the input itself owns `open-on-focus`;
+   * removing the chevron keeps the title visually clean when the parent row
+   * already carries its own action cluster on the right.
+   */
+  hideDropdownTrigger?: boolean;
+}>(), {
+  emptyText: 'No matches',
+});
+
+const { contains } = useFilter({ sensitivity: 'base' });
+
+// Normalize the items list to a single shape so the template only deals
+// with `{ value, label }`. Strings collapse to `{ value: s, label: s }`.
+const normalizedItems = computed<NormalizedItem[]>(() => props.items.map(it =>
+  typeof it === 'string' ? { value: it, label: it } : { value: it.value, label: it.label ?? it.value }));
+
+// query mirrors value so the input always shows the committed string. Reka's
+// ComboboxInput owns the typed text via its own v-model; we keep them in
+// sync so an outside change to the model (form reset, prefill) updates the
+// visible text too.
+const query = ref(value.value);
+watch(value, v => { if (v !== query.value) query.value = v; });
+
+// Single writer: every keystroke pushes the raw query into `value` so the
+// save gate of any consuming dialog reflects what the operator typed
+// without waiting for blur. Trimming is the caller's job — doing it here
+// would clip a trailing space mid-keystroke and force the operator to
+// re-press space to keep typing. ComboboxRoot's own onChange path still
+// fires for clicked rows and just re-writes the same value via this
+// watch.
+watch(query, q => { value.value = q; });
+
+// Always show every suggestion; rank items whose label or value contains the
+// typed query above the rest, preserving the original order within each
+// group. Empty query keeps the configured order untouched. The operator
+// always sees the full set of presets — typing narrows attention to the
+// top of the list without hiding the alternatives.
+const orderedItems = computed<NormalizedItem[]>(() => {
+  if (query.value === '') return normalizedItems.value;
+  const matches: NormalizedItem[] = [];
+  const rest: NormalizedItem[] = [];
+  for (const item of normalizedItems.value) {
+    if (contains(item.label, query.value) || contains(item.value, query.value)) {
+      matches.push(item);
+    } else {
+      rest.push(item);
+    }
+  }
+  return [...matches, ...rest];
+});
+
+const trimmedQuery = computed(() => query.value.trim());
+const hasExactMatch = computed(() => normalizedItems.value.some(item => item.value === trimmedQuery.value));
+const showCreateOption = computed(() => trimmedQuery.value !== '' && !hasExactMatch.value);
+
+const open = ref(false);
+
+// Reka's Combobox only registers items present in the DOM. When the operator
+// types a brand-new value, surface a synthesized "Use 'foo'" row so the
+// arrow keys + Enter path still commits it. The `watch(query)` above is
+// the sole writer to `value`; this handler just closes the popover after
+// the operator confirms.
+const commitTyped = async () => {
+  open.value = false;
+  await nextTick();
+};
+</script>
+
+<template>
+  <ComboboxRoot
+    v-model="value"
+    v-model:open="open"
+    :disabled="disabled"
+    :display-value="(v: string) => v"
+    open-on-focus
+  >
+    <ComboboxAnchor as-child>
+      <div class="relative w-full">
+        <ComboboxInput
+          v-model="query"
+          :placeholder="placeholder"
+          :disabled="disabled"
+          :inputmode="inputmode"
+          :class="[
+            borderless
+              ? 'h-9 w-full bg-transparent text-sm text-white border-0 focus:outline-none focus:ring-0 placeholder:text-gray-600'
+              : [
+                'h-9 w-full rounded-[10px] border border-white/[0.14] bg-surface-700 pl-3 text-sm text-white',
+                'transition-colors hover:border-white/25',
+                'focus:outline-none focus:border-accent-cyan/50 focus:ring-1 focus:ring-accent-cyan/30',
+                'placeholder:text-gray-600',
+              ],
+            !borderless && (hideDropdownTrigger ? 'pr-3' : 'pr-9'),
+            borderless && 'px-0',
+            'disabled:opacity-50 disabled:cursor-not-allowed',
+            inputClass,
+          ]"
+        />
+        <ComboboxTrigger
+          v-if="!hideDropdownTrigger"
+          class="absolute inset-y-0 right-0 grid w-9 place-items-center text-gray-400 hover:text-gray-200"
+          tabindex="-1"
+        >
+          <i class="i-lucide-chevrons-up-down size-3.5" />
+        </ComboboxTrigger>
+      </div>
+    </ComboboxAnchor>
+
+    <ComboboxPortal>
+      <ComboboxContent
+        position="popper"
+        :side-offset="4"
+        class="z-50 max-h-72 w-[--reka-combobox-trigger-width] overflow-hidden rounded-[10px] border border-white/[0.06] bg-surface-800 text-white shadow-xl"
+      >
+        <ComboboxViewport class="p-1">
+          <ComboboxEmpty v-if="orderedItems.length === 0 && !showCreateOption" class="px-2 py-1.5 text-xs text-gray-500">
+            {{ emptyText }}
+          </ComboboxEmpty>
+          <ComboboxGroup>
+            <ComboboxItem
+              v-if="showCreateOption"
+              :value="trimmedQuery"
+              class="relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-7 pr-2 text-sm text-accent-cyan outline-none data-[highlighted]:bg-accent-cyan/10"
+              @select="commitTyped"
+            >
+              <span class="absolute left-2 flex size-3.5 items-center justify-center">
+                <i class="i-lucide-plus size-3.5" />
+              </span>
+              <span class="truncate">Use "<span class="font-mono">{{ trimmedQuery }}</span>"</span>
+            </ComboboxItem>
+            <ComboboxItem
+              v-for="item in orderedItems"
+              :key="item.value"
+              :value="item.value"
+              class="relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-7 pr-2 text-sm text-white outline-none data-[highlighted]:bg-accent-cyan/10 data-[highlighted]:text-accent-cyan"
+            >
+              <span class="absolute left-2 flex size-3.5 items-center justify-center">
+                <ComboboxItemIndicator>
+                  <i class="i-lucide-check size-3.5 text-accent-cyan" />
+                </ComboboxItemIndicator>
+              </span>
+              <span class="truncate">{{ item.label }}</span>
+              <span v-if="item.label !== item.value" class="ml-auto pl-3 font-mono text-xs text-gray-500">{{ item.value }}</span>
+            </ComboboxItem>
+          </ComboboxGroup>
+        </ComboboxViewport>
+      </ComboboxContent>
+    </ComboboxPortal>
+  </ComboboxRoot>
+</template>
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index afb922da4..4f9afa695 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -3,6 +3,7 @@ export { default as Button } from './Button.vue';
 export { default as Card } from './Card.vue';
 export { default as Checkbox } from './Checkbox.vue';
 export { default as Code } from './Code.vue';
+export { default as Combobox } from './Combobox.vue';
 export { default as Dialog } from './Dialog.vue';
 export { default as Input } from './Input.vue';
 export { default as NumberField } from './NumberField.vue';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bf3ef7f58..e1273e234 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -223,6 +223,9 @@ importers:
       '@vitejs/plugin-vue':
         specifier: ^6.0.1
         version: 6.0.7(vite@7.3.1(@types/node@22.19.19)(jiti@2.6.1)(tsx@4.22.4)(yaml@2.9.0))(vue@3.5.34(typescript@5.9.3))
+      '@vue/test-utils':
+        specifier: ^2.4.11
+        version: 2.4.11(@vue/compiler-dom@3.5.34)(@vue/server-renderer@3.5.34(vue@3.5.34(typescript@5.9.3)))(vue@3.5.34(typescript@5.9.3))
       happy-dom:
         specifier: ^20.0.0
         version: 20.10.6
@@ -1278,6 +1281,10 @@ packages:
   '@internationalized/number@3.6.6':
     resolution: {integrity: sha512-iFgmQaXHE0vytNfpLZWOC2mEJCBRzcUxt53Xf/yCXG93lRvqas237i3r7X4RKMwO3txiyZD4mQjKAByFv6UGSQ==}
 
+  '@isaacs/cliui@8.0.2':
+    resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
+    engines: {node: '>=12'}
+
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
@@ -1330,6 +1337,9 @@ packages:
     resolution: {integrity: sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg==}
     engines: {node: '>= 20.19.0'}
 
+  '@one-ini/wasm@0.1.1':
+    resolution: {integrity: sha512-XuySG1E38YScSJoMlqovLru4KTUNSjgVTIjyh7qMX6aNN5HY5Ct5LhRJdxO79JtTzKfzV/bnWpz+zquYrISsvw==}
+
   '@oxc-parser/binding-android-arm-eabi@0.131.0':
     resolution: {integrity: sha512-t2xicr9pfzkSRYx5aPqZqlLaayIwJTqgQ81Jor31Xep2nGyL2Aq3d0K5wOfeR7VevaSdxaS9dzSQP9xDwn8fDg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1489,6 +1499,10 @@ packages:
     resolution: {integrity: sha512-C2Xj8FZ0uHWeCXXqX5B4/gVFQmtSkiuOolzAgutjTfseNOHT3pUjljDZsTSxXFGgio54bCzVFqmEOUrIVk8RDA==}
     engines: {node: '>=20.0.0'}
 
+  '@pkgjs/parseargs@0.11.0':
+    resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
+    engines: {node: '>=14'}
+
   '@polka/url@1.0.0-next.29':
     resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==}
 
@@ -2064,6 +2078,16 @@ packages:
   '@vue/shared@3.5.34':
     resolution: {integrity: sha512-24uqU4OIiX29ryC3MeWid/Xf2fa2EFRUVLb77nRhk+UrTVrh/XiGtFAFmJBAtBRbjwNdsPRP+jj/OL27Eg1NDA==}
 
+  '@vue/test-utils@2.4.11':
+    resolution: {integrity: sha512-GDqaqZsA6m2E5vNzej0aYiIb6BX8xV9pNSbbbXKOfEYwg7ZNblVX8suyqmUBThq8VIrgAJNxn+z72hVtUeiWHA==}
+    peerDependencies:
+      '@vue/compiler-dom': 3.x
+      '@vue/server-renderer': 3.x
+      vue: 3.x
+    peerDependenciesMeta:
+      '@vue/server-renderer':
+        optional: true
+
   '@vueuse/core@14.3.0':
     resolution: {integrity: sha512-aHfz47g0ZhMtTVHmIzMVpJy8ePhhOy68GY5bv110+5DVtZ+W7BsOx+m61UNQqfrWyPztIHIanWa3E2tib3NFIw==}
     peerDependencies:
@@ -2119,6 +2143,10 @@ packages:
     peerDependencies:
       vue: ^3.5.0
 
+  abbrev@2.0.0:
+    resolution: {integrity: sha512-6/mh1E2u2YgEsCHdY0Yx5oW+61gZU+1vXaoiHHrpKeuRNNgFvS+/jrwHiQhB5apAf5oB7UB7E19ol2R2LKH8hQ==}
+    engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0}
+
   acorn-jsx@5.3.2:
     resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
     peerDependencies:
@@ -2142,10 +2170,18 @@ packages:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
 
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
   ansi-styles@4.3.0:
     resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
     engines: {node: '>=8'}
 
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
   argparse@2.0.1:
     resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
 
@@ -2295,6 +2331,10 @@ packages:
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
+  commander@10.0.1:
+    resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==}
+    engines: {node: '>=14'}
+
   concat-map@0.0.1:
     resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
 
@@ -2309,6 +2349,9 @@ packages:
   confbox@0.2.4:
     resolution: {integrity: sha512-ysOGlgTFbN2/Y6Cg3Iye8YKulHw+R2fNXHrgSmXISQdMnomY6eNDprVdW9R5xBguEqI954+S6709UyiO7B+6OQ==}
 
+  config-chain@1.1.13:
+    resolution: {integrity: sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==}
+
   consola@3.4.2:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
@@ -2414,9 +2457,20 @@ packages:
   duplexer@0.1.2:
     resolution: {integrity: sha512-jtD6YG370ZCIi/9GTaJKQxWTZD045+4R4hTk/x1UyoqadyJ9x9CgSi1RlVDQF8U2sxLLSnFkCaMihqljHIWgMg==}
 
+  eastasianwidth@0.2.0:
+    resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
+
+  editorconfig@1.0.7:
+    resolution: {integrity: sha512-e0GOtq/aTQhVdNyDU9e02+wz9oDDM+SIOQxWME2QRjzRX5yyLAuHDE+0aE8vHb9XRC8XD37eO2u57+F09JqFhw==}
+    engines: {node: '>=14'}
+    hasBin: true
+
   emoji-regex@8.0.0:
     resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
 
+  emoji-regex@9.2.2:
+    resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
+
   entities@7.0.1:
     resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
     engines: {node: '>=0.12'}
@@ -2635,6 +2689,10 @@ packages:
     resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
     engines: {node: '>= 0.4'}
 
+  foreground-child@3.3.1:
+    resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
+    engines: {node: '>=14'}
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -2677,6 +2735,11 @@ packages:
     resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
     engines: {node: '>=10.13.0'}
 
+  glob@10.5.0:
+    resolution: {integrity: sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    hasBin: true
+
   globals@14.0.0:
     resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
     engines: {node: '>=18'}
@@ -2767,6 +2830,9 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
+  ini@1.3.8:
+    resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
+
   internal-slot@1.1.0:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
@@ -2887,10 +2953,21 @@ packages:
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
+  jackspeak@3.4.3:
+    resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
+
   jiti@2.6.1:
     resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
+  js-beautify@1.15.4:
+    resolution: {integrity: sha512-9/KXeZUKKJwqCXUdBxFJ3vPh467OCckSBmYDwSK/EtV090K+iMJ7zx2S3HLVDIWFQdqMIsZWbnaGiba18aWhaA==}
+    engines: {node: '>=14'}
+    hasBin: true
+
+  js-cookie@3.0.8:
+    resolution: {integrity: sha512-yeJd4aNAdYZQjaon2bpD/Gb0B/omw7HQOsynXXcOiWVCacbBcPlgn8S/d1X6blFSaHao7ozqtW7NZW19xpCtIw==}
+
   js-yaml@4.1.1:
     resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
     hasBin: true
@@ -2947,6 +3024,9 @@ packages:
   lodash.merge@4.6.2:
     resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
 
+  lru-cache@10.4.3:
+    resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
+
   magic-regexp@0.10.0:
     resolution: {integrity: sha512-Uly1Bu4lO1hwHUW0CQeSWuRtzCMNO00CmXtS8N6fyvB3B979GOEEeAkiTUDsmbYLAbvpUS/Kt5c4ibosAzVyVg==}
 
@@ -2982,6 +3062,10 @@ packages:
   minimist@1.2.8:
     resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
 
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -3018,6 +3102,11 @@ packages:
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
+  nopt@7.2.1:
+    resolution: {integrity: sha512-taM24ViiimT/XntxbPyJQzCG+p4EKOpgD3mxFwW38mGjVUrfERQOeY4EDHjdnptttfHuHQXFx+lTP08Q+mLa/w==}
+    engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0}
+    hasBin: true
+
   nprogress@0.2.0:
     resolution: {integrity: sha512-I19aIingLgR1fmhftnbWWO3dXc0hSxqHQHQb3H8m+K3TnEn/iSeTZZOyvKXWqQESMwuUVnatlCnZdLBZZt2VSA==}
 
@@ -3089,6 +3178,9 @@ packages:
     resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
     engines: {node: '>=10'}
 
+  package-json-from-dist@1.0.1:
+    resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
+
   package-manager-detector@1.6.0:
     resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
@@ -3110,6 +3202,10 @@ packages:
   path-parse@1.0.7:
     resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==}
 
+  path-scurry@1.11.1:
+    resolution: {integrity: sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==}
+    engines: {node: '>=16 || 14 >=14.18'}
+
   path-to-regexp@6.3.0:
     resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==}
 
@@ -3164,6 +3260,9 @@ packages:
     resolution: {integrity: sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==}
     engines: {node: '>=6'}
 
+  proto-list@1.2.4:
+    resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==}
+
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
@@ -3311,6 +3410,10 @@ packages:
   siginfo@2.0.0:
     resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
 
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
   simple-swizzle@0.2.4:
     resolution: {integrity: sha512-nAu1WFPQSMNr2Zn9PGSZK9AGn4t/y97lEm+MXTtUDwfP0ksAIX4nO+6ruD9Jwut4C49SB1Ws+fbXsm/yScWOHw==}
 
@@ -3350,6 +3453,10 @@ packages:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
 
+  string-width@5.1.2:
+    resolution: {integrity: sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==}
+    engines: {node: '>=12'}
+
   string.prototype.trim@1.2.10:
     resolution: {integrity: sha512-Rs66F0P/1kedk5lyYyH9uBzuiI/kNRmwJAR9quK6VOtIpZ2G+hMZd+HQbbv25MgCA6gEffoMZYxlTod4WcdrKA==}
     engines: {node: '>= 0.4'}
@@ -3366,6 +3473,10 @@ packages:
     resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
     engines: {node: '>=8'}
 
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
   strip-bom@3.0.0:
     resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
     engines: {node: '>=4'}
@@ -3623,6 +3734,9 @@ packages:
   vscode-uri@3.1.0:
     resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
 
+  vue-component-type-helpers@3.3.5:
+    resolution: {integrity: sha512-Fe1jyPJoUGpJOYKOri44jduR7My4yYINOMJISuMAbmrs+L5LbIDUc8NTWZYY3EJLK0yPLuCmcd5zoCsE4k2/KA==}
+
   vue-demi@0.14.10:
     resolution: {integrity: sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==}
     engines: {node: '>=12'}
@@ -3715,6 +3829,10 @@ packages:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
 
+  wrap-ansi@8.1.0:
+    resolution: {integrity: sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==}
+    engines: {node: '>=12'}
+
   ws@8.18.0:
     resolution: {integrity: sha512-8VbfWfHLbbwu3+N6OKsOMpBdT4kXPDDB9cJk2bJ6mh9ucxdlnNvH1e+roYkKmN9Nxw2yjz7VzeO9oOz2zJ04Pw==}
     engines: {node: '>=10.0.0'}
@@ -4295,6 +4413,15 @@ snapshots:
     dependencies:
       '@swc/helpers': 0.5.21
 
+  '@isaacs/cliui@8.0.2':
+    dependencies:
+      string-width: 5.1.2
+      string-width-cjs: string-width@4.2.3
+      strip-ansi: 7.2.0
+      strip-ansi-cjs: strip-ansi@6.0.1
+      wrap-ansi: 8.1.0
+      wrap-ansi-cjs: wrap-ansi@7.0.0
+
   '@jridgewell/gen-mapping@0.3.13':
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -4342,6 +4469,8 @@ snapshots:
 
   '@noble/hashes@2.2.0': {}
 
+  '@one-ini/wasm@0.1.1': {}
+
   '@oxc-parser/binding-android-arm-eabi@0.131.0':
     optional: true
 
@@ -4502,6 +4631,9 @@ snapshots:
       tslib: 2.8.1
       tsyringe: 4.10.0
 
+  '@pkgjs/parseargs@0.11.0':
+    optional: true
+
   '@polka/url@1.0.0-next.29': {}
 
   '@poppinss/colors@4.1.6':
@@ -5144,6 +5276,15 @@ snapshots:
 
   '@vue/shared@3.5.34': {}
 
+  '@vue/test-utils@2.4.11(@vue/compiler-dom@3.5.34)(@vue/server-renderer@3.5.34(vue@3.5.34(typescript@5.9.3)))(vue@3.5.34(typescript@5.9.3))':
+    dependencies:
+      '@vue/compiler-dom': 3.5.34
+      js-beautify: 1.15.4
+      vue: 3.5.34(typescript@5.9.3)
+      vue-component-type-helpers: 3.3.5
+    optionalDependencies:
+      '@vue/server-renderer': 3.5.34(vue@3.5.34(typescript@5.9.3))
+
   '@vueuse/core@14.3.0(vue@3.5.34(typescript@5.9.3))':
     dependencies:
       '@types/web-bluetooth': 0.0.21
@@ -5166,6 +5307,8 @@ snapshots:
     dependencies:
       vue: 3.5.34(typescript@5.9.3)
 
+  abbrev@2.0.0: {}
+
   acorn-jsx@5.3.2(acorn@8.16.0):
     dependencies:
       acorn: 8.16.0
@@ -5185,10 +5328,14 @@ snapshots:
 
   ansi-regex@5.0.1: {}
 
+  ansi-regex@6.2.2: {}
+
   ansi-styles@4.3.0:
     dependencies:
       color-convert: 2.0.1
 
+  ansi-styles@6.2.3: {}
+
   argparse@2.0.1: {}
 
   aria-hidden@1.2.6:
@@ -5361,6 +5508,8 @@ snapshots:
 
   colorette@2.0.20: {}
 
+  commander@10.0.1: {}
+
   concat-map@0.0.1: {}
 
   concurrently@9.2.1:
@@ -5376,6 +5525,11 @@ snapshots:
 
   confbox@0.2.4: {}
 
+  config-chain@1.1.13:
+    dependencies:
+      ini: 1.3.8
+      proto-list: 1.2.4
+
   consola@3.4.2: {}
 
   cookie@1.1.1: {}
@@ -5468,8 +5622,19 @@ snapshots:
 
   duplexer@0.1.2: {}
 
+  eastasianwidth@0.2.0: {}
+
+  editorconfig@1.0.7:
+    dependencies:
+      '@one-ini/wasm': 0.1.1
+      commander: 10.0.1
+      minimatch: 9.0.9
+      semver: 7.7.4
+
   emoji-regex@8.0.0: {}
 
+  emoji-regex@9.2.2: {}
+
   entities@7.0.1: {}
 
   error-stack-parser-es@1.0.5: {}
@@ -5812,6 +5977,11 @@ snapshots:
     dependencies:
       is-callable: 1.2.7
 
+  foreground-child@3.3.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      signal-exit: 4.1.0
+
   fsevents@2.3.3:
     optional: true
 
@@ -5864,6 +6034,15 @@ snapshots:
     dependencies:
       is-glob: 4.0.3
 
+  glob@10.5.0:
+    dependencies:
+      foreground-child: 3.3.1
+      jackspeak: 3.4.3
+      minimatch: 9.0.9
+      minipass: 7.1.3
+      package-json-from-dist: 1.0.1
+      path-scurry: 1.11.1
+
   globals@14.0.0: {}
 
   globalthis@1.0.4:
@@ -5937,6 +6116,8 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
+  ini@1.3.8: {}
+
   internal-slot@1.1.0:
     dependencies:
       es-errors: 1.3.0
@@ -6063,8 +6244,24 @@ snapshots:
 
   isexe@2.0.0: {}
 
+  jackspeak@3.4.3:
+    dependencies:
+      '@isaacs/cliui': 8.0.2
+    optionalDependencies:
+      '@pkgjs/parseargs': 0.11.0
+
   jiti@2.6.1: {}
 
+  js-beautify@1.15.4:
+    dependencies:
+      config-chain: 1.1.13
+      editorconfig: 1.0.7
+      glob: 10.5.0
+      js-cookie: 3.0.8
+      nopt: 7.2.1
+
+  js-cookie@3.0.8: {}
+
   js-yaml@4.1.1:
     dependencies:
       argparse: 2.0.1
@@ -6110,6 +6307,8 @@ snapshots:
 
   lodash.merge@4.6.2: {}
 
+  lru-cache@10.4.3: {}
+
   magic-regexp@0.10.0:
     dependencies:
       estree-walker: 3.0.3
@@ -6158,6 +6357,8 @@ snapshots:
 
   minimist@1.2.8: {}
 
+  minipass@7.1.3: {}
+
   mitt@3.0.1: {}
 
   mlly@1.8.2:
@@ -6188,6 +6389,10 @@ snapshots:
 
   node-fetch-native@1.6.7: {}
 
+  nopt@7.2.1:
+    dependencies:
+      abbrev: 2.0.0
+
   nprogress@0.2.0: {}
 
   nth-check@2.1.1:
@@ -6299,6 +6504,8 @@ snapshots:
     dependencies:
       p-limit: 3.1.0
 
+  package-json-from-dist@1.0.1: {}
+
   package-manager-detector@1.6.0: {}
 
   parent-module@1.0.1:
@@ -6313,6 +6520,11 @@ snapshots:
 
   path-parse@1.0.7: {}
 
+  path-scurry@1.11.1:
+    dependencies:
+      lru-cache: 10.4.3
+      minipass: 7.1.3
+
   path-to-regexp@6.3.0: {}
 
   pathe@2.0.3: {}
@@ -6361,6 +6573,8 @@ snapshots:
 
   prismjs@1.30.0: {}
 
+  proto-list@1.2.4: {}
+
   punycode@2.3.1: {}
 
   pvtsutils@1.3.6:
@@ -6611,6 +6825,8 @@ snapshots:
 
   siginfo@2.0.0: {}
 
+  signal-exit@4.1.0: {}
+
   simple-swizzle@0.2.4:
     dependencies:
       is-arrayish: 0.3.4
@@ -6646,6 +6862,12 @@ snapshots:
       is-fullwidth-code-point: 3.0.0
       strip-ansi: 6.0.1
 
+  string-width@5.1.2:
+    dependencies:
+      eastasianwidth: 0.2.0
+      emoji-regex: 9.2.2
+      strip-ansi: 7.2.0
+
   string.prototype.trim@1.2.10:
     dependencies:
       call-bind: 1.0.9
@@ -6673,6 +6895,10 @@ snapshots:
     dependencies:
       ansi-regex: 5.0.1
 
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
   strip-bom@3.0.0: {}
 
   strip-json-comments@3.1.1: {}
@@ -6959,6 +7185,8 @@ snapshots:
 
   vscode-uri@3.1.0: {}
 
+  vue-component-type-helpers@3.3.5: {}
+
   vue-demi@0.14.10(vue@3.5.34(typescript@5.9.3)):
     dependencies:
       vue: 3.5.34(typescript@5.9.3)
@@ -7083,6 +7311,12 @@ snapshots:
       string-width: 4.2.3
       strip-ansi: 6.0.1
 
+  wrap-ansi@8.1.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 5.1.2
+      strip-ansi: 7.2.0
+
   ws@8.18.0: {}
 
   ws@8.21.0: {}