From 5cde5f0685873d63d897299febe6f7c2b66a970f Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Thu, 13 Aug 2026 16:00:38 +0800
Subject: [PATCH 1/7] feat(extension): add Twitter setup wizard UI

---
 .../extension/extensionCard/extensionCard.md  |   2 +
 .../extensionCard/extensionCard.spec.ts       |  90 ++++
 .../extension/extensionCard/extensionCard.vue |  39 +-
 apps/client-web/src/locales/messages/en.json  |   2 +
 .../src/locales/messages/zh-CN.json           |   2 +
 apps/client-web/src/twitterSetupAPI.spec.ts   |  66 +++
 .../client-web/src/twitterSetupWizard.spec.ts |  72 ++++
 extensions/AGENTS.md                          |   2 +
 extensions/twitter/package.json               |   4 +-
 .../twitterSetupWizard/twitterSetupWizard.md  |   9 +
 .../twitterSetupWizard.scss                   | 119 +++++
 .../twitterSetupWizard/twitterSetupWizard.ts  |  10 +
 .../twitterSetupWizard/twitterSetupWizard.vue | 407 ++++++++++++++++++
 extensions/twitter/src/index.ts               |   2 +
 extensions/twitter/src/setup-api.ts           | 167 +++++++
 packages/core/AGENTS.md                       |   2 +
 packages/core/package.json                    |   2 +-
 packages/core/src/client/client.test.ts       |  53 +++
 packages/core/src/client/client.ts            |  27 +-
 .../core/src/database/database.generated.ts   |   4 +
 .../database/runtime-contract.generated.json  |  12 +-
 .../src/database/runtime-contract.test.ts     |   2 +-
 packages/core/src/extension/host.test.ts      |  15 +
 packages/core/src/extension/host.ts           |  12 +
 packages/core/src/extension/index.ts          |   1 +
 packages/core/src/extension/model.ts          |   7 +
 packages/core/src/index.ts                    |   1 +
 scripts/core-release-lib.mjs                  |   3 +-
 scripts/core-release-lib.test.mjs             |  23 +
 scripts/twitter-mf-distribution.test.mjs      |  26 +-
 30 files changed, 1152 insertions(+), 31 deletions(-)
 create mode 100644 apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
 create mode 100644 apps/client-web/src/twitterSetupAPI.spec.ts
 create mode 100644 apps/client-web/src/twitterSetupWizard.spec.ts
 create mode 100644 extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.md
 create mode 100644 extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.scss
 create mode 100644 extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.ts
 create mode 100644 extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.vue
 create mode 100644 extensions/twitter/src/setup-api.ts

diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.md b/apps/client-web/src/components/extension/extensionCard/extensionCard.md
index 2911d00..27ccf37 100644
--- a/apps/client-web/src/components/extension/extensionCard/extensionCard.md
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.md
@@ -17,6 +17,8 @@ A component that displays extension information and provides controls for toggli
 
 - Display canonical Extension Name, exact version, and optional nickname
 - Toggle enable/disable status with a switch
+- Mount the setup component contributed by the already-running local Web Extension in a host-owned dialog
+- Unmount setup content before disabling and disposing the Extension runtime
 - Edit extension configuration via JSON editor in a dialog
 - Change the exact shared version only while every Peer is disabled
 - Auto-formats configuration as JSON for easier editing
diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts b/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
new file mode 100644
index 0000000..dd57e85
--- /dev/null
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
@@ -0,0 +1,90 @@
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import extensionCard from './extensionCard.vue'
+
+const SetupComponent = defineComponent({
+  template: '<p data-test="twitter-setup">Twitter setup</p>',
+})
+const host = {
+  getSetupContribution: vi.fn(() => ({ component: SetupComponent })),
+  enable: vi.fn(),
+  disable: vi.fn(),
+  changeVersion: vi.fn(),
+  updateConfig: vi.fn(),
+  uninstall: vi.fn(),
+}
+
+vi.mock('@/core', () => ({ getExtensionHost: () => host }))
+vi.mock('vue-i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }))
+
+const extension = {
+  name: 'inkcre/twitter',
+  version: '0.2.0',
+  enabled: ['00000000-0000-4000-8000-000000000001'],
+  nickname: 'Twitter',
+  config: {},
+  config_schema: null,
+}
+
+const stubs = {
+  InkButton: defineComponent({
+    props: ['text'],
+    emits: ['click'],
+    template: '<button @click="$emit(\'click\')">{{ text }}</button>',
+  }),
+  InkSwitch: defineComponent({
+    props: ['modelValue'],
+    emits: ['update:modelValue'],
+    template: '<button data-test="switch" @click="$emit(\'update:modelValue\', false)" />',
+  }),
+  InkDialog: defineComponent({ template: '<section><slot /></section>' }),
+  InkInput: true,
+  InkJsonEditor: true,
+}
+
+describe('ExtensionCard setup contribution', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('mounts setup only for an enabled, running Web Extension contribution', async () => {
+    const wrapper = mount(extensionCard, {
+      props: { extension, enabled: true },
+      global: { stubs },
+    })
+
+    const setup = wrapper.findAll('button').find((button) => button.text() === 'extension.setup')
+    expect(setup).toBeDefined()
+    await setup?.trigger('click')
+
+    expect(host.getSetupContribution).toHaveBeenCalledWith('inkcre/twitter')
+    expect(wrapper.get('[data-test="twitter-setup"]').text()).toBe('Twitter setup')
+  })
+
+  it('does not offer setup while this Web Peer is disabled', () => {
+    const wrapper = mount(extensionCard, {
+      props: { extension: { ...extension, enabled: [] }, enabled: false },
+      global: { stubs },
+    })
+
+    expect(wrapper.text()).not.toContain('extension.setup')
+    expect(host.getSetupContribution).not.toHaveBeenCalled()
+  })
+
+  it('unmounts contributed setup before disabling its Remote runtime', async () => {
+    const wrapper = mount(extensionCard, {
+      props: { extension, enabled: true },
+      global: { stubs },
+    })
+    const setup = wrapper.findAll('button').find((button) => button.text() === 'extension.setup')
+    await setup?.trigger('click')
+    expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(true)
+    host.disable.mockImplementationOnce(async () => {
+      expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(false)
+    })
+
+    await wrapper.get('[data-test="switch"]').trigger('click')
+    await flushPromises()
+
+    expect(host.disable).toHaveBeenCalledWith('inkcre/twitter')
+  })
+})
diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.vue b/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
index f72f738..229fbfb 100644
--- a/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, computed, watch } from 'vue'
+import { ref, computed, nextTick, shallowRef, watch, type Component } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { InkButton, InkSwitch, InkDialog, InkInput, InkJsonEditor } from '@inkcre/ui-web'
 import { getExtensionHost } from '@/core'
@@ -12,6 +12,8 @@ const { t } = useI18n()
 // --- data ---
 const configPopupOpen = ref<boolean | Promise<boolean>>(false)
 const versionPopupOpen = ref<boolean | Promise<boolean>>(false)
+const setupPopupOpen = ref(false)
+const setupComponent = shallowRef<Component | null>(null)
 const togglePromise = ref<Promise<boolean> | null>(null)
 const isUninstalling = ref(false)
 const operationError = ref<string | null>(null)
@@ -28,6 +30,15 @@ watch(
 )
 
 const canUninstall = computed(() => props.extension.enabled.length === 0 && !isUninstalling.value)
+const setupContribution = computed(() =>
+  props.enabled ? getExtensionHost().getSetupContribution(props.extension.name) : null
+)
+
+const closeSetup = async () => {
+  setupPopupOpen.value = false
+  setupComponent.value = null
+  await nextTick()
+}
 
 const toggleModel = computed({
   get: () => (togglePromise.value ? togglePromise.value : props.enabled),
@@ -38,6 +49,7 @@ const toggleModel = computed({
         if (enabled) {
           await getExtensionHost().enable(props.extension.name)
         } else {
+          await closeSetup()
           await getExtensionHost().disable(props.extension.name)
         }
         emit('changed')
@@ -56,6 +68,13 @@ const onEditConfigClick = () => {
   configPopupOpen.value = true
 }
 
+const onSetupClick = () => {
+  const contribution = setupContribution.value
+  if (!contribution) return
+  setupComponent.value = contribution.component
+  setupPopupOpen.value = true
+}
+
 const onChangeVersionClick = () => {
   versionModel.value = props.extension.version
   versionPopupOpen.value = true
@@ -123,6 +142,13 @@ const onUninstall = async () => {
     </div>
 
     <div class="extension-card__actions">
+      <InkButton
+        v-if="setupContribution"
+        @click="onSetupClick"
+        :text="t('extension.setup')"
+        theme="primary"
+        size="sm"
+      />
       <InkButton @click="onEditConfigClick" :text="t('extension.editConfig')" size="sm" />
       <InkButton
         @click="onChangeVersionClick"
@@ -146,6 +172,17 @@ const onUninstall = async () => {
     </p>
     <p v-if="operationError" class="extension-card__error">{{ operationError }}</p>
 
+    <InkDialog
+      v-model="setupPopupOpen"
+      :title="t('extension.setupTitle', { name: extension.nickname ?? extension.name })"
+      :show-cancel="false"
+      :show-confirm="false"
+      :close-on-scrim="false"
+      @update:model-value="(open) => !open && closeSetup()"
+    >
+      <component :is="setupComponent" v-if="setupComponent" @close="closeSetup" />
+    </InkDialog>
+
     <InkDialog
       v-model="configPopupOpen"
       :title="t('extension.editConfigTitle')"
diff --git a/apps/client-web/src/locales/messages/en.json b/apps/client-web/src/locales/messages/en.json
index 0b512cc..750168a 100644
--- a/apps/client-web/src/locales/messages/en.json
+++ b/apps/client-web/src/locales/messages/en.json
@@ -59,6 +59,8 @@
     "newJobDescription": "Create a new collect job for this source. The job will be queued and executed as soon as possible.",
     "createJob": "Create Job",
     "editConfig": "Edit Config",
+    "setup": "Setup",
+    "setupTitle": "Set up {name}",
     "delete": "Delete",
     "noJobs": "No collect jobs found",
     "nicknamePlaceholder": "Click to edit nickname",
diff --git a/apps/client-web/src/locales/messages/zh-CN.json b/apps/client-web/src/locales/messages/zh-CN.json
index e3c168f..4f0bfd4 100644
--- a/apps/client-web/src/locales/messages/zh-CN.json
+++ b/apps/client-web/src/locales/messages/zh-CN.json
@@ -59,6 +59,8 @@
     "newJobDescription": "为此数据源创建新的采集任务。该任务将被加入队列并尽快执行。",
     "createJob": "创建任务",
     "editConfig": "编辑配置",
+    "setup": "设置",
+    "setupTitle": "设置 {name}",
     "delete": "删除",
     "noJobs": "未找到采集任务",
     "nicknamePlaceholder": "点击编辑昵称",
diff --git a/apps/client-web/src/twitterSetupAPI.spec.ts b/apps/client-web/src/twitterSetupAPI.spec.ts
new file mode 100644
index 0000000..8695c21
--- /dev/null
+++ b/apps/client-web/src/twitterSetupAPI.spec.ts
@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Client } from '@inkcre/core'
+import { discoverCoreCandidates, TwitterSetupAPI } from '../../../extensions/twitter/src/setup-api'
+
+const extension = {
+  name: 'inkcre/twitter',
+  version: '0.2.0',
+  enabled: ['00000000-0000-4000-8000-000000000002'],
+  nickname: 'Twitter',
+  config: {},
+  config_schema: null,
+}
+
+describe('Twitter setup Core transport', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('discovers candidates by probing the semantic Core management endpoint', async () => {
+    const core = Client.parse({
+      id: '00000000-0000-4000-8000-000000000002',
+      name: 'Core',
+      rest_api_url: 'https://core.example/',
+    })
+    const web = Client.parse({
+      id: '00000000-0000-4000-8000-000000000003',
+      name: 'Web',
+      rest_api_url: 'https://web.example/',
+    })
+    vi.spyOn(Client, 'list').mockResolvedValue([core, web])
+    vi.spyOn(core, 'request').mockResolvedValue(extension)
+    vi.spyOn(web, 'request').mockRejectedValue(new Error('not a Core Peer'))
+
+    await expect(discoverCoreCandidates()).resolves.toMatchObject([
+      { client: { id: core.id }, enabled: true, extension },
+    ])
+  })
+
+  it('keeps OAuth App secrets in a JSON command body and forwards cancellation', async () => {
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000002',
+      name: 'Core',
+      rest_api_url: 'https://core.example/',
+    })
+    const request = vi.spyOn(client, 'request').mockResolvedValue({})
+    const controller = new AbortController()
+
+    await new TwitterSetupAPI(client).saveOAuthApp(
+      'client-id',
+      'client-secret',
+      false,
+      controller.signal
+    )
+
+    expect(request).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'PUT',
+        path: '/twitter/setup/oauth-app',
+        body: {
+          client_id: 'client-id',
+          client_secret: 'client-secret',
+          confirm_account_reset: false,
+        },
+        signal: controller.signal,
+      })
+    )
+  })
+})
diff --git a/apps/client-web/src/twitterSetupWizard.spec.ts b/apps/client-web/src/twitterSetupWizard.spec.ts
new file mode 100644
index 0000000..b6ec062
--- /dev/null
+++ b/apps/client-web/src/twitterSetupWizard.spec.ts
@@ -0,0 +1,72 @@
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Client } from '@inkcre/core'
+import TwitterSetupWizard from '../../../extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.vue'
+
+const coreId = '00000000-0000-4000-8000-000000000002'
+const installed = {
+  name: 'inkcre/twitter',
+  version: '0.2.0',
+  enabled: [] as string[],
+  nickname: 'Twitter',
+  config: {},
+  config_schema: null,
+}
+const status = {
+  backend: 'official',
+  callback_url: 'https://core.example/twitter/auth/callback',
+  oauth_app_configured: false,
+  client_id: null,
+  connected: false,
+  user_id: null,
+  handle: null,
+  scopes: [],
+  reconnect_required: false,
+  bookmark_source_id: null,
+  bookmark_sources: [],
+  bookmark_source_ready: false,
+  ready: false,
+}
+
+const stubs = {
+  InkButton: defineComponent({
+    props: ['text'],
+    emits: ['click'],
+    template: '<button @click="$emit(\'click\')">{{ text }}</button>',
+  }),
+  InkInput: true,
+  InkLoading: true,
+}
+
+describe('TwitterSetupWizard', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('requires explicit Core enablement before showing whole-Extension setup commands', async () => {
+    const core = Client.parse({
+      id: coreId,
+      name: 'Core',
+      rest_api_url: 'https://core.example/',
+    })
+    vi.spyOn(Client, 'list').mockResolvedValue([core])
+    vi.spyOn(core, 'request').mockImplementation(async (options) => {
+      if (options.path === '/extensions/inkcre/twitter' && options.method === 'GET') {
+        return installed
+      }
+      if (options.path === '/extensions/inkcre/twitter/enable') {
+        return { ...installed, enabled: [coreId] }
+      }
+      if (options.path === '/twitter/setup') return status
+      throw new Error(`Unexpected setup request: ${options.method} ${options.path}`)
+    })
+    const wrapper = mount(TwitterSetupWizard, { global: { stubs } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Enable Twitter on this Core Peer')
+    await wrapper.get('button').trigger('click')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Connect an X account')
+    expect(wrapper.text()).toContain('https://core.example/twitter/auth/callback')
+  })
+})
diff --git a/extensions/AGENTS.md b/extensions/AGENTS.md
index 02d5782..8c70d32 100644
--- a/extensions/AGENTS.md
+++ b/extensions/AGENTS.md
@@ -42,6 +42,8 @@ Extensions can register:
 - Custom Resolvers for new content types
 - Custom Storages for data retrieval
 - UI components
+- An optional deployment-wide setup wizard component. `client-web` owns only the popup shell;
+  the Extension owns the stepper, Core coordination, provider flow, and completion semantics.
 
 ## Related
 
diff --git a/extensions/twitter/package.json b/extensions/twitter/package.json
index ac01495..b33aa7b 100644
--- a/extensions/twitter/package.json
+++ b/extensions/twitter/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@inkcre/ext-twitter",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -36,7 +36,7 @@
     "nickname": "Twitter",
     "module_federation": {
       "host_sdk": "@inkcre/core",
-      "host_sdk_version": ">=0.1.0 <0.2.0"
+      "host_sdk_version": ">=0.1.1 <0.2.0"
     }
   }
 }
diff --git a/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.md b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.md
new file mode 100644
index 0000000..aa3cee9
--- /dev/null
+++ b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.md
@@ -0,0 +1,9 @@
+# TwitterSetupWizard
+
+Twitter-owned four-step setup contribution mounted by the client-web Extension dialog.
+
+- Discovers reachable Core Peers through the ordinary `Client` API.
+- Requires explicit Core enablement before setup commands are available.
+- Configures the user's X OAuth App, opens the standalone provider flow, and polls only the opaque transaction reference.
+- Selects or creates a Bookmark Source and explicitly starts initial collection.
+- Derives progress from Core setup facts; it does not persist a wizard step.
diff --git a/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.scss b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.scss
new file mode 100644
index 0000000..0614fcc
--- /dev/null
+++ b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.scss
@@ -0,0 +1,119 @@
+.twitter-setup {
+  display: grid;
+  gap: 1.25rem;
+  width: min(680px, 80vw);
+
+  &__steps {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 0.5rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+
+    li {
+      display: flex;
+      align-items: center;
+      gap: 0.4rem;
+      color: #6b7280;
+      font-size: 0.8rem;
+    }
+
+    span {
+      display: inline-grid;
+      place-items: center;
+      width: 1.5rem;
+      height: 1.5rem;
+      border: 1px solid currentcolor;
+      border-radius: 50%;
+    }
+
+    .is-current,
+    .is-complete {
+      color: #2563eb;
+      font-weight: 600;
+    }
+  }
+
+  &__panel {
+    display: grid;
+    gap: 1rem;
+
+    h3,
+    p {
+      margin: 0;
+    }
+
+    code {
+      display: block;
+      margin-top: 0.5rem;
+      padding: 0.6rem;
+      overflow-wrap: anywhere;
+      background: rgb(0 0 0 / 5%);
+    }
+  }
+
+  &__field,
+  &__schedule label {
+    display: grid;
+    gap: 0.35rem;
+  }
+
+  select,
+  input {
+    min-height: 2.5rem;
+    padding: 0.5rem;
+    border: 1px solid #d1d5db;
+    border-radius: 0.35rem;
+    background: transparent;
+    color: inherit;
+  }
+
+  &__schedule,
+  &__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+
+  &__oauth-link {
+    width: fit-content;
+    font-weight: 600;
+  }
+
+  &__loading {
+    display: flex;
+    justify-content: center;
+    min-height: 10rem;
+  }
+
+  &__error {
+    margin: 0;
+    color: #b91c1c;
+  }
+
+  dl {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: 0.5rem 1rem;
+    margin: 0;
+  }
+
+  dt {
+    font-weight: 600;
+  }
+
+  dd {
+    margin: 0;
+  }
+}
+
+@media (max-width: 640px) {
+  .twitter-setup {
+    width: min(88vw, 680px);
+
+    &__steps {
+      grid-template-columns: 1fr 1fr;
+    }
+  }
+}
diff --git a/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.ts b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.ts
new file mode 100644
index 0000000..aa6288d
--- /dev/null
+++ b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.ts
@@ -0,0 +1,10 @@
+export const twitterSetupWizardEmits = {
+  close: () => true,
+} as const
+
+export const TWITTER_SETUP_STEPS = [
+  'Prepare',
+  'Connect account',
+  'Bookmark Source',
+  'Review and start',
+] as const
diff --git a/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.vue b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.vue
new file mode 100644
index 0000000..df5f48c
--- /dev/null
+++ b/extensions/twitter/src/components/twitterSetupWizard/twitterSetupWizard.vue
@@ -0,0 +1,407 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import { InkButton, InkInput, InkLoading } from '@inkcre/ui-web'
+import {
+  discoverCoreCandidates,
+  TwitterSetupAPI,
+  type CoreCandidate,
+  type OAuthTransaction,
+  type TwitterSetupStatus,
+} from '../../setup-api'
+import { TWITTER_SETUP_STEPS, twitterSetupWizardEmits } from './twitterSetupWizard'
+
+const emit = defineEmits(twitterSetupWizardEmits)
+const candidates = ref<CoreCandidate[]>([])
+const selectedClientId = ref<string | null>(null)
+const status = ref<TwitterSetupStatus | null>(null)
+const currentStep = ref(0)
+const loading = ref(true)
+const busy = ref(false)
+const error = ref<string | null>(null)
+const clientId = ref('')
+const clientSecret = ref('')
+const transaction = ref<OAuthTransaction | null>(null)
+const sourceId = ref<number | null>(null)
+const sourceNickname = ref('Twitter Bookmarks')
+const sourceHour = ref(0)
+const sourceMinute = ref(0)
+let polling: AbortController | null = null
+const lifecycle = new AbortController()
+
+const selectedCandidate = computed(
+  () => candidates.value.find((candidate) => candidate.client.id === selectedClientId.value) ?? null
+)
+const api = computed(() =>
+  selectedCandidate.value ? new TwitterSetupAPI(selectedCandidate.value.client) : null
+)
+const selectedCoreEnabled = computed(() => selectedCandidate.value?.enabled ?? false)
+
+function message(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+function deriveStep(next: TwitterSetupStatus): number {
+  if (!next.oauth_app_configured || !next.connected) return 1
+  if (next.bookmark_source_id === null) return 2
+  return 3
+}
+
+function applyStatus(next: TwitterSetupStatus): void {
+  status.value = next
+  clientId.value = next.client_id ?? ''
+  clientSecret.value = ''
+  sourceId.value = next.bookmark_source_id ?? next.bookmark_sources[0]?.source_id ?? null
+  const source = next.bookmark_sources.find((item) => item.source_id === sourceId.value)
+  if (source) {
+    sourceNickname.value = source.nickname
+    sourceHour.value = source.collect_at.hour
+    sourceMinute.value = source.collect_at.minute
+  }
+  currentStep.value = deriveStep(next)
+}
+
+async function reloadStatus(): Promise<void> {
+  if (!api.value || !selectedCoreEnabled.value) return
+  applyStatus(await api.value.status(lifecycle.signal))
+}
+
+async function initialize(): Promise<void> {
+  loading.value = true
+  error.value = null
+  try {
+    candidates.value = await discoverCoreCandidates(lifecycle.signal)
+    const selected = candidates.value.find((candidate) => candidate.enabled) ?? candidates.value[0]
+    selectedClientId.value = selected?.client.id ?? null
+    if (selected?.enabled) await reloadStatus()
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    loading.value = false
+  }
+}
+
+async function enableSelectedCore(): Promise<void> {
+  if (!api.value || !selectedCandidate.value) return
+  busy.value = true
+  error.value = null
+  try {
+    const extension = await api.value.enableCore(lifecycle.signal)
+    selectedCandidate.value.extension = extension
+    selectedCandidate.value.enabled = extension.enabled.includes(selectedCandidate.value.client.id)
+    await reloadStatus()
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+async function saveOAuthApp(): Promise<void> {
+  if (!api.value) return
+  busy.value = true
+  error.value = null
+  try {
+    try {
+      applyStatus(
+        await api.value.saveOAuthApp(clientId.value, clientSecret.value, false, lifecycle.signal)
+      )
+    } catch (cause) {
+      const causeMessage = message(cause)
+      if (!causeMessage.includes('requires confirmation')) throw cause
+      if (!window.confirm(`${causeMessage}\n\nDisconnect the current account and continue?`)) return
+      applyStatus(
+        await api.value.saveOAuthApp(clientId.value, clientSecret.value, true, lifecycle.signal)
+      )
+    }
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+function stopPolling(): void {
+  polling?.abort()
+  polling = null
+}
+
+async function wait(milliseconds: number, signal: AbortSignal): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException('Polling cancelled', 'AbortError'))
+      return
+    }
+    const onAbort = () => {
+      window.clearTimeout(timer)
+      reject(new DOMException('Polling cancelled', 'AbortError'))
+    }
+    const timer = window.setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, milliseconds)
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+async function pollTransaction(id: string): Promise<void> {
+  if (!api.value) return
+  stopPolling()
+  const controller = new AbortController()
+  polling = controller
+  try {
+    while (!controller.signal.aborted) {
+      await wait(2000, controller.signal)
+      const next = await api.value.oauthTransaction(id, controller.signal)
+      transaction.value = next
+      if (!['pending', 'exchanging'].includes(next.status)) {
+        if (next.status === 'succeeded') await reloadStatus()
+        else error.value = next.error ?? 'Twitter authorization did not complete.'
+        return
+      }
+    }
+  } catch (cause) {
+    if (!controller.signal.aborted) error.value = message(cause)
+  } finally {
+    if (polling === controller) polling = null
+  }
+}
+
+async function beginOAuth(): Promise<void> {
+  if (!api.value) return
+  busy.value = true
+  error.value = null
+  try {
+    transaction.value = await api.value.beginOAuth(lifecycle.signal)
+    void pollTransaction(transaction.value.id)
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+async function disconnect(): Promise<void> {
+  if (!api.value) return
+  busy.value = true
+  error.value = null
+  try {
+    stopPolling()
+    transaction.value = null
+    applyStatus(await api.value.disconnect(lifecycle.signal))
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+async function saveBookmarkSource(): Promise<void> {
+  if (!api.value) return
+  busy.value = true
+  error.value = null
+  try {
+    applyStatus(
+      await api.value.ensureBookmarkSource(
+        {
+          ...(sourceId.value === null ? {} : { source_id: sourceId.value }),
+          nickname: sourceNickname.value,
+          collect_at: {
+            day_of_week: null,
+            hour: sourceHour.value,
+            minute: sourceMinute.value,
+          },
+        },
+        lifecycle.signal
+      )
+    )
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+async function finish(): Promise<void> {
+  if (!api.value) return
+  busy.value = true
+  error.value = null
+  try {
+    applyStatus(await api.value.finish(lifecycle.signal))
+  } catch (cause) {
+    error.value = message(cause)
+  } finally {
+    busy.value = false
+  }
+}
+
+onMounted(() => void initialize())
+onBeforeUnmount(() => {
+  lifecycle.abort()
+  stopPolling()
+})
+</script>
+
+<template>
+  <section class="twitter-setup">
+    <ol class="twitter-setup__steps" aria-label="Twitter setup progress">
+      <li
+        v-for="(step, index) in TWITTER_SETUP_STEPS"
+        :key="step"
+        :class="{ 'is-current': currentStep === index, 'is-complete': currentStep > index }"
+      >
+        <span>{{ index + 1 }}</span
+        >{{ step }}
+      </li>
+    </ol>
+
+    <div v-if="loading" class="twitter-setup__loading"><InkLoading /></div>
+    <template v-else>
+      <p v-if="error" class="twitter-setup__error" role="alert">{{ error }}</p>
+
+      <div v-if="currentStep === 0" class="twitter-setup__panel">
+        <h3>Choose a Core Peer</h3>
+        <p>
+          The setup commands run on a Core Peer, but configure Twitter for the whole deployment.
+        </p>
+        <label v-if="candidates.length" class="twitter-setup__field">
+          Core Peer
+          <select v-model="selectedClientId">
+            <option
+              v-for="candidate in candidates"
+              :key="candidate.client.id"
+              :value="candidate.client.id"
+            >
+              {{ candidate.client.name }}{{ candidate.enabled ? ' — enabled' : '' }}
+            </option>
+          </select>
+        </label>
+        <p v-else>No reachable Core Peer exposes the installed Twitter Extension.</p>
+        <InkButton
+          v-if="selectedCandidate && !selectedCoreEnabled"
+          text="Enable Twitter on this Core Peer"
+          theme="primary"
+          :loading="busy"
+          @click="enableSelectedCore"
+        />
+      </div>
+
+      <div v-else-if="currentStep === 1" class="twitter-setup__panel">
+        <h3>Connect an X account</h3>
+        <p>
+          Register your own X OAuth 2.0 application and use this callback URL:
+          <code>{{ status?.callback_url }}</code>
+        </p>
+        <InkInput v-model="clientId" label="Client ID" required />
+        <label class="twitter-setup__field">
+          Client Secret
+          <input v-model="clientSecret" type="password" autocomplete="off" required />
+        </label>
+        <div class="twitter-setup__actions">
+          <InkButton
+            text="Save OAuth App"
+            :loading="busy"
+            :disabled="!clientId || !clientSecret"
+            @click="saveOAuthApp"
+          />
+          <InkButton
+            v-if="status?.oauth_app_configured"
+            text="Create authorization link"
+            theme="primary"
+            :loading="busy"
+            @click="beginOAuth"
+          />
+          <InkButton
+            v-if="status?.connected"
+            text="Disconnect"
+            theme="danger"
+            @click="disconnect"
+          />
+        </div>
+        <a
+          v-if="transaction?.authorize_url"
+          :href="transaction.authorize_url"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="twitter-setup__oauth-link"
+        >
+          Open X authorization
+        </a>
+        <p v-if="transaction && ['pending', 'exchanging'].includes(transaction.status)">
+          Waiting for the standalone Core callback…
+        </p>
+        <p v-if="status?.connected">Connected as @{{ status.handle }}.</p>
+      </div>
+
+      <div v-else-if="currentStep === 2" class="twitter-setup__panel">
+        <h3>Choose a Bookmark Source</h3>
+        <label v-if="status?.bookmark_sources.length" class="twitter-setup__field">
+          Existing Source
+          <select v-model="sourceId">
+            <option :value="null">Create a new Source</option>
+            <option
+              v-for="source in status.bookmark_sources"
+              :key="source.source_id ?? 0"
+              :value="source.source_id"
+            >
+              {{ source.nickname }}
+            </option>
+          </select>
+        </label>
+        <InkInput v-model="sourceNickname" label="Source nickname" :disabled="sourceId !== null" />
+        <div class="twitter-setup__schedule">
+          <label>
+            Daily hour
+            <input
+              v-model.number="sourceHour"
+              type="number"
+              min="0"
+              max="23"
+              :disabled="sourceId !== null"
+            />
+          </label>
+          <label>
+            Minute
+            <input
+              v-model.number="sourceMinute"
+              type="number"
+              min="0"
+              max="59"
+              :disabled="sourceId !== null"
+            />
+          </label>
+        </div>
+        <p v-if="sourceId !== null">Change an existing Source schedule from the Sources page.</p>
+        <InkButton
+          text="Use this Source"
+          theme="primary"
+          :loading="busy"
+          @click="saveBookmarkSource"
+        />
+      </div>
+
+      <div v-else class="twitter-setup__panel">
+        <h3>{{ status?.ready ? 'Twitter is ready' : 'Review and start' }}</h3>
+        <dl>
+          <dt>Account</dt>
+          <dd>@{{ status?.handle }}</dd>
+          <dt>Bookmark Source</dt>
+          <dd>#{{ status?.bookmark_source_id }}</dd>
+          <dt>Initial collection</dt>
+          <dd>{{ status?.bookmark_source_ready ? 'accepted' : 'not started' }}</dd>
+        </dl>
+        <div class="twitter-setup__actions">
+          <InkButton
+            v-if="!status?.ready"
+            text="Start collecting bookmarks"
+            theme="primary"
+            :loading="busy"
+            @click="finish"
+          />
+          <InkButton text="Close" theme="subtle" @click="emit('close')" />
+        </div>
+      </div>
+    </template>
+  </section>
+</template>
+
+<style lang="scss" scoped src="./twitterSetupWizard.scss" />
diff --git a/extensions/twitter/src/index.ts b/extensions/twitter/src/index.ts
index d685fd2..d942a7f 100644
--- a/extensions/twitter/src/index.ts
+++ b/extensions/twitter/src/index.ts
@@ -12,8 +12,10 @@
 
 import { type ExtensionModule } from '@inkcre/core'
 import './resolver'
+import TwitterSetupWizard from './components/twitterSetupWizard/twitterSetupWizard.vue'
 
 const Extension: ExtensionModule = {
+  setup: { component: TwitterSetupWizard },
   async initialize() {},
 
   async activate() {
diff --git a/extensions/twitter/src/setup-api.ts b/extensions/twitter/src/setup-api.ts
new file mode 100644
index 0000000..a44ca5e
--- /dev/null
+++ b/extensions/twitter/src/setup-api.ts
@@ -0,0 +1,167 @@
+import { Client, InstalledExtensionSchema, type InstalledExtension } from '@inkcre/core'
+import { z } from 'zod'
+
+const CollectAtSchema = z.object({
+  day_of_week: z.number().int().min(0).max(6).nullable(),
+  hour: z.number().int().min(0).max(23),
+  minute: z.number().int().min(0).max(59),
+})
+
+const BookmarkSourceSchema = z.object({
+  source_id: z.number().int().positive().nullable(),
+  nickname: z.string(),
+  collect_at: CollectAtSchema,
+})
+
+export const TwitterSetupStatusSchema = z.object({
+  backend: z.string(),
+  callback_url: z.url(),
+  oauth_app_configured: z.boolean(),
+  client_id: z.string().nullable(),
+  connected: z.boolean(),
+  user_id: z.string().nullable(),
+  handle: z.string().nullable(),
+  scopes: z.array(z.string()),
+  reconnect_required: z.boolean(),
+  bookmark_source_id: z.number().int().positive().nullable(),
+  bookmark_sources: z.array(BookmarkSourceSchema),
+  bookmark_source_ready: z.boolean(),
+  ready: z.boolean(),
+})
+
+export const OAuthTransactionSchema = z.object({
+  id: z.string().uuid(),
+  status: z.enum(['pending', 'exchanging', 'succeeded', 'failed', 'expired']),
+  authorize_url: z.url().nullable(),
+  expires_at: z.coerce.date(),
+  error: z.string().nullable(),
+})
+
+export type TwitterSetupStatus = z.infer<typeof TwitterSetupStatusSchema>
+export type OAuthTransaction = z.infer<typeof OAuthTransactionSchema>
+
+export interface CoreCandidate {
+  client: Client
+  extension: InstalledExtension
+  enabled: boolean
+}
+
+type SetupClient = Pick<Client, 'request'>
+
+export async function discoverCoreCandidates(signal?: AbortSignal): Promise<CoreCandidate[]> {
+  const clients = (await Client.list()).filter((client) => client.rest_api_url)
+  const candidates = await Promise.all(
+    clients.map(async (client): Promise<CoreCandidate | null> => {
+      try {
+        const extension = await client.request({
+          method: 'GET',
+          path: '/extensions/inkcre/twitter',
+          resBodySchema: InstalledExtensionSchema,
+          signal,
+        })
+        return {
+          client,
+          extension,
+          enabled: extension.enabled.includes(client.id),
+        }
+      } catch {
+        return null
+      }
+    })
+  )
+  return candidates.filter((candidate): candidate is CoreCandidate => candidate !== null)
+}
+
+export class TwitterSetupAPI {
+  constructor(readonly client: SetupClient) {}
+
+  async enableCore(signal?: AbortSignal): Promise<InstalledExtension> {
+    return this.client.request({
+      method: 'POST',
+      path: '/extensions/inkcre/twitter/enable',
+      resBodySchema: InstalledExtensionSchema,
+      signal,
+    })
+  }
+
+  status(signal?: AbortSignal): Promise<TwitterSetupStatus> {
+    return this.client.request({
+      method: 'GET',
+      path: '/twitter/setup',
+      resBodySchema: TwitterSetupStatusSchema,
+      signal,
+    })
+  }
+
+  saveOAuthApp(
+    clientId: string,
+    clientSecret: string,
+    confirmAccountReset: boolean,
+    signal?: AbortSignal
+  ): Promise<TwitterSetupStatus> {
+    return this.client.request({
+      method: 'PUT',
+      path: '/twitter/setup/oauth-app',
+      body: {
+        client_id: clientId,
+        client_secret: clientSecret,
+        confirm_account_reset: confirmAccountReset,
+      },
+      resBodySchema: TwitterSetupStatusSchema,
+      signal,
+    })
+  }
+
+  beginOAuth(signal?: AbortSignal): Promise<OAuthTransaction> {
+    return this.client.request({
+      method: 'POST',
+      path: '/twitter/setup/oauth-transactions',
+      resBodySchema: OAuthTransactionSchema,
+      signal,
+    })
+  }
+
+  oauthTransaction(id: string, signal?: AbortSignal): Promise<OAuthTransaction> {
+    return this.client.request({
+      method: 'GET',
+      path: `/twitter/setup/oauth-transactions/${encodeURIComponent(id)}`,
+      resBodySchema: OAuthTransactionSchema,
+      signal,
+    })
+  }
+
+  disconnect(signal?: AbortSignal): Promise<TwitterSetupStatus> {
+    return this.client.request({
+      method: 'DELETE',
+      path: '/twitter/setup/account',
+      resBodySchema: TwitterSetupStatusSchema,
+      signal,
+    })
+  }
+
+  ensureBookmarkSource(
+    input: {
+      source_id?: number
+      nickname: string
+      collect_at: { day_of_week: number | null; hour: number; minute: number }
+    },
+    signal?: AbortSignal
+  ): Promise<TwitterSetupStatus> {
+    return this.client.request({
+      method: 'POST',
+      path: '/twitter/setup/bookmark-source',
+      body: input,
+      resBodySchema: TwitterSetupStatusSchema,
+      signal,
+    })
+  }
+
+  finish(signal?: AbortSignal): Promise<TwitterSetupStatus> {
+    return this.client.request({
+      method: 'POST',
+      path: '/twitter/setup/finish',
+      resBodySchema: TwitterSetupStatusSchema,
+      signal,
+    })
+  }
+}
diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md
index c37cc0f..f5a2948 100644
--- a/packages/core/AGENTS.md
+++ b/packages/core/AGENTS.md
@@ -46,6 +46,8 @@ Make use of Vue reactivity thorughout-ly.
   native manifest URL with Module Federation.
 - Preserve `initialize`, `activate`, `deactivate`, and `dispose`, including durable-state failure
   compensation.
+- A running Extension may contribute an optional setup Vue component. The Host exposes that
+  component only while the exact runtime is active; it does not own setup steps or provider logic.
 
 ### Info-Base Content Contract
 
diff --git a/packages/core/package.json b/packages/core/package.json
index d398a43..8a6c349 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@inkcre/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "files": [
     "dist"
   ],
diff --git a/packages/core/src/client/client.test.ts b/packages/core/src/client/client.test.ts
index 583e7f0..12d04ae 100644
--- a/packages/core/src/client/client.test.ts
+++ b/packages/core/src/client/client.test.ts
@@ -53,4 +53,57 @@ describe('Client.request', () => {
       expect.objectContaining({ method: 'GET' })
     )
   })
+
+  it('preserves JSON headers, body, and AbortSignal across one 401 refresh retry', async () => {
+    vi.spyOn(authStore, 'getToken')
+      .mockResolvedValueOnce('expired-token')
+      .mockResolvedValueOnce('fresh-token')
+    vi.spyOn(authStore, 'refreshToken').mockResolvedValue('fresh-token')
+    const fetch = vi
+      .fn()
+      .mockResolvedValueOnce(Response.json({ detail: 'expired' }, { status: 401 }))
+      .mockResolvedValueOnce(Response.json({ ok: true }))
+    vi.stubGlobal('fetch', fetch)
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000001',
+      name: 'Core',
+      rest_api_url: 'https://core.example/',
+    })
+    const controller = new AbortController()
+
+    await expect(
+      client.request({
+        method: 'PUT',
+        path: '/twitter/setup/oauth-app',
+        body: { client_id: 'client', client_secret: 'secret' },
+        signal: controller.signal,
+      })
+    ).resolves.toEqual({ ok: true })
+
+    const retry = fetch.mock.calls[1]?.[1] as RequestInit
+    expect(retry.method).toBe('PUT')
+    expect(retry.body).toBe(JSON.stringify({ client_id: 'client', client_secret: 'secret' }))
+    expect(retry.signal).toBe(controller.signal)
+    expect(retry.headers).toMatchObject({
+      Authorization: 'Bearer fresh-token',
+      'Content-Type': 'application/json',
+    })
+  })
+
+  it('uses a bounded string FastAPI detail as the API error message', async () => {
+    vi.spyOn(authStore, 'getToken').mockResolvedValue('test-token')
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () =>
+        Response.json({ detail: 'Connect a Twitter account first' }, { status: 409 })
+      )
+    )
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000001',
+      name: 'Core',
+      rest_api_url: 'https://core.example/',
+    })
+
+    await expect(client.get('/twitter/setup')).rejects.toThrow('Connect a Twitter account first')
+  })
 })
diff --git a/packages/core/src/client/client.ts b/packages/core/src/client/client.ts
index 88337bb..ac762ac 100644
--- a/packages/core/src/client/client.ts
+++ b/packages/core/src/client/client.ts
@@ -124,9 +124,10 @@ export class Client extends Z.class({
     path: string
     body?: any
     query?: Record<string, any>
-    resBodySchema?: { parse<T>(input: unknown): T }
+    resBodySchema?: { parse(input: unknown): T }
+    signal?: AbortSignal
   }): Promise<T> {
-    const { method, path, body, query, resBodySchema } = options
+    const { method, path, body, query, resBodySchema, signal } = options
     const parseSuccessfulResponse = async (response: Response): Promise<T> => {
       if (response.status === 204) {
         return undefined as T
@@ -145,6 +146,7 @@ export class Client extends Z.class({
     const config: RequestInit = {
       method,
       headers,
+      signal,
     }
 
     if (body !== undefined) {
@@ -179,10 +181,15 @@ export class Client extends Z.class({
 
         try {
           responseData = await response.json()
-          if (responseData.message) {
+          if (typeof responseData.message === 'string') {
             errorMessage = responseData.message
-          } else if (responseData.error) {
+          } else if (typeof responseData.error === 'string') {
             errorMessage = responseData.error
+          } else if (
+            typeof responseData.detail === 'string' &&
+            responseData.detail.length <= 1000
+          ) {
+            errorMessage = responseData.detail
           }
         } catch {
           // If response is not JSON, use status text
@@ -194,7 +201,7 @@ export class Client extends Z.class({
             await authStore.refreshToken()
             const retryResponse = await fetch(url, {
               ...config,
-              headers: { ...(await this.getAuthHeaders()) },
+              headers: { ...headers, ...(await this.getAuthHeaders()) },
             })
 
             if (retryResponse.ok) {
@@ -223,7 +230,7 @@ export class Client extends Z.class({
   async get<T = any>(
     path: string,
     query?: Record<string, any>,
-    resBodySchema?: { parse<T>(input: unknown): T }
+    resBodySchema?: { parse(input: unknown): T }
   ): Promise<T> {
     return this.request<T>({ method: 'GET', path, query, resBodySchema })
   }
@@ -234,7 +241,7 @@ export class Client extends Z.class({
   async post<T = any>(
     path: string,
     body?: any,
-    resBodySchema?: { parse<T>(input: unknown): T }
+    resBodySchema?: { parse(input: unknown): T }
   ): Promise<T> {
     return this.request<T>({ method: 'POST', path, body, resBodySchema })
   }
@@ -245,7 +252,7 @@ export class Client extends Z.class({
   async put<T = any>(
     path: string,
     body?: any,
-    resBodySchema?: { parse<T>(input: unknown): T }
+    resBodySchema?: { parse(input: unknown): T }
   ): Promise<T> {
     return this.request<T>({ method: 'PUT', path, body, resBodySchema })
   }
@@ -256,7 +263,7 @@ export class Client extends Z.class({
   async patch<T = any>(
     path: string,
     body?: any,
-    resBodySchema?: { parse<T>(input: unknown): T }
+    resBodySchema?: { parse(input: unknown): T }
   ): Promise<T> {
     return this.request<T>({ method: 'PATCH', path, body, resBodySchema })
   }
@@ -264,7 +271,7 @@ export class Client extends Z.class({
   /**
    * Convenience method for DELETE requests
    */
-  async delete<T = any>(path: string, resBodySchema?: { parse<T>(input: unknown): T }): Promise<T> {
+  async delete<T = any>(path: string, resBodySchema?: { parse(input: unknown): T }): Promise<T> {
     return this.request<T>({ method: 'DELETE', path, resBodySchema })
   }
 
diff --git a/packages/core/src/database/database.generated.ts b/packages/core/src/database/database.generated.ts
index 3f33865..2bc3313 100644
--- a/packages/core/src/database/database.generated.ts
+++ b/packages/core/src/database/database.generated.ts
@@ -101,6 +101,7 @@ export type Database = {
           enabled: string[]
           name: string
           nickname: string | null
+          state: Json
           version: string
         }
         Insert: {
@@ -109,6 +110,7 @@ export type Database = {
           enabled?: string[]
           name: string
           nickname?: string | null
+          state?: Json
           version: string
         }
         Update: {
@@ -117,6 +119,7 @@ export type Database = {
           enabled?: string[]
           name?: string
           nickname?: string | null
+          state?: Json
           version?: string
         }
         Relationships: []
@@ -373,6 +376,7 @@ export type Database = {
           enabled: string[]
           name: string
           nickname: string | null
+          state: Json
           version: string
         }[]
         SetofOptions: {
diff --git a/packages/core/src/database/runtime-contract.generated.json b/packages/core/src/database/runtime-contract.generated.json
index 5bd5f9e..85eeddd 100644
--- a/packages/core/src/database/runtime-contract.generated.json
+++ b/packages/core/src/database/runtime-contract.generated.json
@@ -271,6 +271,14 @@
               "kind": "string"
             }
           },
+          "state": {
+            "generated": false,
+            "has_default": true,
+            "nullable": false,
+            "type": {
+              "kind": "json"
+            }
+          },
           "version": {
             "generated": false,
             "has_default": false,
@@ -702,6 +710,6 @@
     },
     "schema": "inkcre"
   },
-  "revision": "peer-database-runtime-v2",
-  "source_revision": "34914b6deed4768237508fdb02e033655feb8073"
+  "revision": "peer-database-runtime-v3",
+  "source_revision": "63f57b26ed8685fa34a74516ade39e2af72218d9"
 }
diff --git a/packages/core/src/database/runtime-contract.test.ts b/packages/core/src/database/runtime-contract.test.ts
index a330cf7..565ba1f 100644
--- a/packages/core/src/database/runtime-contract.test.ts
+++ b/packages/core/src/database/runtime-contract.test.ts
@@ -6,7 +6,7 @@ describe('database runtime contract', () => {
   it('contains only environment-neutral protocol and JWT metadata', () => {
     expect(databaseRuntimeContract).toEqual({
       format: 1,
-      revision: 'peer-database-runtime-v2',
+      revision: 'peer-database-runtime-v3',
       protocol: {
         format: 1,
         schema: 'inkcre',
diff --git a/packages/core/src/extension/host.test.ts b/packages/core/src/extension/host.test.ts
index 3c00276..a79a45a 100644
--- a/packages/core/src/extension/host.test.ts
+++ b/packages/core/src/extension/host.test.ts
@@ -131,6 +131,7 @@ function createHarness(
     resolveManifestUrl: vi.fn((url) => new URL(url, 'https://registry.example').href),
   }
   const extensionModule = {
+    setup: { component: { name: 'TestSetup' } },
     initialize: vi.fn(async () => {
       events.push('initialize')
     }),
@@ -196,6 +197,20 @@ describe('WebExtensionHost', () => {
     )
     expect(harness.events).toEqual(['register-manifest', 'load-remote', 'initialize', 'activate'])
     expect(harness.state.events).toEqual(['persist-enable'])
+    expect(harness.host.isRunning(installed.name)).toBe(true)
+    expect(harness.host.getSetupContribution(installed.name)?.component).toEqual({
+      name: 'TestSetup',
+    })
+  })
+
+  it('withdraws the setup contribution with the running Extension', async () => {
+    const harness = createHarness()
+    await harness.host.enable(installed.name)
+
+    await harness.host.disable(installed.name)
+
+    expect(harness.host.isRunning(installed.name)).toBe(false)
+    expect(harness.host.getSetupContribution(installed.name)).toBeNull()
   })
 
   it('rejects an incompatible @inkcre/core range before MF can fetch executable bytes', async () => {
diff --git a/packages/core/src/extension/host.ts b/packages/core/src/extension/host.ts
index cbe882a..be3a026 100644
--- a/packages/core/src/extension/host.ts
+++ b/packages/core/src/extension/host.ts
@@ -84,6 +84,14 @@ export class WebExtensionHost {
     return this.runtimeErrors.get(name) ?? null
   }
 
+  isRunning(name: string): boolean {
+    return this.running.has(name)
+  }
+
+  getSetupContribution(name: string) {
+    return this.running.get(name)?.lifecycle.module?.setup ?? null
+  }
+
   async install(input: InstallExtensionInput): Promise<InstalledExtension> {
     const exact = InstallExtensionInputSchema.parse(input)
     return this.exclusively(async () => {
@@ -383,6 +391,10 @@ class WebExtensionLifecycle {
 
   constructor(private readonly load: () => Promise<ExtensionModule>) {}
 
+  get module(): ExtensionModule | null {
+    return this.extensionModule
+  }
+
   async start(): Promise<void> {
     if (this.extensionModule) return
 
diff --git a/packages/core/src/extension/index.ts b/packages/core/src/extension/index.ts
index 02fa927..1a9f48f 100644
--- a/packages/core/src/extension/index.ts
+++ b/packages/core/src/extension/index.ts
@@ -4,6 +4,7 @@ export {
   InstalledExtensionSchema,
   InstallExtensionInputSchema,
   type ExtensionModule,
+  type ExtensionSetupContribution,
   type InstalledExtension,
   type InstallExtensionInput,
 } from './model'
diff --git a/packages/core/src/extension/model.ts b/packages/core/src/extension/model.ts
index 0ee97f1..1d635d5 100644
--- a/packages/core/src/extension/model.ts
+++ b/packages/core/src/extension/model.ts
@@ -1,4 +1,5 @@
 import { parse as parseSemVer } from 'semver'
+import type { Component } from 'vue'
 import { z } from 'zod'
 
 const EXTENSION_NAME_PATTERN =
@@ -36,10 +37,16 @@ export const InstallExtensionInputSchema = InstalledExtensionSchema.pick({
 export type InstalledExtension = z.infer<typeof InstalledExtensionSchema>
 export type InstallExtensionInput = z.infer<typeof InstallExtensionInputSchema>
 
+/** Setup UI contributed by one already-running Web Extension. */
+export interface ExtensionSetupContribution {
+  component: Component
+}
+
 /** Default export exposed by a Web Extension's native Module Federation Remote. */
 export interface ExtensionModule {
   initialize?(): Promise<void>
   activate?(): Promise<void>
   deactivate?(): Promise<void>
   dispose?(): Promise<void>
+  setup?: ExtensionSetupContribution
 }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 212982f..e0ebc92 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -21,6 +21,7 @@ export {
   InstalledExtensionSchema,
   InstallExtensionInputSchema,
   type ExtensionModule,
+  type ExtensionSetupContribution,
   type InstalledExtension,
   type InstallExtensionInput,
   setMFImplementation,
diff --git a/scripts/core-release-lib.mjs b/scripts/core-release-lib.mjs
index b46ebbd..ccc45b9 100644
--- a/scripts/core-release-lib.mjs
+++ b/scripts/core-release-lib.mjs
@@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises'
 
 const stableImagePattern = /^ghcr\.io\/inkcre\/core-py:stable$/
 const digestPattern = /^ghcr\.io\/inkcre\/core-py@sha256:[0-9a-f]{64}$/
+const localImageIdPattern = /^sha256:[0-9a-f]{64}$/
 const sourceRevisionPattern = /^[0-9a-f]{40}$/
 const sha256Pattern = /^[0-9a-f]{64}$/
 
@@ -108,7 +109,7 @@ export function resolveCoreRelease(runDocker, stableImage) {
 }
 
 export function inspectCoreRelease(runDocker, image) {
-  if (!digestPattern.test(image)) {
+  if (!digestPattern.test(image) && !localImageIdPattern.test(image)) {
     throw new Error(`core release must be digest-pinned: ${image}`)
   }
   const manifest = validateSchemaManifest(
diff --git a/scripts/core-release-lib.test.mjs b/scripts/core-release-lib.test.mjs
index afabcaa..ab4fa03 100644
--- a/scripts/core-release-lib.test.mjs
+++ b/scripts/core-release-lib.test.mjs
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import { test } from 'vitest'
 
 import {
+  inspectCoreRelease,
   selectImmutableDigest,
   validateCoreReleaseConfig,
   validateRuntimeContract,
@@ -85,6 +86,28 @@ test('binds runtime identity to the schema manifest', () => {
   )
 })
 
+test('accepts an immutable local image id for feature-contract synchronization', () => {
+  const runtimeContract = {
+    format: 1,
+    revision: manifest.contract_revision,
+    source_revision: sourceRevision,
+    protocol: { schema: 'inkcre' },
+    jwt: { algorithm: 'HS256', role: 'authenticated' },
+  }
+  const runDocker = (args) => {
+    if (args.includes('schema')) return JSON.stringify(manifest)
+    if (args.includes('/app/database-contract/runtime-contract.json')) {
+      return JSON.stringify(runtimeContract)
+    }
+    throw new Error(`unexpected Docker command: ${args.join(' ')}`)
+  }
+
+  assert.equal(
+    inspectCoreRelease(runDocker, `sha256:${digest}`).runtime_contract.revision,
+    manifest.contract_revision
+  )
+})
+
 test('rejects artifact content that differs from the manifest', () => {
   assert.throws(() => verifyArtifact(Buffer.from('wrong'), manifest.schema, 'schema'), /manifest/)
 })
diff --git a/scripts/twitter-mf-distribution.test.mjs b/scripts/twitter-mf-distribution.test.mjs
index 2b46bce..7721957 100644
--- a/scripts/twitter-mf-distribution.test.mjs
+++ b/scripts/twitter-mf-distribution.test.mjs
@@ -45,7 +45,7 @@ async function createFixture() {
     shared: [
       {
         name: '@inkcre/core',
-        requiredVersion: '^0.1.0',
+        requiredVersion: '^0.1.1',
         assets: {
           js: { sync: ['assets/shared.js'], async: [] },
           css: { sync: [], async: [] },
@@ -64,13 +64,13 @@ async function createFixture() {
   }
   const extensionPackage = {
     name: '@inkcre/ext-twitter',
-    version: '0.1.1',
+    version: '0.2.0',
     inkcre: {
       name: 'inkcre/twitter',
       nickname: 'Twitter',
       module_federation: {
         host_sdk: '@inkcre/core',
-        host_sdk_version: '>=0.1.0 <0.2.0',
+        host_sdk_version: '>=0.1.1 <0.2.0',
       },
     },
   }
@@ -82,7 +82,7 @@ async function createFixture() {
     ),
     writeFile(path.join(artifactDirectory, 'mf-manifest.json'), `${JSON.stringify(manifest)}\n`),
     writeFile(packagePath, `${JSON.stringify(extensionPackage)}\n`),
-    writeFile(corePackagePath, `${JSON.stringify({ name: '@inkcre/core', version: '0.1.0' })}\n`),
+    writeFile(corePackagePath, `${JSON.stringify({ name: '@inkcre/core', version: '0.1.1' })}\n`),
   ])
 
   return {
@@ -104,10 +104,10 @@ test('Twitter produces a native manifest with a Registry-relocatable base and ty
 
   assert.equal(extensionPackage.inkcre.name, 'inkcre/twitter')
   assert.equal(extensionPackage.inkcre.nickname, 'Twitter')
-  assert.equal(extensionPackage.version, '0.1.1')
+  assert.equal(extensionPackage.version, '0.2.0')
   assert.deepEqual(extensionPackage.inkcre.module_federation, {
     host_sdk: '@inkcre/core',
-    host_sdk_version: '>=0.1.0 <0.2.0',
+    host_sdk_version: '>=0.1.1 <0.2.0',
   })
   assert.equal(twitterFederationOptions.manifest, true)
   assert.equal(twitterArtifactBase, './')
@@ -145,10 +145,10 @@ test('builds the frozen native prepare payload with distribution-owned provenanc
       }),
       {
         nickname: 'Twitter',
-        version: '0.1.1',
+        version: '0.2.0',
         module_federation: {
           host_sdk: '@inkcre/core',
-          host_sdk_version: '>=0.1.0 <0.2.0',
+          host_sdk_version: '>=0.1.1 <0.2.0',
           source_repository: 'https://github.com/inkcre/client-web',
           source_revision: 'a'.repeat(40),
           build_id: 'client-web-mf-build-123',
@@ -174,7 +174,7 @@ test('verifies Registry publicPath materialization and exact native public bytes
   const fixture = await createFixture()
   try {
     const publicPrefix =
-      'https://registry.example/extensions/inkcre/twitter/0.1.1/module-federation/'
+      'https://registry.example/extensions/inkcre/twitter/0.2.0/module-federation/'
     const publicManifest = structuredClone(fixture.manifest)
     publicManifest.metaData.publicPath = publicPrefix
     const fetchImplementation = async (input) => {
@@ -184,17 +184,17 @@ test('verifies Registry publicPath materialization and exact native public bytes
         'cache-control': 'public, max-age=31536000, immutable',
         etag: '"snapshot"',
       }
-      if (url.pathname.endsWith('/v1/extensions/inkcre/twitter/releases/0.1.1')) {
+      if (url.pathname.endsWith('/v1/extensions/inkcre/twitter/releases/0.2.0')) {
         return Response.json(
           {
             name: 'inkcre/twitter',
             nickname: 'Twitter',
-            version: '0.1.1',
+            version: '0.2.0',
             state: 'published',
             module_federation: {
-              manifest_url: '/extensions/inkcre/twitter/0.1.1/module-federation/mf-manifest.json',
+              manifest_url: '/extensions/inkcre/twitter/0.2.0/module-federation/mf-manifest.json',
               host_sdk: '@inkcre/core',
-              host_sdk_version: '>=0.1.0 <0.2.0',
+              host_sdk_version: '>=0.1.1 <0.2.0',
             },
           },
           { headers }

From c454d207a0ad1f8748d68f4ca43a70e0a65dbab0 Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Thu, 13 Aug 2026 18:05:20 +0800
Subject: [PATCH 2/7] fix(preview): project current twitter release version

---
 scripts/twitter-mf-distribution.test.mjs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/scripts/twitter-mf-distribution.test.mjs b/scripts/twitter-mf-distribution.test.mjs
index 2cc703c..558780f 100644
--- a/scripts/twitter-mf-distribution.test.mjs
+++ b/scripts/twitter-mf-distribution.test.mjs
@@ -180,7 +180,7 @@ test('builds and assembles a read-only native Twitter preview projection', async
 
     const publicRelease = JSON.parse(
       await readFile(
-        path.join(pagesDirectory, 'v1/extensions/inkcre/twitter/releases/0.1.1'),
+        path.join(pagesDirectory, `v1/extensions/inkcre/twitter/releases/${release.version}`),
         'utf8'
       )
     )
@@ -189,7 +189,7 @@ test('builds and assembles a read-only native Twitter preview projection', async
       await readFile(
         path.join(
           pagesDirectory,
-          'extensions/inkcre/twitter/0.1.1/module-federation/remoteEntry.js'
+          `extensions/inkcre/twitter/${release.version}/module-federation/remoteEntry.js`
         ),
         'utf8'
       ),
@@ -199,14 +199,14 @@ test('builds and assembles a read-only native Twitter preview projection', async
       await readFile(
         path.join(
           pagesDirectory,
-          'extensions/inkcre/twitter/0.1.1/module-federation/mf-manifest.json'
+          `extensions/inkcre/twitter/${release.version}/module-federation/mf-manifest.json`
         ),
         'utf8'
       )
     )
     assert.equal(
       publicManifest.metaData.publicPath,
-      'https://preview.example/extensions/inkcre/twitter/0.1.1/module-federation/'
+      `https://preview.example/extensions/inkcre/twitter/${release.version}/module-federation/`
     )
     assert.match(await readFile(path.join(pagesDirectory, '_headers'), 'utf8'), /no-store/)
   } finally {

From 608edbd5bf8493676e2bf270efcb4031f5004edd Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Thu, 13 Aug 2026 18:20:37 +0800
Subject: [PATCH 3/7] fix(extension): label setup wizard entry

---
 apps/client-web/src/locales/messages/en.json    | 2 ++
 apps/client-web/src/locales/messages/zh-CN.json | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/apps/client-web/src/locales/messages/en.json b/apps/client-web/src/locales/messages/en.json
index 750168a..dfcdb73 100644
--- a/apps/client-web/src/locales/messages/en.json
+++ b/apps/client-web/src/locales/messages/en.json
@@ -80,6 +80,8 @@
     "namePlaceholder": "namespace/name, for example inkcre/twitter",
     "version": "Version",
     "versionPlaceholder": "exact version, for example 0.1.0",
+    "setup": "Set Up",
+    "setupTitle": "Set Up {name}",
     "editConfig": "Edit Config",
     "editConfigTitle": "Edit Extension Configuration",
     "changeVersion": "Change Version",
diff --git a/apps/client-web/src/locales/messages/zh-CN.json b/apps/client-web/src/locales/messages/zh-CN.json
index 4f0bfd4..3db464f 100644
--- a/apps/client-web/src/locales/messages/zh-CN.json
+++ b/apps/client-web/src/locales/messages/zh-CN.json
@@ -80,6 +80,8 @@
     "namePlaceholder": "namespace/name，例如 inkcre/twitter",
     "version": "版本",
     "versionPlaceholder": "精确版本，例如 0.1.0",
+    "setup": "设置",
+    "setupTitle": "设置 {name}",
     "editConfig": "编辑配置",
     "editConfigTitle": "编辑扩展配置",
     "changeVersion": "变更版本",

From f25e684be7dd52a8bd3f43bccc599a06542399be Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Thu, 13 Aug 2026 18:28:59 +0800
Subject: [PATCH 4/7] fix(extension): await runtime restore before listing

---
 apps/client-web/src/core.spec.ts              | 40 ++++++++++++++++++-
 apps/client-web/src/core.ts                   | 14 +++++++
 apps/client-web/src/main.ts                   |  4 +-
 .../src/views/extensions/extensions.vue       | 12 +++++-
 4 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/apps/client-web/src/core.spec.ts b/apps/client-web/src/core.spec.ts
index 3baaf32..42f5202 100644
--- a/apps/client-web/src/core.spec.ts
+++ b/apps/client-web/src/core.spec.ts
@@ -1,5 +1,10 @@
-import { describe, expect, it } from 'vitest'
-import { shouldLoadClientConfigAtBootstrap } from './core'
+import { describe, expect, it, vi } from 'vitest'
+import { configStore, type ExtensionStatePort } from '@inkcre/core'
+import {
+  initializeExtensionHost,
+  shouldLoadClientConfigAtBootstrap,
+  startExtensionHost,
+} from './core'
 
 describe('client configuration bootstrap', () => {
   it('keeps Settings reachable without contacting a configured Peer', () => {
@@ -12,3 +17,34 @@ describe('client configuration bootstrap', () => {
     expect(shouldLoadClientConfigAtBootstrap('/extensions')).toBe(true)
   })
 })
+
+describe('Extension Host bootstrap', () => {
+  it('shares the initial runtime restore with the Extension management view', async () => {
+    const previousPeerId = configStore.metaConfig.INKCRE_CLIENT_ID
+    configStore.metaConfig.INKCRE_CLIENT_ID = '00000000-0000-4000-8000-000000000002'
+    const list = vi.fn().mockResolvedValue([])
+    const unused = vi.fn(() => {
+      throw new Error('not used')
+    })
+    initializeExtensionHost({
+      list,
+      get: unused,
+      install: unused,
+      updateConfig: unused,
+      changeVersion: unused,
+      setPeerEnabled: unused,
+      uninstall: unused,
+    } satisfies ExtensionStatePort)
+
+    try {
+      const appStartup = startExtensionHost()
+      const viewStartup = startExtensionHost()
+
+      expect(viewStartup).toBe(appStartup)
+      await viewStartup
+      expect(list).toHaveBeenCalledOnce()
+    } finally {
+      configStore.metaConfig.INKCRE_CLIENT_ID = previousPeerId
+    }
+  })
+})
diff --git a/apps/client-web/src/core.ts b/apps/client-web/src/core.ts
index 65a8e45..ce432e5 100644
--- a/apps/client-web/src/core.ts
+++ b/apps/client-web/src/core.ts
@@ -53,8 +53,10 @@ export function setupResolvers(): void {
 // ============================================================================
 
 let extensionHost: WebExtensionHost | null = null
+let extensionHostStartup: Promise<void> | null = null
 
 export function initializeExtensionHost(state: ExtensionStatePort): WebExtensionHost {
+  extensionHostStartup = null
   extensionHost = new WebExtensionHost({
     state,
     releases: new RegistryExtensionReleaseReader(
@@ -74,6 +76,18 @@ export function getExtensionHost(): WebExtensionHost {
   return extensionHost
 }
 
+/** Share one initial runtime restore across the app shell and Extension management view. */
+export function startExtensionHost(): Promise<void> {
+  if (extensionHostStartup) return extensionHostStartup
+
+  const startup = getExtensionHost().startup()
+  extensionHostStartup = startup.catch((error: unknown) => {
+    extensionHostStartup = null
+    throw error
+  })
+  return extensionHostStartup
+}
+
 // ============================================================================
 // Module Federation
 // ============================================================================
diff --git a/apps/client-web/src/main.ts b/apps/client-web/src/main.ts
index b2f8653..b2aafcd 100644
--- a/apps/client-web/src/main.ts
+++ b/apps/client-web/src/main.ts
@@ -24,9 +24,9 @@ await initializeCore({
 })
 app.mount('#app')
 
-import { getExtensionHost } from './core'
+import { getExtensionHost, startExtensionHost } from './core'
 const extensionHost = getExtensionHost()
-extensionHost.startup().catch((error) => {
+startExtensionHost().catch((error) => {
   console.error('[Web Extension Host] Startup failed:', error)
 })
 
diff --git a/apps/client-web/src/views/extensions/extensions.vue b/apps/client-web/src/views/extensions/extensions.vue
index 748dc7d..2f47d44 100644
--- a/apps/client-web/src/views/extensions/extensions.vue
+++ b/apps/client-web/src/views/extensions/extensions.vue
@@ -4,7 +4,7 @@ import extensionCard from '@/components/extension/extensionCard/extensionCard.vu
 import installExtension from '@/components/extension/installExtension/installExtension.vue'
 import { InkLoading } from '@inkcre/ui-web'
 import { configStore, type InstalledExtension } from '@inkcre/core'
-import { getExtensionHost } from '@/core'
+import { getExtensionHost, startExtensionHost } from '@/core'
 import { useI18n } from 'vue-i18n'
 
 // --- data ---
@@ -29,7 +29,15 @@ const refreshExtensions = async () => {
   }
 }
 
-onMounted(() => void refreshExtensions())
+onMounted(async () => {
+  try {
+    await startExtensionHost()
+  } catch {
+    // The app shell owns runtime-startup reporting. The installed list remains a
+    // useful recovery surface even when one enabled Extension fails to start.
+  }
+  await refreshExtensions()
+})
 
 // --- methods ---
 const onInstallExtension = () => {

From 0e60499e45018c27f4a26b64695597f504e553c7 Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Fri, 14 Aug 2026 11:17:52 +0800
Subject: [PATCH 5/7] fix(settings): restore connected Client configuration

---
 apps/client-web/src/core.spec.ts              |  6 +-
 apps/client-web/src/core.ts                   |  2 +-
 apps/client-web/src/locales/messages/en.json  |  4 +
 .../src/locales/messages/zh-CN.json           |  4 +
 .../src/views/extensions/extensions.vue       |  2 +-
 .../src/views/settings/settings.scss          |  9 ++
 .../src/views/settings/settings.vue           | 62 ++++++++++---
 packages/core/src/auth/store.ts               | 30 +++----
 packages/core/src/base/db-api.ts              |  6 +-
 packages/core/src/client/client.test.ts       | 71 +++++++++++++++
 packages/core/src/client/client.ts            | 87 ++++++++++++++++---
 packages/core/src/config/index.ts             |  2 +-
 packages/core/src/config/schema.test.ts       | 21 +++--
 packages/core/src/config/schema.ts            | 24 ++++-
 packages/core/src/config/store.test.ts        | 72 +++++++++++++++
 packages/core/src/config/store.ts             | 26 ++++--
 packages/core/src/extension/host.ts           |  2 +-
 packages/core/src/index.ts                    |  2 +-
 .../10-evidence.md                            |  2 +-
 tests/e2e/browser-extension.spec.ts           |  2 +-
 tests/e2e/peer-database.spec.ts               |  2 +-
 21 files changed, 373 insertions(+), 65 deletions(-)
 create mode 100644 packages/core/src/config/store.test.ts

diff --git a/apps/client-web/src/core.spec.ts b/apps/client-web/src/core.spec.ts
index 42f5202..cca0927 100644
--- a/apps/client-web/src/core.spec.ts
+++ b/apps/client-web/src/core.spec.ts
@@ -20,8 +20,8 @@ describe('client configuration bootstrap', () => {
 
 describe('Extension Host bootstrap', () => {
   it('shares the initial runtime restore with the Extension management view', async () => {
-    const previousPeerId = configStore.metaConfig.INKCRE_CLIENT_ID
-    configStore.metaConfig.INKCRE_CLIENT_ID = '00000000-0000-4000-8000-000000000002'
+    const previousPeerId = configStore.metaConfig.client_id
+    configStore.metaConfig.client_id = '00000000-0000-4000-8000-000000000002'
     const list = vi.fn().mockResolvedValue([])
     const unused = vi.fn(() => {
       throw new Error('not used')
@@ -44,7 +44,7 @@ describe('Extension Host bootstrap', () => {
       await viewStartup
       expect(list).toHaveBeenCalledOnce()
     } finally {
-      configStore.metaConfig.INKCRE_CLIENT_ID = previousPeerId
+      configStore.metaConfig.client_id = previousPeerId
     }
   })
 })
diff --git a/apps/client-web/src/core.ts b/apps/client-web/src/core.ts
index ce432e5..31f4fdd 100644
--- a/apps/client-web/src/core.ts
+++ b/apps/client-web/src/core.ts
@@ -63,7 +63,7 @@ export function initializeExtensionHost(state: ExtensionStatePort): WebExtension
       () => configStore.clientConfig.extension_registry_url
     ),
     moduleFederation: getMFImplementation,
-    currentPeerId: () => configStore.metaConfig.INKCRE_CLIENT_ID,
+    currentPeerId: () => configStore.metaConfig.client_id,
     hostSdkVersion: corePackageJson.version,
   })
   return extensionHost
diff --git a/apps/client-web/src/locales/messages/en.json b/apps/client-web/src/locales/messages/en.json
index dfcdb73..8ca35c0 100644
--- a/apps/client-web/src/locales/messages/en.json
+++ b/apps/client-web/src/locales/messages/en.json
@@ -29,10 +29,14 @@
     "extensionRegistryUrl": "Extension Registry URL",
     "jwtSecret": "JWT Secret",
     "clientId": "Client ID",
+    "clientIdGenerated": "Generated and retained by this browser origin.",
+    "clientConfig": "Client Configuration",
+    "clientConfigNotice": "Saving verifies the database connection, registers this browser Client if needed, and persists these settings.",
     "languageLabel": "Language",
     "languageDescription": "Select your preferred language",
     "saveConfig": "Save",
     "saveSuccess": "Configuration saved successfully",
+    "saveError": "Failed to save configuration",
     "resetConfig": "Reset",
     "resetConfirmTitle": "Reset Configuration",
     "resetConfirmMessage": "Are you sure you want to reset all settings to default? This action cannot be undone.",
diff --git a/apps/client-web/src/locales/messages/zh-CN.json b/apps/client-web/src/locales/messages/zh-CN.json
index 3db464f..ca72993 100644
--- a/apps/client-web/src/locales/messages/zh-CN.json
+++ b/apps/client-web/src/locales/messages/zh-CN.json
@@ -29,10 +29,14 @@
     "extensionRegistryUrl": "扩展注册表地址",
     "jwtSecret": "JWT 密钥",
     "clientId": "客户端 ID",
+    "clientIdGenerated": "由当前浏览器来源自动生成并持久保存。",
+    "clientConfig": "客户端配置",
+    "clientConfigNotice": "保存时会验证数据库连接，并在需要时注册当前浏览器客户端，然后持久化这些设置。",
     "languageLabel": "语言",
     "languageDescription": "选择您的首选语言",
     "saveConfig": "保存",
     "saveSuccess": "配置保存成功",
+    "saveError": "配置保存失败",
     "resetConfig": "重置",
     "resetConfirmTitle": "重置配置",
     "resetConfirmMessage": "确定要重置所有设置为默认值吗？此操作无法撤销。",
diff --git a/apps/client-web/src/views/extensions/extensions.vue b/apps/client-web/src/views/extensions/extensions.vue
index 2f47d44..9642809 100644
--- a/apps/client-web/src/views/extensions/extensions.vue
+++ b/apps/client-web/src/views/extensions/extensions.vue
@@ -9,7 +9,7 @@ import { useI18n } from 'vue-i18n'
 
 // --- data ---
 const { t } = useI18n()
-const currentPeerId = configStore.metaConfig.INKCRE_CLIENT_ID
+const currentPeerId = configStore.metaConfig.client_id
 const extensions = ref<InstalledExtension[]>([])
 const extensionsLoading = ref(false)
 const error = ref<string | null>(null)
diff --git a/apps/client-web/src/views/settings/settings.scss b/apps/client-web/src/views/settings/settings.scss
index d8f83b9..65ea714 100644
--- a/apps/client-web/src/views/settings/settings.scss
+++ b/apps/client-web/src/views/settings/settings.scss
@@ -25,6 +25,7 @@
   }
 
   &__secret,
+  &__identity,
   &__locale {
     display: flex;
     flex-direction: column;
@@ -43,6 +44,14 @@
     }
   }
 
+  &__identity code {
+    padding: sys-var('space', 'sm');
+    overflow-wrap: anywhere;
+    color: sys-var('color', 'text', 'base');
+    background: sys-var('color', 'surface', 'subtle');
+    border: 1px solid sys-var('color', 'border', 'base');
+  }
+
   &__actions {
     display: flex;
     gap: sys-var('space', 'md');
diff --git a/apps/client-web/src/views/settings/settings.vue b/apps/client-web/src/views/settings/settings.vue
index a332af6..9f045ba 100644
--- a/apps/client-web/src/views/settings/settings.vue
+++ b/apps/client-web/src/views/settings/settings.vue
@@ -1,8 +1,14 @@
 <script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { InkForm, InkInput, InkButton, InkDoubleCheck } from '@inkcre/ui-web'
-import { configStore, MetaConfigSchema, type MetaConfig } from '@inkcre/core'
+import {
+  ClientConfigSchema,
+  configStore,
+  MetaConfigSchema,
+  type ClientConfig,
+  type MetaConfig,
+} from '@inkcre/core'
 import { setLocale, SUPPORT_LOCALES, LOCALE_NAMES, type SupportLocale } from '@/locales'
 import i18n from '@/locales'
 
@@ -10,6 +16,7 @@ const { t } = useI18n()
 
 // Local reactive copy of metaConfig for form editing
 const metaFormConfig = reactive<MetaConfig>({ ...configStore.metaConfig })
+const clientFormConfig = reactive<ClientConfig>(ClientConfigSchema.parse(configStore.clientConfig))
 
 // Synchronize metaFormConfig with configStore.metaConfig
 watch(
@@ -19,6 +26,21 @@ watch(
   },
   { deep: true }
 )
+watch(
+  () => configStore.clientConfig,
+  (newClientConfig) => {
+    Object.assign(clientFormConfig, ClientConfigSchema.parse(newClientConfig))
+  },
+  { deep: true }
+)
+
+onMounted(async () => {
+  if (!configStore.metaConfig.INKCRE_PGREST_URL || !configStore.metaConfig.INKCRE_JWT_SECRET) {
+    return
+  }
+  await configStore.loadClientConfig()
+  Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
+})
 
 // Current locale (computed for v-model)
 const currentLocale = computed({
@@ -31,14 +53,15 @@ const currentLocale = computed({
 // Save config
 const onSave = async () => {
   try {
-    const validated = MetaConfigSchema.parse(metaFormConfig)
-    Object.assign(configStore.metaConfig, validated)
-    await configStore.saveMeta()
-    await configStore.loadClientConfig()
+    const validatedMeta = MetaConfigSchema.parse(metaFormConfig)
+    const validatedClient = ClientConfigSchema.parse(clientFormConfig)
+    await configStore.connectAndSave(validatedMeta, validatedClient)
+    Object.assign(metaFormConfig, configStore.metaConfig)
+    Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
     alert(t('settings.saveSuccess'))
   } catch (error) {
     console.error('Failed to save config:', error)
-    alert('Failed to save configuration')
+    alert(error instanceof Error ? error.message : t('settings.saveError'))
   }
 }
 
@@ -46,6 +69,7 @@ const onSave = async () => {
 const onReset = async () => {
   await configStore.resetMeta()
   Object.assign(metaFormConfig, configStore.metaConfig)
+  Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
 }
 
 // Export config
@@ -55,7 +79,7 @@ const onExport = () => {
     containsCredential: false,
     metaConfig: {
       INKCRE_PGREST_URL: configStore.metaConfig.INKCRE_PGREST_URL,
-      INKCRE_CLIENT_ID: configStore.metaConfig.INKCRE_CLIENT_ID,
+      client_id: configStore.metaConfig.client_id,
     },
   }
   const configJson = JSON.stringify(portableConfig, null, 2)
@@ -89,10 +113,9 @@ const onFileSelected = async (event: Event) => {
         ...configStore.metaConfig,
         ...imported.metaConfig,
       })
-      Object.assign(configStore.metaConfig, validated)
-      await configStore.saveMeta()
-      await configStore.loadClientConfig()
+      await configStore.connectAndSave(validated, ClientConfigSchema.parse(clientFormConfig))
       Object.assign(metaFormConfig, configStore.metaConfig)
+      Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
       alert(t('settings.saveSuccess'))
     } catch (error) {
       console.error('Failed to import config:', error)
@@ -133,10 +156,21 @@ const onFileSelected = async (event: Event) => {
         <small>{{ t('settings.jwtStoredLocally') }}</small>
       </label>
 
+      <div class="settings-view__identity">
+        <span>{{ t('settings.clientId') }}</span>
+        <code>{{ metaFormConfig.client_id }}</code>
+        <small>{{ t('settings.clientIdGenerated') }}</small>
+      </div>
+
+      <!-- Client Configuration -->
+      <h2 class="settings-view__section-title">
+        {{ t('settings.clientConfig') }}
+      </h2>
+      <p class="settings-view__notice">{{ t('settings.clientConfigNotice') }}</p>
       <InkInput
-        v-model="metaFormConfig.INKCRE_CLIENT_ID"
-        :label="t('settings.clientId')"
-        placeholder="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+        v-model="clientFormConfig.extension_registry_url"
+        :label="t('settings.extensionRegistryUrl')"
+        placeholder="https://..."
       />
 
       <!-- Language Selection -->
diff --git a/packages/core/src/auth/store.ts b/packages/core/src/auth/store.ts
index 9cebdff..a3d9a79 100644
--- a/packages/core/src/auth/store.ts
+++ b/packages/core/src/auth/store.ts
@@ -3,6 +3,20 @@ import { SignJWT } from 'jose'
 import { configStore } from '../config'
 import { peerJwtContract } from '../database'
 
+export async function signDatabaseToken(jwtSecret: string): Promise<string> {
+  if (!jwtSecret) throw new Error('JWT_SECRET not configured')
+
+  const secret = new TextEncoder().encode(jwtSecret)
+  const issuedAt = Math.floor(Date.now() / 1000)
+  return new SignJWT({ role: peerJwtContract.role })
+    .setProtectedHeader({ alg: peerJwtContract.algorithm })
+    .setIssuedAt(issuedAt)
+    .setExpirationTime(issuedAt + peerJwtContract.maximum_lifetime_seconds)
+    .setIssuer(peerJwtContract.issuer)
+    .setAudience(peerJwtContract.audience)
+    .sign(secret)
+}
+
 /**
  * Create an auth store instance.
  * Returns reactive token and token management functions.
@@ -11,22 +25,8 @@ export function createAuthStore(configStoreIns = configStore) {
   const token = ref<string | undefined>(undefined)
 
   async function newToken(): Promise<string> {
-    if (!configStoreIns.metaConfig.INKCRE_JWT_SECRET) {
-      throw new Error('JWT_SECRET not configured')
-    }
-
     try {
-      const secret = new TextEncoder().encode(configStoreIns.metaConfig.INKCRE_JWT_SECRET)
-      const issuedAt = Math.floor(Date.now() / 1000)
-      const signedToken = await new SignJWT({
-        role: peerJwtContract.role,
-      })
-        .setProtectedHeader({ alg: peerJwtContract.algorithm })
-        .setIssuedAt(issuedAt)
-        .setExpirationTime(issuedAt + peerJwtContract.maximum_lifetime_seconds)
-        .setIssuer(peerJwtContract.issuer)
-        .setAudience(peerJwtContract.audience)
-        .sign(secret)
+      const signedToken = await signDatabaseToken(configStoreIns.metaConfig.INKCRE_JWT_SECRET)
 
       token.value = signedToken
       return signedToken
diff --git a/packages/core/src/base/db-api.ts b/packages/core/src/base/db-api.ts
index 862ead2..dbd76e1 100644
--- a/packages/core/src/base/db-api.ts
+++ b/packages/core/src/base/db-api.ts
@@ -6,6 +6,7 @@ import type { Database, InkcreSchema, RelationName, RelationRow } from '../datab
 
 type RelationInsert<Relation extends RelationName> = InkcreSchema['Tables'][Relation]['Insert']
 type RelationUpdate<Relation extends RelationName> = InkcreSchema['Tables'][Relation]['Update']
+export type DatabaseTokenProvider = () => Promise<string>
 
 function encodeTransportValue<Value>(value: unknown): Value {
   const encoded = JSON.stringify(value)
@@ -57,13 +58,14 @@ export class DBAPIClient<
     protected relation: Relation,
     protected defSchema?: { parse(input: unknown): DT },
     public schemaName: 'inkcre' = 'inkcre',
-    baseUrl: string = ''
+    baseUrl: string = '',
+    tokenProvider: DatabaseTokenProvider = () => authStore.getToken()
   ) {
     super(baseUrl, {
       schema: schemaName,
       // Custom fetch to dynamically inject auth token on each request
       fetch: async (input, init) => {
-        const token = await authStore.getToken()
+        const token = await tokenProvider()
         const headers = new Headers(init?.headers)
         headers.set('Authorization', `Bearer ${token}`)
         return fetch(input, { ...init, headers })
diff --git a/packages/core/src/client/client.test.ts b/packages/core/src/client/client.test.ts
index 12d04ae..ea9f5f1 100644
--- a/packages/core/src/client/client.test.ts
+++ b/packages/core/src/client/client.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { authStore } from '../auth'
+import { ClientConfigSchema, MetaConfigSchema } from '../config'
 import { Client } from './client'
 
 afterEach(() => {
@@ -107,3 +108,73 @@ describe('Client.request', () => {
     await expect(client.get('/twitter/setup')).rejects.toThrow('Connect a Twitter account first')
   })
 })
+
+describe('Client.connect', () => {
+  it('validates the candidate database before registering a missing browser Client', async () => {
+    const clientId = '00000000-0000-4000-8000-000000000002'
+    const fetch = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+      if (init?.method === 'GET') {
+        return Response.json([], {
+          headers: { 'Content-Range': '*/0' },
+        })
+      }
+      if (init?.method === 'POST') {
+        return Response.json(
+          {
+            id: clientId,
+            name: 'client-web',
+            labels: ['web'],
+            rest_api_url: null,
+            config: { extension_registry_url: 'https://registry.inkcre.dev/' },
+            config_schema: {},
+            created_at: '2026-08-14T00:00:00Z',
+          },
+          { status: 201 }
+        )
+      }
+      return Response.json({ message: 'unexpected request' }, { status: 500 })
+    })
+    vi.stubGlobal('fetch', fetch)
+
+    const connected = await Client.connect(
+      MetaConfigSchema.parse({
+        INKCRE_PGREST_URL: 'https://database.example.test/',
+        INKCRE_JWT_SECRET: 'test-secret',
+        client_id: clientId,
+      }),
+      ClientConfigSchema.parse({
+        extension_registry_url: 'https://registry.inkcre.dev/',
+      })
+    )
+
+    expect(connected.id).toBe(clientId)
+    expect(fetch).toHaveBeenCalledTimes(2)
+    const registration = fetch.mock.calls[1]?.[1]
+    expect(registration?.method).toBe('POST')
+    expect(JSON.parse(String(registration?.body))).toMatchObject({
+      id: clientId,
+      name: 'client-web',
+      labels: ['web'],
+      config: { extension_registry_url: 'https://registry.inkcre.dev/' },
+    })
+  })
+
+  it('surfaces a candidate database authentication failure', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () =>
+        Response.json({ code: 'PGRST301', message: 'JWT verification failed' }, { status: 401 })
+      )
+    )
+
+    await expect(
+      Client.connect(
+        MetaConfigSchema.parse({
+          INKCRE_PGREST_URL: 'https://database.example.test/',
+          INKCRE_JWT_SECRET: 'wrong-secret',
+        }),
+        ClientConfigSchema.parse({})
+      )
+    ).rejects.toThrow('Client database connection failed: JWT verification failed')
+  })
+})
diff --git a/packages/core/src/client/client.ts b/packages/core/src/client/client.ts
index ac762ac..ec039c2 100644
--- a/packages/core/src/client/client.ts
+++ b/packages/core/src/client/client.ts
@@ -2,8 +2,8 @@ import { z } from 'zod'
 import { Z } from 'zod-class'
 import { DBAPIClient, APIError } from '../base/db-api'
 import { makeStringProp, makeObjectProp } from '../utils/vue-props'
-import { authStore } from '../auth'
-import { configStore } from '../config'
+import { authStore, signDatabaseToken } from '../auth'
+import { ClientConfigSchema, configStore, type ClientConfig, type MetaConfig } from '../config'
 
 export type ClientRef = string
 export const makeClientProp = (v?: any) => makeObjectProp<Client>(v)
@@ -64,16 +64,72 @@ export class Client extends Z.class({
     }))
   }
 
+  /** Get the browser-owned Client from bootstrap configuration. */
+  static async getSelf(): Promise<Client> {
+    return Client.get(configStore.metaConfig.client_id)
+  }
+
   /**
-   * Get the self/core client from config (INKCRE_CLIENT_ID).
-   * This client is used for Core API requests.
+   * Prove one candidate bootstrap configuration and persist this browser's
+   * typed Client configuration. The candidate connection is isolated from the
+   * currently active application configuration.
    */
-  static async getSelf(): Promise<Client> {
-    const clientId = configStore.metaConfig.INKCRE_CLIENT_ID
-    if (!clientId) {
-      throw new Error('INKCRE_CLIENT_ID is not configured')
+  static async connect(meta: MetaConfig, config: ClientConfig): Promise<Client> {
+    const candidate = new DBAPIClient<'clients', Client>(
+      'clients',
+      Client,
+      'inkcre',
+      meta.INKCRE_PGREST_URL,
+      () => signDatabaseToken(meta.INKCRE_JWT_SECRET)
+    )
+    const existingResponse = await candidate.from().select().eq('id', meta.client_id).maybeSingle()
+    if (existingResponse.error) {
+      throw new APIError(
+        `Client database connection failed: ${existingResponse.error.message}`,
+        existingResponse.status,
+        existingResponse.error
+      )
     }
-    return Client.get(clientId)
+
+    const parsedConfig = ClientConfigSchema.parse(config)
+    if (existingResponse.data) {
+      const updateResponse = await candidate
+        .update({
+          config: parsedConfig,
+          config_schema: z.toJSONSchema(ClientConfigSchema),
+        })
+        .eq('id', meta.client_id)
+        .select()
+        .single()
+      if (updateResponse.error) {
+        throw new APIError(
+          `Client configuration save failed: ${updateResponse.error.message}`,
+          updateResponse.status,
+          updateResponse.error
+        )
+      }
+      return Client.parse(updateResponse.data)
+    }
+
+    const createResponse = await candidate
+      .insert({
+        id: meta.client_id,
+        name: 'client-web',
+        labels: ['web'],
+        rest_api_url: null,
+        config: parsedConfig,
+        config_schema: z.toJSONSchema(ClientConfigSchema),
+      })
+      .select()
+      .single()
+    if (createResponse.error) {
+      throw new APIError(
+        `Client registration failed: ${createResponse.error.message}`,
+        createResponse.status,
+        createResponse.error
+      )
+    }
+    return Client.parse(createResponse.data)
   }
 
   /**
@@ -279,7 +335,18 @@ export class Client extends Z.class({
    * Save only the config field to the database
    */
   async saveConfig(): Promise<void> {
-    await Client.dbApi.upsert({ id: this.id, config: this.config }).select().single()
+    const response = await Client.dbApi
+      .update({ config: this.config, config_schema: this.config_schema })
+      .eq('id', this.id)
+      .select()
+      .single()
+    if (response.error) {
+      throw new APIError(
+        `Client configuration save failed: ${response.error.message}`,
+        response.status,
+        response.error
+      )
+    }
   }
 }
 
diff --git a/packages/core/src/config/index.ts b/packages/core/src/config/index.ts
index fab9deb..bb80338 100644
--- a/packages/core/src/config/index.ts
+++ b/packages/core/src/config/index.ts
@@ -7,7 +7,7 @@
  * **MetaConfig** (State: `metaConfig`): Contains bootstrap configuration needed to initialize the app
  * - INKCRE_PGREST_URL: PostgreSQL/PostgREST base URL
  * - INKCRE_JWT_SECRET: JWT signing secret
- * - INKCRE_CLIENT_ID: Current client UUID
+ * - client_id: Browser-owned Client UUID generated on first initialization
  *
  * **ClientConfig** (State: `config`): Contains runtime application configuration
  * - extension_registry_url: Extension registry URL
diff --git a/packages/core/src/config/schema.test.ts b/packages/core/src/config/schema.test.ts
index f3db28d..8c5190c 100644
--- a/packages/core/src/config/schema.test.ts
+++ b/packages/core/src/config/schema.test.ts
@@ -3,32 +3,43 @@ import { describe, expect, it } from 'vitest'
 import { ClientConfigSchema, MetaConfigSchema } from './schema'
 
 describe('MetaConfigSchema', () => {
-  it('represents an unconfigured persisted state without environment defaults', () => {
+  it('generates a stable-shape browser Client identity without an environment value', () => {
     expect(MetaConfigSchema.parse({})).toEqual({
       INKCRE_PGREST_URL: '',
       INKCRE_JWT_SECRET: '',
-      INKCRE_CLIENT_ID: '',
+      client_id: expect.any(String),
     })
+    expect(MetaConfigSchema.parse({}).client_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+    )
   })
 
   it('accepts explicit runtime coordinates and rejects malformed non-empty values', () => {
     expect(
       MetaConfigSchema.parse({
         INKCRE_PGREST_URL: 'https://database.example.test/',
-        INKCRE_CLIENT_ID: '00000000-0000-4000-8000-000000000002',
+        client_id: '00000000-0000-4000-8000-000000000002',
       })
     ).toMatchObject({
       INKCRE_PGREST_URL: 'https://database.example.test/',
-      INKCRE_CLIENT_ID: '00000000-0000-4000-8000-000000000002',
+      client_id: '00000000-0000-4000-8000-000000000002',
     })
 
     expect(
       MetaConfigSchema.safeParse({
         INKCRE_PGREST_URL: 'not-a-url',
-        INKCRE_CLIENT_ID: 'not-a-uuid',
+        client_id: 'not-a-uuid',
       }).success
     ).toBe(false)
   })
+
+  it('migrates the former environment-style Client identity', () => {
+    expect(
+      MetaConfigSchema.parse({
+        INKCRE_CLIENT_ID: '00000000-0000-4000-8000-000000000002',
+      }).client_id
+    ).toBe('00000000-0000-4000-8000-000000000002')
+  })
 })
 
 describe('ClientConfigSchema', () => {
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index 7c95716..dba29c2 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -35,14 +35,32 @@ export const AIConfigSchema = z.object({
  * Contains URLs and secrets needed to fetch and initialize app config
  */
 const UnconfiguredUrlSchema = z.union([z.literal(''), z.url()])
-const UnconfiguredClientIdSchema = z.union([z.literal(''), z.uuid()])
+const GeneratedClientIdSchema = z.preprocess(
+  (value) => (value === '' ? undefined : value),
+  z.uuid().default(() => crypto.randomUUID())
+)
 
-export const MetaConfigSchema = z.object({
+const CurrentMetaConfigSchema = z.object({
   INKCRE_PGREST_URL: UnconfiguredUrlSchema.default(''),
   INKCRE_JWT_SECRET: z.string().default(''),
-  INKCRE_CLIENT_ID: UnconfiguredClientIdSchema.default(''),
+  client_id: GeneratedClientIdSchema,
 })
 
+/**
+ * Browser bootstrap configuration.
+ *
+ * `INKCRE_CLIENT_ID` was once a manually supplied environment-style value. A
+ * browser now owns its stable identity, while this preprocessor preserves an
+ * already configured origin during migration.
+ */
+export const MetaConfigSchema = z.preprocess((value) => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return value
+
+  const input = value as Record<string, unknown>
+  if (input.client_id !== undefined || input.INKCRE_CLIENT_ID === undefined) return input
+  return { ...input, client_id: input.INKCRE_CLIENT_ID }
+}, CurrentMetaConfigSchema)
+
 export type MetaConfig = z.infer<typeof MetaConfigSchema>
 
 /**
diff --git a/packages/core/src/config/store.test.ts b/packages/core/src/config/store.test.ts
new file mode 100644
index 0000000..ff4ab74
--- /dev/null
+++ b/packages/core/src/config/store.test.ts
@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { Client } from '../client'
+import type { ConfigAdapterWithWrite } from './types'
+import { configStore } from './store'
+
+const clientId = '00000000-0000-4000-8000-000000000002'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('connected configuration save', () => {
+  it('does not persist or activate MetaConfig when database validation fails', async () => {
+    const write = vi.fn()
+    const adapter: ConfigAdapterWithWrite = {
+      name: 'test',
+      read: async () => ({
+        INKCRE_PGREST_URL: 'https://old.example.test/',
+        INKCRE_JWT_SECRET: 'old-secret',
+        client_id: clientId,
+      }),
+      write,
+    }
+    await configStore.initializeMeta(adapter)
+    vi.spyOn(Client, 'connect').mockRejectedValue(new Error('database unavailable'))
+
+    await expect(
+      configStore.connectAndSave(
+        {
+          INKCRE_PGREST_URL: 'https://new.example.test/',
+          INKCRE_JWT_SECRET: 'new-secret',
+          client_id: clientId,
+        },
+        { ...configStore.clientConfig }
+      )
+    ).rejects.toThrow('database unavailable')
+
+    expect(write).not.toHaveBeenCalled()
+    expect(configStore.metaConfig.INKCRE_PGREST_URL).toBe('https://old.example.test/')
+  })
+
+  it('persists MetaConfig only after the browser Client is registered', async () => {
+    const events: string[] = []
+    const write = vi.fn(async () => {
+      events.push('write')
+    })
+    const adapter: ConfigAdapterWithWrite = {
+      name: 'test',
+      read: async () => ({}),
+      write,
+    }
+    await configStore.initializeMeta(adapter)
+    vi.spyOn(Client, 'connect').mockImplementation(async () => {
+      events.push('connect')
+      return Client.parse({ id: clientId, name: 'client-web' })
+    })
+
+    await configStore.connectAndSave(
+      {
+        INKCRE_PGREST_URL: 'https://database.example.test/',
+        INKCRE_JWT_SECRET: 'test-secret',
+        client_id: clientId,
+      },
+      { ...configStore.clientConfig, extension_registry_url: 'https://registry.inkcre.dev/' }
+    )
+
+    expect(events).toEqual(['connect', 'write'])
+    expect(configStore.metaConfig.client_id).toBe(clientId)
+    expect(configStore.clientConfig.extension_registry_url).toBe('https://registry.inkcre.dev/')
+  })
+})
diff --git a/packages/core/src/config/store.ts b/packages/core/src/config/store.ts
index c5d2884..0f05635 100644
--- a/packages/core/src/config/store.ts
+++ b/packages/core/src/config/store.ts
@@ -46,11 +46,6 @@ export const useConfigStore = defineStore('inkcre-config', () => {
   }
 
   async function loadClientConfig(): Promise<void> {
-    if (!metaConfig.value.INKCRE_CLIENT_ID) {
-      clientConfig.value = ClientConfigSchema.parse({})
-      return
-    }
-
     const Client = await lazyClient()
     try {
       const loaded = await Client.getSelf()
@@ -72,6 +67,26 @@ export const useConfigStore = defineStore('inkcre-config', () => {
     }
   }
 
+  async function connectAndSave(
+    metaCandidate: MetaConfig,
+    clientCandidate: ClientConfig
+  ): Promise<void> {
+    error.value = null
+    const nextMeta = MetaConfigSchema.parse(metaCandidate)
+    const nextClient = ClientConfigSchema.parse(clientCandidate)
+
+    try {
+      const Client = await lazyClient()
+      await Client.connect(nextMeta, nextClient)
+      await metaAdapter.value.write(nextMeta)
+      metaConfig.value = nextMeta
+      clientConfig.value = nextClient
+    } catch (err) {
+      error.value = err as Error
+      throw err
+    }
+  }
+
   async function resetMeta(): Promise<void> {
     metaConfig.value = MetaConfigSchema.parse({})
     clientConfig.value = ClientConfigSchema.parse({})
@@ -86,6 +101,7 @@ export const useConfigStore = defineStore('inkcre-config', () => {
     error,
     initializeMeta,
     loadClientConfig,
+    connectAndSave,
     saveMeta,
     resetMeta,
   }
diff --git a/packages/core/src/extension/host.ts b/packages/core/src/extension/host.ts
index be3a026..1688131 100644
--- a/packages/core/src/extension/host.ts
+++ b/packages/core/src/extension/host.ts
@@ -366,7 +366,7 @@ export class WebExtensionHost {
   private requireCurrentPeerId(): string {
     const peerId = this.currentPeerId()
     if (!peerId)
-      throw new WebExtensionHostError('INKCRE_CLIENT_ID is required for Extension state.')
+      throw new WebExtensionHostError('A browser Client identity is required for Extension state.')
     return peerId
   }
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e0ebc92..c50376b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -151,7 +151,7 @@ export {
 } from './database'
 
 // Authentication
-export { authStore } from './auth'
+export { authStore, signDatabaseToken } from './auth'
 
 // Utils
 export {
diff --git a/tasks/developer-experience-engineering/10-evidence.md b/tasks/developer-experience-engineering/10-evidence.md
index ec265b4..01964f4 100644
--- a/tasks/developer-experience-engineering/10-evidence.md
+++ b/tasks/developer-experience-engineering/10-evidence.md
@@ -31,7 +31,7 @@ This file records observed facts only. Decisions and desired state live in adjac
 
 ## Configuration and JWT Data Flow
 
-- `MetaConfig` contains `INKCRE_PGREST_URL`, `INKCRE_JWT_SECRET`, and `INKCRE_CLIENT_ID`: `packages/core/src/config/schema.ts:33`.
+- `MetaConfig` contains browser-local database coordinates plus an automatically generated `client_id`; saving Settings proves the candidate database and registers that browser Client before persisting MetaConfig: `packages/core/src/config/schema.ts`, `packages/core/src/config/store.ts`, and `packages/core/src/client/client.ts`.
 - The default meta adapter is `envAdapter`. Client-web sets it to the same adapter in development and does not automatically select `httpAdapter`: `packages/core/src/config/store.ts:16`, `apps/client-web/src/core.ts:139`.
 - The settings page lets a user manually select `localStorage`, `http`, or `env`: `apps/client-web/src/views/settings/settings.vue:42`.
 - The selected adapter name is written to `inkcre_config_adapter`, but no current code restores that choice on reload: `apps/client-web/src/views/settings/settings.vue:59`.
diff --git a/tests/e2e/browser-extension.spec.ts b/tests/e2e/browser-extension.spec.ts
index b888ed4..838a6f3 100644
--- a/tests/e2e/browser-extension.spec.ts
+++ b/tests/e2e/browser-extension.spec.ts
@@ -29,7 +29,7 @@ test('built Chromium extension loads its real popup', async ({ context, page, ex
       })
     },
     {
-      INKCRE_CLIENT_ID: '063cd1df-c495-5006-a119-67aa633b26be',
+      client_id: '063cd1df-c495-5006-a119-67aa633b26be',
       INKCRE_JWT_SECRET: 'client-webext-e2e-secret-at-least-32-bytes',
       INKCRE_PGREST_URL: 'http://127.0.0.1:9/',
     }
diff --git a/tests/e2e/peer-database.spec.ts b/tests/e2e/peer-database.spec.ts
index 9c1e4b4..0f7f568 100644
--- a/tests/e2e/peer-database.spec.ts
+++ b/tests/e2e/peer-database.spec.ts
@@ -23,7 +23,7 @@ test.beforeEach(async ({ page }) => {
         JSON.stringify({
           INKCRE_PGREST_URL: postgrestUrl,
           INKCRE_JWT_SECRET: jwtSecret,
-          INKCRE_CLIENT_ID: '00000000-0000-4000-8000-000000000002',
+          client_id: '00000000-0000-4000-8000-000000000002',
         })
       )
     },

From 6c43ff33db35879d11ea6c0a78cd40c934ae590b Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Fri, 14 Aug 2026 11:24:35 +0800
Subject: [PATCH 6/7] fix(settings): guard unconfigured client bootstrap

---
 packages/core/src/config/store.test.ts          | 15 +++++++++++++++
 packages/core/src/config/store.ts               |  5 +++++
 pnpm-lock.yaml                                  | 12 ++++++------
 pnpm-workspace.yaml                             |  2 +-
 .../10-evidence.md                              | 17 +++++++++++++++++
 5 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/packages/core/src/config/store.test.ts b/packages/core/src/config/store.test.ts
index ff4ab74..62190c2 100644
--- a/packages/core/src/config/store.test.ts
+++ b/packages/core/src/config/store.test.ts
@@ -11,6 +11,21 @@ afterEach(() => {
 })
 
 describe('connected configuration save', () => {
+  it('does not query the database before its bootstrap settings exist', async () => {
+    const adapter: ConfigAdapterWithWrite = {
+      name: 'test',
+      read: async () => ({}),
+      write: vi.fn(),
+    }
+    await configStore.initializeMeta(adapter)
+    const getSelf = vi.spyOn(Client, 'getSelf')
+
+    await configStore.loadClientConfig()
+
+    expect(getSelf).not.toHaveBeenCalled()
+    expect(configStore.clientConfig.extension_registry_url).toBe('')
+  })
+
   it('does not persist or activate MetaConfig when database validation fails', async () => {
     const write = vi.fn()
     const adapter: ConfigAdapterWithWrite = {
diff --git a/packages/core/src/config/store.ts b/packages/core/src/config/store.ts
index 0f05635..2f53a67 100644
--- a/packages/core/src/config/store.ts
+++ b/packages/core/src/config/store.ts
@@ -46,6 +46,11 @@ export const useConfigStore = defineStore('inkcre-config', () => {
   }
 
   async function loadClientConfig(): Promise<void> {
+    if (!metaConfig.value.INKCRE_PGREST_URL || !metaConfig.value.INKCRE_JWT_SECRET) {
+      clientConfig.value = ClientConfigSchema.parse({})
+      return
+    }
+
     const Client = await lazyClient()
     try {
       const loaded = await Client.getSelf()
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aee617c..e89f6a6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -23,7 +23,7 @@ overrides:
   immutable@>=5.0.0-beta.1 <5.1.8: 5.1.8
   js-yaml@>=4.0.0 <4.3.1: 4.3.1
   koa@>=3.0.0 <3.1.2: 3.1.2
-  nanoid@>=3.0.0 <3.3.17: 3.3.17
+  nanoid@>=3.0.0 <3.3.18: 3.3.18
   nanoid@>=4.0.0 <5.1.16: 5.1.16
   picomatch@<2.3.2: 2.3.2
   picomatch@>=4.0.0 <4.0.4: 4.0.5
@@ -4627,8 +4627,8 @@ packages:
     resolution: {integrity: sha512-FRS2otuFcPPYDPYViNWQ42+1iZqbXydinkRHTHFxrF4a1CpBfmydR9zkI44WSXAXCyPrkcGtPk5CnpW6Y3lFKQ==}
     engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
 
-  nanoid@3.3.17:
-    resolution: {integrity: sha512-xQLf0A3HOMlgHq0n247/LRuAOYmB7dXJ/DvAxGvsSBij45XtBSmQycu+F8ODbHwns/XyFZagyL1+J0Offw1E0g==}
+  nanoid@3.3.18:
+    resolution: {integrity: sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
@@ -10248,7 +10248,7 @@ snapshots:
 
   nanoevents@6.0.2: {}
 
-  nanoid@3.3.17: {}
+  nanoid@3.3.18: {}
 
   nanoid@5.1.16: {}
 
@@ -10597,13 +10597,13 @@ snapshots:
 
   postcss@8.5.18:
     dependencies:
-      nanoid: 3.3.17
+      nanoid: 3.3.18
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
   postcss@8.5.22:
     dependencies:
-      nanoid: 3.3.17
+      nanoid: 3.3.18
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 61bf9c0..6e48b87 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -25,7 +25,7 @@ overrides:
   immutable@>=5.0.0-beta.1 <5.1.8: 5.1.8
   js-yaml@>=4.0.0 <4.3.1: 4.3.1
   koa@>=3.0.0 <3.1.2: 3.1.2
-  nanoid@>=3.0.0 <3.3.17: 3.3.17
+  nanoid@>=3.0.0 <3.3.18: 3.3.18
   nanoid@>=4.0.0 <5.1.16: 5.1.16
   picomatch@<2.3.2: 2.3.2
   picomatch@>=4.0.0 <4.0.4: 4.0.5
diff --git a/tasks/developer-experience-engineering/10-evidence.md b/tasks/developer-experience-engineering/10-evidence.md
index 01964f4..b5de397 100644
--- a/tasks/developer-experience-engineering/10-evidence.md
+++ b/tasks/developer-experience-engineering/10-evidence.md
@@ -524,3 +524,20 @@ wrangler@4.114.0` invocation has a healthy OAuth session with Pages write access
 - Frozen installation, the complete 11-file / 40-test workspace check, the
   3-file / 19-test UI source-mode suite, and the cross-repository source type
   graph pass under the pnpm-managed Node 22.22.3 runtime.
+
+## 2026-08-14 Connected Client Settings Follow-up
+
+- Browser MetaConfig now owns a generated Client UUID. Runtime ClientConfig is
+  loaded only after both the PostgREST URL and JWT secret are configured, so a
+  fresh browser never treats the Pages origin as a database endpoint.
+- Saving Settings validates the candidate database connection and registers or
+  updates the browser Client before persisting MetaConfig; a failed connection
+  leaves the prior local configuration unchanged.
+- The Workspace contract remained the only prerequisite for Pages preview
+  delivery. Database-contract and browser/database E2E failures against the
+  Peer-based stable Core remain independent evidence while this feature branch
+  intentionally validates the Client-based Core PR 52 baseline.
+- The `nanoid` 3.x security override moved to 3.3.18 after GHSA-2v37-7h3g-55p8;
+  `pnpm audit --audit-level high` now reports no high-severity finding.
+- `pnpm check` passes with 22 test files and 96 tests, all workspace builds and
+  package contracts; `git diff --check` also passes.

From e1ee0e3102c308ad4a93b7211f870f123d406f5c Mon Sep 17 00:00:00 2001
From: Lan_zhijiang <lanzhijiang@foxmail.com>
Date: Fri, 14 Aug 2026 16:56:57 +0800
Subject: [PATCH 7/7] feat(extension): restore per-client management

---
 .../client/clientCard/clientCard.md           |   8 +-
 .../client/clientCard/clientCard.scss         |   2 +
 .../client/clientCard/clientCard.spec.ts      |  87 ++++++++++
 .../client/clientCard/clientCard.vue          |  68 ++++++--
 .../client/clientList/clientList.scss         |  17 +-
 .../client/clientList/clientList.spec.ts      |  51 ++++++
 .../client/clientList/clientList.vue          |  52 ++++--
 .../extensionCard/extensionCard.spec.ts       |  52 ++++--
 .../extension/extensionCard/extensionCard.ts  |   6 +-
 .../extension/extensionCard/extensionCard.vue |  10 +-
 apps/client-web/src/core.ts                   |   9 +
 .../src/extension-client-control.spec.ts      | 113 ++++++++++++
 .../src/extension-client-control.ts           |  67 ++++++++
 apps/client-web/src/locales/messages/en.json  |  13 +-
 .../src/locales/messages/zh-CN.json           |  13 +-
 .../src/views/extensions/extensions.scss      |  12 ++
 .../src/views/extensions/extensions.spec.ts   | 149 ++++++++++++++++
 .../src/views/extensions/extensions.vue       | 112 ++++++++++--
 .../src/views/settings/settings.scss          |  25 ++-
 .../src/views/settings/settings.spec.ts       | 108 ++++++++++++
 .../src/views/settings/settings.vue           | 162 ++++++++++--------
 21 files changed, 991 insertions(+), 145 deletions(-)
 create mode 100644 apps/client-web/src/components/client/clientCard/clientCard.spec.ts
 create mode 100644 apps/client-web/src/components/client/clientList/clientList.spec.ts
 create mode 100644 apps/client-web/src/extension-client-control.spec.ts
 create mode 100644 apps/client-web/src/extension-client-control.ts
 create mode 100644 apps/client-web/src/views/extensions/extensions.spec.ts
 create mode 100644 apps/client-web/src/views/settings/settings.spec.ts

diff --git a/apps/client-web/src/components/client/clientCard/clientCard.md b/apps/client-web/src/components/client/clientCard/clientCard.md
index afe539e..0e78c3d 100644
--- a/apps/client-web/src/components/client/clientCard/clientCard.md
+++ b/apps/client-web/src/components/client/clientCard/clientCard.md
@@ -2,11 +2,11 @@
 
 ## Rationale
 
-Display and edit a single client in the client list.
+Display and edit a registered Client in the deployment Client list.
 
 ## Goals
 
-Allow users to view client details and edit client name and URL.
+Allow users to view Client details and explicitly save its name, management URL, or configuration.
 
 ## Key Concepts
 
@@ -14,11 +14,11 @@ Client management, health status.
 
 ## Specification
 
-Shows client name, ID, URL, and status. Has edit mode with inputs for name and URL, save/cancel buttons.
+Shows Client name, ID, management URL, and health status. Name and URL changes use an explicit save action. Configuration changes use a JSON dialog.
 
 ## Implementation
 
-Uses reactive editing state, emits updated on save.
+Updates only an existing Client and emits `updated` after a successful save.
 
 ### Props
 
diff --git a/apps/client-web/src/components/client/clientCard/clientCard.scss b/apps/client-web/src/components/client/clientCard/clientCard.scss
index 4bb3995..1062231 100644
--- a/apps/client-web/src/components/client/clientCard/clientCard.scss
+++ b/apps/client-web/src/components/client/clientCard/clientCard.scss
@@ -10,6 +10,8 @@
     display: flex;
     flex-direction: column;
     gap: sys-var(space, xs);
+    flex: 1;
+    min-width: 0;
   }
 
   &__item-name {
diff --git a/apps/client-web/src/components/client/clientCard/clientCard.spec.ts b/apps/client-web/src/components/client/clientCard/clientCard.spec.ts
new file mode 100644
index 0000000..2792aa4
--- /dev/null
+++ b/apps/client-web/src/components/client/clientCard/clientCard.spec.ts
@@ -0,0 +1,87 @@
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Client } from '@inkcre/core'
+import ClientCard from './clientCard.vue'
+
+vi.mock('vue-i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }))
+
+const stubs = {
+  InkInput: defineComponent({
+    props: ['modelValue'],
+    emits: ['update:modelValue'],
+    template:
+      '<input :value="modelValue ?? \'\'" @input="$emit(\'update:modelValue\', $event.target.value)" />',
+  }),
+  InkButton: defineComponent({
+    props: ['text', 'loading'],
+    emits: ['click'],
+    template: '<button @click="$emit(\'click\')">{{ text }}</button>',
+  }),
+  InkDialog: defineComponent({ template: '<div><slot /></div>' }),
+  InkJsonEditor: true,
+}
+
+describe('ClientCard', () => {
+  beforeEach(() => {
+    vi.stubGlobal('alert', vi.fn())
+    vi.spyOn(console, 'error').mockImplementation(() => undefined)
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('explicitly updates an existing Client without an upsert lifecycle', async () => {
+    const single = vi.fn().mockResolvedValue({ data: {}, error: null, status: 200 })
+    const select = vi.fn(() => ({ single }))
+    const eq = vi.fn(() => ({ select }))
+    const update = vi.spyOn(Client.dbApi, 'update').mockReturnValue({ eq } as never)
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000003',
+      name: 'Old name',
+      rest_api_url: 'https://old.example.test/',
+    })
+    const wrapper = mount(ClientCard, {
+      props: { client, status: 'unknown' },
+      global: { stubs },
+    })
+
+    const inputs = wrapper.findAll('input')
+    await inputs[0].setValue('Renamed Client')
+    await inputs[1].setValue('https://new.example.test/')
+    const save = wrapper.findAll('button').find((button) => button.text() === 'settings.saveConfig')
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(update).toHaveBeenCalledWith({
+      name: 'Renamed Client',
+      rest_api_url: 'https://new.example.test/',
+    })
+    expect(eq).toHaveBeenCalledWith('id', client.id)
+    expect(single).toHaveBeenCalledOnce()
+    expect(wrapper.emitted('updated')).toHaveLength(1)
+  })
+
+  it('rejects an invalid management URL before writing the Client row', async () => {
+    const update = vi.spyOn(Client.dbApi, 'update')
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000003',
+      name: 'Core',
+      rest_api_url: 'https://core.example.test/',
+    })
+    const wrapper = mount(ClientCard, {
+      props: { client, status: 'unknown' },
+      global: { stubs },
+    })
+
+    await wrapper.findAll('input')[1].setValue('not a URL')
+    const save = wrapper.findAll('button').find((button) => button.text() === 'settings.saveConfig')
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(update).not.toHaveBeenCalled()
+    expect(alert).toHaveBeenCalledOnce()
+  })
+})
diff --git a/apps/client-web/src/components/client/clientCard/clientCard.vue b/apps/client-web/src/components/client/clientCard/clientCard.vue
index f4b001a..b328731 100644
--- a/apps/client-web/src/components/client/clientCard/clientCard.vue
+++ b/apps/client-web/src/components/client/clientCard/clientCard.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
-import { ref, computed } from 'vue'
+import { ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { InkButton, InkInput, InkDialog, InkJsonEditor } from '@inkcre/ui-web'
-import { Client, CreateClientForm } from '@inkcre/core'
+import { APIError, Client } from '@inkcre/core'
 import { clientCardProps, clientCardEmits } from './clientCard'
 
 const props = defineProps(clientCardProps)
@@ -11,36 +11,64 @@ const emit = defineEmits(clientCardEmits)
 const { t } = useI18n()
 
 const configPopupOpen = ref(false)
-const configModel = computed({
-  get: () => JSON.stringify(props.client.config ?? {}, null, 2),
-  set: (newValue: string) => {
-    props.client.config = JSON.parse(newValue)
-  },
-})
+const configModel = ref('')
+const clientSaving = ref(false)
+
+const isJsonObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
 
 const saveClient = async () => {
+  clientSaving.value = true
   try {
-    const form = new CreateClientForm(props.client)
-    await form.upsert()
+    const updatedClient = Client.parse({
+      ...props.client,
+      rest_api_url: props.client.rest_api_url || null,
+    })
+    const response = await Client.dbApi
+      .update({
+        name: updatedClient.name,
+        rest_api_url: updatedClient.rest_api_url,
+      })
+      .eq('id', props.client.id)
+      .select()
+      .single()
+    if (response.error) {
+      throw new APIError(
+        `Client update failed: ${response.error.message}`,
+        response.status,
+        response.error
+      )
+    }
     emit('updated')
   } catch (error) {
     console.error('Failed to update client:', error)
-    alert('Failed to update client')
+    alert(error instanceof Error ? error.message : t('settings.saveError'))
+  } finally {
+    clientSaving.value = false
   }
 }
 
 const onEditConfigClick = () => {
+  configModel.value = JSON.stringify(props.client.config ?? {}, null, 2)
   configPopupOpen.value = true
 }
 
 const onConfirmConfig = async () => {
+  const previousConfig = props.client.config
   try {
+    const nextConfig: unknown = JSON.parse(configModel.value)
+    if (!isJsonObject(nextConfig)) {
+      throw new TypeError('Client configuration must be a JSON object.')
+    }
+    props.client.config = nextConfig
     await props.client.saveConfig()
     emit('updated')
     configPopupOpen.value = false
   } catch (error) {
+    props.client.config = previousConfig
     console.error('Failed to update client config:', error)
-    alert('Failed to update client config')
+    alert(error instanceof Error ? error.message : t('settings.saveError'))
   }
 }
 
@@ -57,10 +85,18 @@ const getStatusText = (status: 'online' | 'offline' | 'unknown') => {
 <template>
   <div class="client-card">
     <div class="client-card__item-info">
-      <InkInput v-model="client.name" type="inline" @confirm="saveClient" />
+      <InkInput v-model="client.name" type="inline" />
       <span class="client-card__item-id">{{ client.id }}</span>
-      <InkInput v-model="client.rest_api_url" type="inline" @confirm="saveClient" />
-      <InkButton :text="t('client.editConfig')" size="sm" @click="onEditConfigClick" />
+      <InkInput v-model="client.rest_api_url" type="inline" />
+      <div class="client-card__edit-actions">
+        <InkButton
+          :text="t('settings.saveConfig')"
+          size="sm"
+          :loading="clientSaving"
+          @click="saveClient"
+        />
+        <InkButton :text="t('settings.clientConfig')" size="sm" @click="onEditConfigClick" />
+      </div>
     </div>
     <span :class="['client-card__item-status', `client-card__item-status--${status}`]">
       {{ getStatusText(status) }}
@@ -68,7 +104,7 @@ const getStatusText = (status: 'online' | 'offline' | 'unknown') => {
 
     <InkDialog
       v-model="configPopupOpen"
-      :title="t('client.editConfigTitle')"
+      :title="t('settings.clientConfig')"
       @confirm="onConfirmConfig"
     >
       <InkJsonEditor v-model="configModel" />
diff --git a/apps/client-web/src/components/client/clientList/clientList.scss b/apps/client-web/src/components/client/clientList/clientList.scss
index a9226d8..d7f0d89 100644
--- a/apps/client-web/src/components/client/clientList/clientList.scss
+++ b/apps/client-web/src/components/client/clientList/clientList.scss
@@ -1,7 +1,10 @@
 .client-list {
   display: flex;
   flex-direction: column;
-  gap: sys-var(space, md);
+  gap: sys-var(space, lg);
+  padding: sys-var(space, lg);
+  background-color: sys-var(color, surface, base);
+  border: 1px solid sys-var(color, border, base);
 
   &__header {
     display: flex;
@@ -17,6 +20,11 @@
     color: sys-var(color, text, base);
   }
 
+  &__notice {
+    margin: sys-var(space, xs) 0 0;
+    color: sys-var(color, text, subtle);
+  }
+
   &__actions {
     display: flex;
     gap: sys-var(space, sm);
@@ -85,4 +93,11 @@
     text-align: center;
     padding: sys-var(space, xl);
   }
+
+  &__error {
+    padding: sys-var(space, md);
+    color: sys-var(color, danger, base);
+    background-color: sys-var(color, danger, surface);
+    border: 1px solid sys-var(color, danger, base);
+  }
 }
diff --git a/apps/client-web/src/components/client/clientList/clientList.spec.ts b/apps/client-web/src/components/client/clientList/clientList.spec.ts
new file mode 100644
index 0000000..dd8ab5f
--- /dev/null
+++ b/apps/client-web/src/components/client/clientList/clientList.spec.ts
@@ -0,0 +1,51 @@
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Client } from '@inkcre/core'
+import ClientList from './clientList.vue'
+
+vi.mock('vue-i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }))
+
+const stubs = {
+  InkButton: defineComponent({
+    props: ['text'],
+    emits: ['click'],
+    template: '<button @click="$emit(\'click\')">{{ text }}</button>',
+  }),
+  InkLoading: defineComponent({ template: '<span data-test="loading" />' }),
+  ClientCard: defineComponent({
+    props: ['client', 'status'],
+    emits: ['updated'],
+    template: '<article data-test="client-card">{{ client.name }}:{{ status }}</article>',
+  }),
+}
+
+describe('ClientList', () => {
+  afterEach(() => vi.restoreAllMocks())
+
+  it('presents registered Clients as a deployment-wide scope', async () => {
+    const client = Client.parse({
+      id: '00000000-0000-4000-8000-000000000002',
+      name: 'Core',
+      rest_api_url: 'https://core.example.test/',
+    })
+    vi.spyOn(Client, 'list').mockResolvedValue([client])
+
+    const wrapper = mount(ClientList, { global: { stubs } })
+    await flushPromises()
+
+    expect(wrapper.get('h2').text()).toBe('settings.allClientsScope')
+    expect(wrapper.text()).toContain('settings.allClientsNotice')
+    expect(wrapper.get('[data-test="client-card"]').text()).toBe('Core:unknown')
+  })
+
+  it('shows a load failure instead of claiming that no Clients exist', async () => {
+    vi.spyOn(Client, 'list').mockRejectedValue(new Error('Database connection refused'))
+
+    const wrapper = mount(ClientList, { global: { stubs } })
+    await flushPromises()
+
+    expect(wrapper.get('[role="alert"]').text()).toContain('Database connection refused')
+    expect(wrapper.text()).not.toContain('client.noClients')
+  })
+})
diff --git a/apps/client-web/src/components/client/clientList/clientList.vue b/apps/client-web/src/components/client/clientList/clientList.vue
index dda19f0..303097f 100644
--- a/apps/client-web/src/components/client/clientList/clientList.vue
+++ b/apps/client-web/src/components/client/clientList/clientList.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useAsyncState } from '@vueuse/core'
 import { InkButton, InkLoading } from '@inkcre/ui-web'
@@ -11,50 +11,60 @@ const { t } = useI18n()
 // --- data ---
 const {
   state: clients,
-  execute: refreshClients,
+  execute: loadClients,
   isLoading: clientsLoading,
+  error: clientsError,
 } = useAsyncState(() => Client.list(), [], { immediate: true })
 
 const clientHealthStatus = ref<Record<string, 'online' | 'offline' | 'unknown'>>({})
 const healthCheckLoading = ref(false)
 
 // --- methods ---
+const refreshClients = async () => {
+  clientHealthStatus.value = {}
+  await loadClients()
+}
+
 const checkAllHealth = async () => {
   healthCheckLoading.value = true
   const results: Record<string, 'online' | 'offline' | 'unknown'> = {}
-  await Promise.all(
-    clients.value.map(async (client) => {
-      results[client.id] = client.rest_api_url ? await client.ping() : 'unknown'
-    })
-  )
-  clientHealthStatus.value = results
-  healthCheckLoading.value = false
-}
-
-const getStatusText = (status: 'online' | 'offline' | 'unknown') => {
-  const statusMap = {
-    online: t('client.statusOnline'),
-    offline: t('client.statusOffline'),
-    unknown: t('client.statusUnknown'),
+  try {
+    await Promise.all(
+      clients.value.map(async (client) => {
+        results[client.id] = client.rest_api_url ? await client.ping() : 'unknown'
+      })
+    )
+    clientHealthStatus.value = results
+  } finally {
+    healthCheckLoading.value = false
   }
-  return statusMap[status]
 }
 
 const getClientStatus = (clientId: string) => {
   return clientHealthStatus.value[clientId] || 'unknown'
 }
+
+const clientsErrorMessage = computed(() => {
+  if (!clientsError.value) return ''
+  return clientsError.value instanceof Error
+    ? clientsError.value.message
+    : String(clientsError.value)
+})
 </script>
 
 <template>
   <section class="client-list">
     <div class="client-list__header">
-      <h2 class="client-list__title">{{ t('client.listTitle') }}</h2>
+      <div>
+        <h2 class="client-list__title">{{ t('settings.allClientsScope') }}</h2>
+        <p class="client-list__notice">{{ t('settings.allClientsNotice') }}</p>
+      </div>
       <div class="client-list__actions">
         <InkButton
           :text="t('client.refresh')"
           size="sm"
           :loading="clientsLoading"
-          @click="() => refreshClients()"
+          @click="refreshClients"
         />
         <InkButton
           :text="t('client.checkHealth')"
@@ -67,6 +77,10 @@ const getClientStatus = (clientId: string) => {
 
     <InkLoading v-if="clientsLoading && clients.length === 0" />
 
+    <div v-else-if="clientsError" class="client-list__error" role="alert">
+      {{ clientsErrorMessage }}
+    </div>
+
     <div v-else-if="clients.length === 0" class="client-list__empty">
       {{ t('client.noClients') }}
     </div>
diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts b/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
index dd57e85..c70211d 100644
--- a/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.spec.ts
@@ -7,9 +7,9 @@ const SetupComponent = defineComponent({
   template: '<p data-test="twitter-setup">Twitter setup</p>',
 })
 const host = {
-  getSetupContribution: vi.fn(() => ({ component: SetupComponent })),
-  enable: vi.fn(),
-  disable: vi.fn(),
+  getSetupContribution: vi.fn((): { component: typeof SetupComponent } | null => ({
+    component: SetupComponent,
+  })),
   changeVersion: vi.fn(),
   updateConfig: vi.fn(),
   uninstall: vi.fn(),
@@ -46,9 +46,14 @@ const stubs = {
 describe('ExtensionCard setup contribution', () => {
   beforeEach(() => vi.clearAllMocks())
 
-  it('mounts setup only for an enabled, running Web Extension contribution', async () => {
+  it('mounts setup from the current Web runtime independently of selected Client state', async () => {
     const wrapper = mount(extensionCard, {
-      props: { extension, enabled: true },
+      props: {
+        extension,
+        enabled: false,
+        controlsCurrentWebRuntime: false,
+        setEnabled: vi.fn(async () => ({ ...extension, enabled: [] })),
+      },
       global: { stubs },
     })
 
@@ -60,31 +65,54 @@ describe('ExtensionCard setup contribution', () => {
     expect(wrapper.get('[data-test="twitter-setup"]').text()).toBe('Twitter setup')
   })
 
-  it('does not offer setup while this Web Peer is disabled', () => {
+  it('does not offer setup without a running Web contribution', () => {
+    host.getSetupContribution.mockReturnValueOnce(null)
     const wrapper = mount(extensionCard, {
-      props: { extension: { ...extension, enabled: [] }, enabled: false },
+      props: {
+        extension: { ...extension, enabled: [] },
+        enabled: false,
+        controlsCurrentWebRuntime: false,
+        setEnabled: vi.fn(async () => ({ ...extension, enabled: [] })),
+      },
       global: { stubs },
     })
 
     expect(wrapper.text()).not.toContain('extension.setup')
-    expect(host.getSetupContribution).not.toHaveBeenCalled()
+    expect(host.getSetupContribution).toHaveBeenCalledWith('inkcre/twitter')
   })
 
   it('unmounts contributed setup before disabling its Remote runtime', async () => {
+    const setEnabled = vi.fn(async () => {
+      expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(false)
+      return { ...extension, enabled: [] }
+    })
     const wrapper = mount(extensionCard, {
-      props: { extension, enabled: true },
+      props: { extension, enabled: true, controlsCurrentWebRuntime: true, setEnabled },
       global: { stubs },
     })
     const setup = wrapper.findAll('button').find((button) => button.text() === 'extension.setup')
     await setup?.trigger('click')
     expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(true)
-    host.disable.mockImplementationOnce(async () => {
-      expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(false)
+    await wrapper.get('[data-test="switch"]').trigger('click')
+    await flushPromises()
+
+    expect(setEnabled).toHaveBeenCalledWith(false)
+    expect(wrapper.emitted('updated')?.[0]).toEqual([{ ...extension, enabled: [] }])
+  })
+
+  it('does not close current Web setup when disabling another selected Client', async () => {
+    const setEnabled = vi.fn(async () => ({ ...extension, enabled: [] }))
+    const wrapper = mount(extensionCard, {
+      props: { extension, enabled: true, controlsCurrentWebRuntime: false, setEnabled },
+      global: { stubs },
     })
+    const setup = wrapper.findAll('button').find((button) => button.text() === 'extension.setup')
+    await setup?.trigger('click')
 
     await wrapper.get('[data-test="switch"]').trigger('click')
     await flushPromises()
 
-    expect(host.disable).toHaveBeenCalledWith('inkcre/twitter')
+    expect(wrapper.find('[data-test="twitter-setup"]').exists()).toBe(true)
+    expect(setEnabled).toHaveBeenCalledWith(false)
   })
 })
diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.ts b/apps/client-web/src/components/extension/extensionCard/extensionCard.ts
index 9643960..5713e30 100644
--- a/apps/client-web/src/components/extension/extensionCard/extensionCard.ts
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.ts
@@ -5,11 +5,15 @@ import type { InstalledExtension } from '@inkcre/core'
 export const extensionCardProps = {
   extension: { type: Object as PropType<InstalledExtension>, required: true },
   enabled: { type: Boolean, required: true },
+  controlsCurrentWebRuntime: { type: Boolean, required: true },
+  setEnabled: {
+    type: Function as PropType<(enabled: boolean) => Promise<InstalledExtension>>,
+    required: true,
+  },
 } as const
 
 // --- Emits ---
 export const extensionCardEmits = {
-  changed: () => true,
   updated: (_extension: InstalledExtension) => true,
   uninstalled: () => true,
 } as const
diff --git a/apps/client-web/src/components/extension/extensionCard/extensionCard.vue b/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
index 229fbfb..180f7b1 100644
--- a/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
+++ b/apps/client-web/src/components/extension/extensionCard/extensionCard.vue
@@ -31,7 +31,7 @@ watch(
 
 const canUninstall = computed(() => props.extension.enabled.length === 0 && !isUninstalling.value)
 const setupContribution = computed(() =>
-  props.enabled ? getExtensionHost().getSetupContribution(props.extension.name) : null
+  getExtensionHost().getSetupContribution(props.extension.name)
 )
 
 const closeSetup = async () => {
@@ -46,13 +46,11 @@ const toggleModel = computed({
     operationError.value = null
     togglePromise.value = (async () => {
       try {
-        if (enabled) {
-          await getExtensionHost().enable(props.extension.name)
-        } else {
+        if (!enabled && props.controlsCurrentWebRuntime) {
           await closeSetup()
-          await getExtensionHost().disable(props.extension.name)
         }
-        emit('changed')
+        const updated = await props.setEnabled(enabled)
+        emit('updated', updated)
         return enabled
       } catch (error) {
         operationError.value = error instanceof Error ? error.message : String(error)
diff --git a/apps/client-web/src/core.ts b/apps/client-web/src/core.ts
index 31f4fdd..c484dba 100644
--- a/apps/client-web/src/core.ts
+++ b/apps/client-web/src/core.ts
@@ -54,9 +54,11 @@ export function setupResolvers(): void {
 
 let extensionHost: WebExtensionHost | null = null
 let extensionHostStartup: Promise<void> | null = null
+let extensionState: ExtensionStatePort | null = null
 
 export function initializeExtensionHost(state: ExtensionStatePort): WebExtensionHost {
   extensionHostStartup = null
+  extensionState = state
   extensionHost = new WebExtensionHost({
     state,
     releases: new RegistryExtensionReleaseReader(
@@ -76,6 +78,13 @@ export function getExtensionHost(): WebExtensionHost {
   return extensionHost
 }
 
+export function getExtensionState(): ExtensionStatePort {
+  if (!extensionState) {
+    throw new Error('Web Extension state port has not been initialized.')
+  }
+  return extensionState
+}
+
 /** Share one initial runtime restore across the app shell and Extension management view. */
 export function startExtensionHost(): Promise<void> {
   if (extensionHostStartup) return extensionHostStartup
diff --git a/apps/client-web/src/extension-client-control.spec.ts b/apps/client-web/src/extension-client-control.spec.ts
new file mode 100644
index 0000000..ebd1880
--- /dev/null
+++ b/apps/client-web/src/extension-client-control.spec.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from 'vitest'
+import { extensionClientControlMode, setExtensionClientEnabled } from './extension-client-control'
+
+const currentClientId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const remoteClientId = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+const extension = {
+  name: 'inkcre/twitter',
+  version: '0.2.0',
+  enabled: [],
+  nickname: 'Twitter',
+  config: {},
+  config_schema: null,
+}
+
+function harness(client: { id: string; rest_api_url: string | null }) {
+  return {
+    client: {
+      ...client,
+      request: vi.fn(async (request: { path: string }) => ({
+        ...extension,
+        enabled: request.path.endsWith('/enable') ? [client.id] : [],
+      })),
+    },
+    webHost: {
+      enable: vi.fn(async () => ({ ...extension, enabled: [currentClientId] })),
+      disable: vi.fn(async () => extension),
+    },
+    state: {
+      setPeerEnabled: vi.fn(async (_name: string, clientId: string, enabled: boolean) => ({
+        ...extension,
+        enabled: enabled ? [clientId] : [],
+      })),
+    },
+  }
+}
+
+describe('Extension Client control', () => {
+  it('uses the Web Host lifecycle for the current browser Client', async () => {
+    const control = harness({ id: currentClientId, rest_api_url: null })
+
+    expect(extensionClientControlMode(control.client, currentClientId)).toBe('current-runtime')
+    await setExtensionClientEnabled({
+      name: extension.name,
+      client: control.client,
+      currentClientId,
+      enabled: true,
+      webHost: control.webHost,
+      state: control.state,
+    })
+
+    expect(control.webHost.enable).toHaveBeenCalledWith(extension.name)
+    expect(control.client.request).not.toHaveBeenCalled()
+    expect(control.state.setPeerEnabled).not.toHaveBeenCalled()
+  })
+
+  it('uses the selected Client Host API when it has a management endpoint', async () => {
+    const control = harness({ id: remoteClientId, rest_api_url: 'https://core.example.test' })
+
+    expect(extensionClientControlMode(control.client, currentClientId)).toBe('remote-host')
+    const updated = await setExtensionClientEnabled({
+      name: extension.name,
+      client: control.client,
+      currentClientId,
+      enabled: false,
+      webHost: control.webHost,
+      state: control.state,
+    })
+
+    expect(control.client.request).toHaveBeenCalledWith({
+      method: 'POST',
+      path: '/extensions/inkcre/twitter/disable',
+      resBodySchema: expect.anything(),
+    })
+    expect(updated.enabled).toEqual([])
+    expect(control.webHost.disable).not.toHaveBeenCalled()
+    expect(control.state.setPeerEnabled).not.toHaveBeenCalled()
+  })
+
+  it('updates only durable desired state for an unaddressable Client', async () => {
+    const control = harness({ id: remoteClientId, rest_api_url: null })
+
+    expect(extensionClientControlMode(control.client, currentClientId)).toBe('desired-state')
+    const updated = await setExtensionClientEnabled({
+      name: extension.name,
+      client: control.client,
+      currentClientId,
+      enabled: true,
+      webHost: control.webHost,
+      state: control.state,
+    })
+
+    expect(control.state.setPeerEnabled).toHaveBeenCalledWith(extension.name, remoteClientId, true)
+    expect(updated.enabled).toEqual([remoteClientId])
+    expect(control.webHost.enable).not.toHaveBeenCalled()
+    expect(control.client.request).not.toHaveBeenCalled()
+  })
+
+  it('rejects a remote Host response that changed a different Client', async () => {
+    const control = harness({ id: remoteClientId, rest_api_url: 'https://core.example.test' })
+    control.client.request.mockResolvedValueOnce({ ...extension, enabled: [currentClientId] })
+
+    await expect(
+      setExtensionClientEnabled({
+        name: extension.name,
+        client: control.client,
+        currentClientId,
+        enabled: true,
+        webHost: control.webHost,
+        state: control.state,
+      })
+    ).rejects.toThrow(`did not enable the selected Client ${remoteClientId}`)
+  })
+})
diff --git a/apps/client-web/src/extension-client-control.ts b/apps/client-web/src/extension-client-control.ts
new file mode 100644
index 0000000..9c97e38
--- /dev/null
+++ b/apps/client-web/src/extension-client-control.ts
@@ -0,0 +1,67 @@
+import {
+  InstalledExtensionSchema,
+  type ExtensionStatePort,
+  type InstalledExtension,
+  type WebExtensionHost,
+} from '@inkcre/core'
+
+export type ExtensionClientControlMode = 'current-runtime' | 'remote-host' | 'desired-state'
+
+export interface ExtensionClient {
+  id: string
+  rest_api_url: string | null
+  request?(options: {
+    method: string
+    path: string
+    resBodySchema: { parse(input: unknown): InstalledExtension }
+  }): Promise<InstalledExtension>
+}
+type CurrentWebHost = Pick<WebExtensionHost, 'enable' | 'disable'>
+type ExtensionDesiredState = Pick<ExtensionStatePort, 'setPeerEnabled'>
+
+export function extensionClientControlMode(
+  client: ExtensionClient,
+  currentClientId: string
+): ExtensionClientControlMode {
+  if (client.id === currentClientId) return 'current-runtime'
+  if (client.rest_api_url) return 'remote-host'
+  return 'desired-state'
+}
+
+export async function setExtensionClientEnabled(input: {
+  name: string
+  client: ExtensionClient
+  currentClientId: string
+  enabled: boolean
+  webHost: CurrentWebHost
+  state: ExtensionDesiredState
+}): Promise<InstalledExtension> {
+  const mode = extensionClientControlMode(input.client, input.currentClientId)
+  let updated: InstalledExtension
+
+  if (mode === 'current-runtime') {
+    updated = input.enabled
+      ? await input.webHost.enable(input.name)
+      : await input.webHost.disable(input.name)
+  } else if (mode === 'remote-host') {
+    if (!input.client.request) {
+      throw new Error(`Client ${input.client.id} has no callable management endpoint.`)
+    }
+    const operation = input.enabled ? 'enable' : 'disable'
+    updated = await input.client.request({
+      method: 'POST',
+      path: `/extensions/${input.name}/${operation}`,
+      resBodySchema: InstalledExtensionSchema,
+    })
+  } else {
+    updated = await input.state.setPeerEnabled(input.name, input.client.id, input.enabled)
+  }
+
+  const selectedClientIsEnabled = updated.enabled.includes(input.client.id)
+  if (selectedClientIsEnabled !== input.enabled) {
+    throw new Error(
+      `${input.name} did not ${input.enabled ? 'enable' : 'disable'} the selected Client ${input.client.id}.`
+    )
+  }
+  return updated
+}
diff --git a/apps/client-web/src/locales/messages/en.json b/apps/client-web/src/locales/messages/en.json
index 8ca35c0..3c332b4 100644
--- a/apps/client-web/src/locales/messages/en.json
+++ b/apps/client-web/src/locales/messages/en.json
@@ -23,6 +23,9 @@
   },
   "settings": {
     "title": "Settings",
+    "currentBrowserScope": "This Browser",
+    "allClientsScope": "Deployment Clients",
+    "allClientsNotice": "Manage the registered Clients connected to this deployment, including their management endpoint and declared configuration.",
     "metaConfig": "Meta Configuration",
     "coreUrl": "Core API URL",
     "pgrestUrl": "PostgreSQL REST URL",
@@ -91,8 +94,14 @@
     "changeVersion": "Change Version",
     "changeVersionTitle": "Change Exact Extension Version",
     "uninstall": "Uninstall",
-    "enabledPeerCount": "Enabled on {count} Peer(s).",
-    "uninstallDisabled": "Disable every Peer before uninstalling or changing the shared version."
+    "clientSelector": "Client",
+    "clientSelectorPlaceholder": "Select a Client",
+    "currentBrowser": "this browser",
+    "clientNotFound": "The selected Client no longer exists. Refresh the Client list.",
+    "clientListUnavailable": "Other Clients could not be loaded. This browser remains manageable. {error}",
+    "desiredStateOnly": "This Client has no management endpoint. The switch updates its saved desired state only; a running instance may continue until that Client reloads.",
+    "enabledPeerCount": "Enabled on {count} Client(s).",
+    "uninstallDisabled": "Disable every Client before uninstalling or changing the shared version."
   },
   "collectJob": {
     "title": "Collect Job Details",
diff --git a/apps/client-web/src/locales/messages/zh-CN.json b/apps/client-web/src/locales/messages/zh-CN.json
index ca72993..d434967 100644
--- a/apps/client-web/src/locales/messages/zh-CN.json
+++ b/apps/client-web/src/locales/messages/zh-CN.json
@@ -23,6 +23,9 @@
   },
   "settings": {
     "title": "设置",
+    "currentBrowserScope": "当前浏览器",
+    "allClientsScope": "Deployment 中的 Clients",
+    "allClientsNotice": "管理此 Deployment 中已注册的 Client，包括管理端点及其声明的配置。",
     "metaConfig": "运行配置",
     "coreUrl": "核心 API 地址",
     "pgrestUrl": "PostgreSQL REST 地址",
@@ -91,8 +94,14 @@
     "changeVersion": "变更版本",
     "changeVersionTitle": "变更扩展的精确版本",
     "uninstall": "卸载",
-    "enabledPeerCount": "已在 {count} 个 Peer 上启用。",
-    "uninstallDisabled": "卸载或变更共享版本前，必须先禁用所有 Peer。"
+    "clientSelector": "Client",
+    "clientSelectorPlaceholder": "选择 Client",
+    "currentBrowser": "当前浏览器",
+    "clientNotFound": "所选 Client 已不存在，请刷新 Client 列表。",
+    "clientListUnavailable": "无法加载其他 Client，当前浏览器仍可管理。{error}",
+    "desiredStateOnly": "此 Client 没有管理端点；开关只更新其持久化期望状态，已运行的实例可能持续到该 Client 刷新。",
+    "enabledPeerCount": "已在 {count} 个 Client 上启用。",
+    "uninstallDisabled": "卸载或变更共享版本前，必须先禁用所有 Client。"
   },
   "collectJob": {
     "title": "采集任务详情",
diff --git a/apps/client-web/src/views/extensions/extensions.scss b/apps/client-web/src/views/extensions/extensions.scss
index fcc75c7..78f2836 100644
--- a/apps/client-web/src/views/extensions/extensions.scss
+++ b/apps/client-web/src/views/extensions/extensions.scss
@@ -18,6 +18,18 @@
     overflow-y: auto;
   }
 
+  &__header {
+    display: flex;
+    flex-direction: column;
+    gap: sys-var(space, sm);
+  }
+
+  &__notice {
+    @include apply-font(body-sm);
+    margin: 0;
+    color: sys-var(color, text, muted);
+  }
+
   &__error {
     @include apply-font(body-sm);
     color: sys-var(color, danger, base);
diff --git a/apps/client-web/src/views/extensions/extensions.spec.ts b/apps/client-web/src/views/extensions/extensions.spec.ts
new file mode 100644
index 0000000..0c31c45
--- /dev/null
+++ b/apps/client-web/src/views/extensions/extensions.spec.ts
@@ -0,0 +1,149 @@
+import { defineComponent, nextTick } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ExtensionsView from './extensions.vue'
+
+const fixtures = vi.hoisted(() => {
+  const currentClientId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+  const remoteClientId = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+  const clients = [
+    {
+      id: currentClientId,
+      name: 'Browser A',
+      labels: ['web'],
+      rest_api_url: null,
+      request: vi.fn(),
+    },
+    {
+      id: remoteClientId,
+      name: 'Browser B',
+      labels: ['web'],
+      rest_api_url: null,
+      request: vi.fn(),
+    },
+  ]
+  const extension = {
+    name: 'inkcre/twitter',
+    version: '0.2.0',
+    enabled: [currentClientId],
+    nickname: 'Twitter',
+    config: {},
+    config_schema: null,
+  }
+  return {
+    currentClientId,
+    remoteClientId,
+    clients,
+    extension,
+    host: { list: vi.fn(async () => [extension]) },
+    listClients: vi.fn(async () => clients),
+    setClientEnabled: vi.fn(),
+  }
+})
+
+vi.mock('@inkcre/core', () => ({
+  Client: { list: fixtures.listClients },
+  configStore: { metaConfig: { client_id: fixtures.currentClientId } },
+}))
+vi.mock('@/core', () => ({
+  getExtensionHost: () => fixtures.host,
+  getExtensionState: () => ({ setPeerEnabled: vi.fn() }),
+  startExtensionHost: vi.fn(async () => undefined),
+}))
+vi.mock('@/extension-client-control', () => ({
+  extensionClientControlMode: (client: { id: string; rest_api_url: string | null }) =>
+    client.id === fixtures.currentClientId
+      ? 'current-runtime'
+      : client.rest_api_url
+        ? 'remote-host'
+        : 'desired-state',
+  setExtensionClientEnabled: fixtures.setClientEnabled,
+}))
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({ t: (key: string) => key }),
+}))
+
+const ExtensionCardStub = defineComponent({
+  props: ['extension', 'enabled', 'controlsCurrentWebRuntime', 'setEnabled'],
+  template:
+    '<div data-test="extension-card" :data-enabled="String(enabled)" :data-current="String(controlsCurrentWebRuntime)" />',
+})
+const InkDropdownStub = defineComponent({
+  props: ['modelValue', 'options', 'label', 'placeholder'],
+  emits: ['update:modelValue'],
+  template: '<button data-test="client-selector" />',
+})
+
+describe('Extensions Client selector', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('defaults to this browser and projects enabled state for the selected Client', async () => {
+    const wrapper = mount(ExtensionsView, {
+      global: {
+        stubs: {
+          extensionCard: ExtensionCardStub,
+          installExtension: true,
+          InkDropdown: InkDropdownStub,
+          InkLoading: true,
+        },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.getComponent(InkDropdownStub)
+    expect(selector.props('modelValue')).toBe(fixtures.currentClientId)
+    expect(selector.props('options')[0]).toMatchObject({
+      value: fixtures.currentClientId,
+      label: 'Browser A (extension.currentBrowser)',
+    })
+    expect(wrapper.get('[data-test="extension-card"]').attributes()).toMatchObject({
+      'data-enabled': 'true',
+      'data-current': 'true',
+    })
+
+    selector.vm.$emit('update:modelValue', fixtures.remoteClientId)
+    await nextTick()
+
+    expect(wrapper.get('[data-test="extension-card"]').attributes()).toMatchObject({
+      'data-enabled': 'false',
+      'data-current': 'false',
+    })
+    expect(wrapper.text()).toContain('extension.desiredStateOnly')
+  })
+
+  it('keeps current-browser management available when the Client list fails', async () => {
+    fixtures.listClients.mockRejectedValueOnce(new Error('Client row could not be parsed'))
+    fixtures.setClientEnabled.mockResolvedValueOnce({ ...fixtures.extension, enabled: [] })
+    const wrapper = mount(ExtensionsView, {
+      global: {
+        stubs: {
+          extensionCard: ExtensionCardStub,
+          installExtension: true,
+          InkDropdown: InkDropdownStub,
+          InkLoading: true,
+        },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.getComponent(InkDropdownStub)
+    const card = wrapper.getComponent(ExtensionCardStub)
+    expect(selector.props('modelValue')).toBe(fixtures.currentClientId)
+    expect(selector.props('options')).toEqual([
+      {
+        label: 'extension.currentBrowser',
+        value: fixtures.currentClientId,
+        description: fixtures.currentClientId,
+      },
+    ])
+    expect(wrapper.text()).toContain('extension.clientListUnavailable')
+
+    await card.props('setEnabled')(false)
+    expect(fixtures.setClientEnabled).toHaveBeenCalledWith(
+      expect.objectContaining({
+        client: { id: fixtures.currentClientId, rest_api_url: null },
+        currentClientId: fixtures.currentClientId,
+      })
+    )
+  })
+})
diff --git a/apps/client-web/src/views/extensions/extensions.vue b/apps/client-web/src/views/extensions/extensions.vue
index 9642809..0a200f3 100644
--- a/apps/client-web/src/views/extensions/extensions.vue
+++ b/apps/client-web/src/views/extensions/extensions.vue
@@ -1,21 +1,74 @@
 <script setup lang="ts">
-import { onMounted, ref } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 import extensionCard from '@/components/extension/extensionCard/extensionCard.vue'
 import installExtension from '@/components/extension/installExtension/installExtension.vue'
-import { InkLoading } from '@inkcre/ui-web'
-import { configStore, type InstalledExtension } from '@inkcre/core'
-import { getExtensionHost, startExtensionHost } from '@/core'
+import { InkDropdown, InkLoading } from '@inkcre/ui-web'
+import { Client, configStore, type InstalledExtension } from '@inkcre/core'
+import { getExtensionHost, getExtensionState, startExtensionHost } from '@/core'
+import {
+  extensionClientControlMode,
+  setExtensionClientEnabled,
+  type ExtensionClient,
+} from '@/extension-client-control'
 import { useI18n } from 'vue-i18n'
 
 // --- data ---
 const { t } = useI18n()
-const currentPeerId = configStore.metaConfig.client_id
+const currentClientId = configStore.metaConfig.client_id
+const selectedClientId = ref(currentClientId)
+const clients = ref<Client[]>([])
 const extensions = ref<InstalledExtension[]>([])
+const clientsLoading = ref(false)
 const extensionsLoading = ref(false)
 const error = ref<string | null>(null)
+const clientError = ref<string | null>(null)
 
-const isEnabledForCurrentPeer = (extension: InstalledExtension) =>
-  currentPeerId ? extension.enabled.includes(currentPeerId) : false
+const currentClientFallback: ExtensionClient = {
+  id: currentClientId,
+  rest_api_url: null,
+}
+const selectedClient = computed(
+  () =>
+    clients.value.find((client) => client.id === selectedClientId.value) ??
+    (selectedClientId.value === currentClientId ? currentClientFallback : null)
+)
+const clientOptions = computed(() => {
+  const options = clients.value.map((client) => ({
+    label:
+      client.id === currentClientId
+        ? `${client.name} (${t('extension.currentBrowser')})`
+        : client.name,
+    value: client.id,
+    description: client.id,
+  }))
+  if (clients.value.some((client) => client.id === currentClientId)) return options
+  return [
+    {
+      label: t('extension.currentBrowser'),
+      value: currentClientId,
+      description: currentClientId,
+    },
+    ...options,
+  ]
+})
+const selectedControlMode = computed(() =>
+  selectedClient.value ? extensionClientControlMode(selectedClient.value, currentClientId) : null
+)
+const isEnabledForSelectedClient = (extension: InstalledExtension) =>
+  selectedClientId.value ? extension.enabled.includes(selectedClientId.value) : false
+
+const refreshClients = async () => {
+  clientsLoading.value = true
+  clientError.value = null
+  try {
+    clients.value = await Client.list()
+  } catch (cause) {
+    clients.value = []
+    clientError.value = cause instanceof Error ? cause.message : String(cause)
+  } finally {
+    clientsLoading.value = false
+  }
+}
 
 const refreshExtensions = async () => {
   extensionsLoading.value = true
@@ -36,7 +89,11 @@ onMounted(async () => {
     // The app shell owns runtime-startup reporting. The installed list remains a
     // useful recovery surface even when one enabled Extension fails to start.
   }
-  await refreshExtensions()
+  try {
+    await Promise.all([refreshClients(), refreshExtensions()])
+  } catch (cause) {
+    error.value = cause instanceof Error ? cause.message : String(cause)
+  }
 })
 
 // --- methods ---
@@ -49,6 +106,23 @@ const updExtension = (updatedExtension: InstalledExtension) => {
     extension.name === updatedExtension.name ? updatedExtension : extension
   )
 }
+
+const setEnabledForSelectedClient = async (
+  extension: InstalledExtension,
+  enabled: boolean
+): Promise<InstalledExtension> => {
+  const client = selectedClient.value
+  if (!client) throw new Error(t('extension.clientNotFound'))
+
+  return setExtensionClientEnabled({
+    name: extension.name,
+    client,
+    currentClientId,
+    enabled,
+    webHost: getExtensionHost(),
+    state: getExtensionState(),
+  })
+}
 </script>
 
 <template>
@@ -56,7 +130,22 @@ const updExtension = (updatedExtension: InstalledExtension) => {
     <installExtension @install="onInstallExtension" />
 
     <div class="extensions-view__list">
-      <div v-if="extensionsLoading" class="flex items-center justify-center">
+      <div class="extensions-view__header">
+        <InkDropdown
+          v-model="selectedClientId"
+          :label="t('extension.clientSelector')"
+          :placeholder="t('extension.clientSelectorPlaceholder')"
+          :options="clientOptions"
+        />
+        <p v-if="selectedControlMode === 'desired-state'" class="extensions-view__notice">
+          {{ t('extension.desiredStateOnly') }}
+        </p>
+        <p v-if="clientError" class="extensions-view__error">
+          {{ t('extension.clientListUnavailable', { error: clientError }) }}
+        </p>
+      </div>
+
+      <div v-if="extensionsLoading || clientsLoading" class="flex items-center justify-center">
         <InkLoading />
       </div>
       <p v-else-if="error" class="extensions-view__error">{{ error }}</p>
@@ -65,8 +154,9 @@ const updExtension = (updatedExtension: InstalledExtension) => {
         v-else
         :key="extension.name"
         :extension="extension"
-        :enabled="isEnabledForCurrentPeer(extension)"
-        @changed="refreshExtensions"
+        :enabled="isEnabledForSelectedClient(extension)"
+        :controls-current-web-runtime="selectedControlMode === 'current-runtime'"
+        :set-enabled="(enabled) => setEnabledForSelectedClient(extension, enabled)"
         @updated="updExtension"
         @uninstalled="refreshExtensions"
       />
diff --git a/apps/client-web/src/views/settings/settings.scss b/apps/client-web/src/views/settings/settings.scss
index 65ea714..9b5b610 100644
--- a/apps/client-web/src/views/settings/settings.scss
+++ b/apps/client-web/src/views/settings/settings.scss
@@ -3,7 +3,7 @@
   padding: sys-var('space', 'lg');
   display: flex;
   flex-direction: column;
-  gap: sys-var('space', 'lg');
+  gap: sys-var('space', 'xl');
   overflow-y: auto;
 
   &__title {
@@ -12,12 +12,35 @@
     color: sys-var('color', 'text', 'base');
   }
 
+  &__scope {
+    display: flex;
+    flex-direction: column;
+    gap: sys-var('space', 'lg');
+    padding: sys-var('space', 'lg');
+    background: sys-var('color', 'surface', 'base');
+    border: 1px solid sys-var('color', 'border', 'base');
+  }
+
+  &__scope-title {
+    @include apply-font('title', 'lg');
+    margin: 0;
+    padding-bottom: sys-var('space', 'md');
+    color: sys-var('color', 'text', 'base');
+    border-bottom: 1px solid sys-var('color', 'border', 'base');
+  }
+
   &__form {
     display: flex;
     flex-direction: column;
     gap: sys-var('space', 'md');
   }
 
+  &__section-title {
+    @include apply-font('title', 'md');
+    margin: sys-var('space', 'sm') 0 0;
+    color: sys-var('color', 'text', 'base');
+  }
+
   &__notice,
   &__export-note {
     margin: 0;
diff --git a/apps/client-web/src/views/settings/settings.spec.ts b/apps/client-web/src/views/settings/settings.spec.ts
new file mode 100644
index 0000000..edeaa37
--- /dev/null
+++ b/apps/client-web/src/views/settings/settings.spec.ts
@@ -0,0 +1,108 @@
+import { defineComponent, onMounted } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ClientConfigSchema, configStore, MetaConfigSchema } from '@inkcre/core'
+import Settings from './settings.vue'
+
+const clientListState = vi.hoisted(() => ({ mounts: 0 }))
+
+vi.mock('@/components/client/clientList/clientList.vue', () => ({
+  default: defineComponent({
+    name: 'ClientList',
+    setup() {
+      onMounted(() => {
+        clientListState.mounts += 1
+      })
+    },
+    template: '<section data-test="all-clients-scope" />',
+  }),
+}))
+
+vi.mock('vue-i18n', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('vue-i18n')>()),
+  useI18n: () => ({ t: (key: string) => key }),
+}))
+
+const connectedMetaConfig = MetaConfigSchema.parse({
+  INKCRE_PGREST_URL: 'https://database.example.test/',
+  INKCRE_JWT_SECRET: 'secret',
+  client_id: '00000000-0000-4000-8000-000000000001',
+})
+const originalMetaConfig = { ...configStore.metaConfig }
+const originalClientConfig = ClientConfigSchema.parse(configStore.clientConfig)
+
+const stubs = {
+  InkForm: defineComponent({ template: '<form><slot /></form>' }),
+  InkInput: true,
+  InkButton: defineComponent({
+    props: ['text'],
+    emits: ['click'],
+    template: '<button type="button" @click="$emit(\'click\')">{{ text }}</button>',
+  }),
+  InkDoubleCheck: defineComponent({ template: '<div><slot /></div>' }),
+}
+
+describe('Settings client scopes', () => {
+  beforeEach(() => {
+    clientListState.mounts = 0
+    vi.stubGlobal('alert', vi.fn())
+  })
+
+  afterEach(() => {
+    Object.assign(configStore.metaConfig, originalMetaConfig)
+    Object.assign(configStore.clientConfig, originalClientConfig)
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('keeps the browser recovery scope local while bootstrap is unconfigured', async () => {
+    Object.assign(configStore.metaConfig, MetaConfigSchema.parse({}))
+    const loadClientConfig = vi.spyOn(configStore, 'loadClientConfig').mockResolvedValue()
+
+    const wrapper = mount(Settings, { global: { stubs } })
+    await flushPromises()
+
+    expect(wrapper.get('[data-test="current-browser-scope"]').text()).toContain(
+      'settings.currentBrowserScope'
+    )
+    expect(wrapper.find('[data-test="all-clients-scope"]').exists()).toBe(false)
+    expect(loadClientConfig).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('mounts deployment Clients after the current browser scope when connected', async () => {
+    Object.assign(configStore.metaConfig, connectedMetaConfig)
+    vi.spyOn(configStore, 'loadClientConfig').mockResolvedValue()
+
+    const wrapper = mount(Settings, { global: { stubs } })
+    await flushPromises()
+
+    const browserScope = wrapper.get('[data-test="current-browser-scope"]')
+    const allClientsScope = wrapper.get('[data-test="all-clients-scope"]')
+    const relativePosition = browserScope.element.compareDocumentPosition(allClientsScope.element)
+
+    expect(relativePosition & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0)
+    expect(clientListState.mounts).toBe(1)
+    wrapper.unmount()
+  })
+
+  it('reloads the deployment Client list after saving browser configuration', async () => {
+    Object.assign(configStore.metaConfig, connectedMetaConfig)
+    vi.spyOn(configStore, 'loadClientConfig').mockResolvedValue()
+    vi.spyOn(configStore, 'connectAndSave').mockImplementation(async (meta, client) => {
+      Object.assign(configStore.metaConfig, meta)
+      Object.assign(configStore.clientConfig, client)
+    })
+
+    const wrapper = mount(Settings, { global: { stubs } })
+    await flushPromises()
+    const save = wrapper.findAll('button').find((button) => button.text() === 'settings.saveConfig')
+
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(configStore.connectAndSave).toHaveBeenCalledOnce()
+    expect(clientListState.mounts).toBe(2)
+    wrapper.unmount()
+  })
+})
diff --git a/apps/client-web/src/views/settings/settings.vue b/apps/client-web/src/views/settings/settings.vue
index 9f045ba..91a7d0b 100644
--- a/apps/client-web/src/views/settings/settings.vue
+++ b/apps/client-web/src/views/settings/settings.vue
@@ -11,12 +11,20 @@ import {
 } from '@inkcre/core'
 import { setLocale, SUPPORT_LOCALES, LOCALE_NAMES, type SupportLocale } from '@/locales'
 import i18n from '@/locales'
+import ClientList from '@/components/client/clientList/clientList.vue'
 
 const { t } = useI18n()
 
 // Local reactive copy of metaConfig for form editing
 const metaFormConfig = reactive<MetaConfig>({ ...configStore.metaConfig })
 const clientFormConfig = reactive<ClientConfig>(ClientConfigSchema.parse(configStore.clientConfig))
+const allClientsRevision = ref(0)
+
+const hasConnectedConfig = computed(
+  () =>
+    Boolean(configStore.metaConfig.INKCRE_PGREST_URL) &&
+    Boolean(configStore.metaConfig.INKCRE_JWT_SECRET)
+)
 
 // Synchronize metaFormConfig with configStore.metaConfig
 watch(
@@ -58,6 +66,7 @@ const onSave = async () => {
     await configStore.connectAndSave(validatedMeta, validatedClient)
     Object.assign(metaFormConfig, configStore.metaConfig)
     Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
+    allClientsRevision.value += 1
     alert(t('settings.saveSuccess'))
   } catch (error) {
     console.error('Failed to save config:', error)
@@ -116,6 +125,7 @@ const onFileSelected = async (event: Event) => {
       await configStore.connectAndSave(validated, ClientConfigSchema.parse(clientFormConfig))
       Object.assign(metaFormConfig, configStore.metaConfig)
       Object.assign(clientFormConfig, ClientConfigSchema.parse(configStore.clientConfig))
+      allClientsRevision.value += 1
       alert(t('settings.saveSuccess'))
     } catch (error) {
       console.error('Failed to import config:', error)
@@ -133,83 +143,95 @@ const onFileSelected = async (event: Event) => {
   <main class="settings-view">
     <h1 class="settings-view__title">{{ t('settings.title') }}</h1>
 
-    <InkForm layout="col" class="settings-view__form">
-      <!-- Meta Configuration -->
-      <h2 class="settings-view__section-title">
-        {{ t('settings.metaConfig') }}
+    <section
+      class="settings-view__scope settings-view__scope--current-browser"
+      data-test="current-browser-scope"
+      aria-labelledby="current-browser-scope-title"
+    >
+      <h2 id="current-browser-scope-title" class="settings-view__scope-title">
+        {{ t('settings.currentBrowserScope') }}
       </h2>
-      <p class="settings-view__notice">{{ t('settings.storageNotice') }}</p>
-      <InkInput
-        v-model="metaFormConfig.INKCRE_PGREST_URL"
-        :label="t('settings.pgrestUrl')"
-        placeholder="https://..."
-      />
 
-      <label class="settings-view__secret">
-        <span>{{ t('settings.jwtSecret') }}</span>
-        <input
-          v-model="metaFormConfig.INKCRE_JWT_SECRET"
-          type="password"
-          autocomplete="off"
-          placeholder="••••••••"
+      <InkForm layout="col" class="settings-view__form">
+        <!-- Meta Configuration -->
+        <h3 class="settings-view__section-title">
+          {{ t('settings.metaConfig') }}
+        </h3>
+        <p class="settings-view__notice">{{ t('settings.storageNotice') }}</p>
+        <InkInput
+          v-model="metaFormConfig.INKCRE_PGREST_URL"
+          :label="t('settings.pgrestUrl')"
+          placeholder="https://..."
         />
-        <small>{{ t('settings.jwtStoredLocally') }}</small>
-      </label>
 
-      <div class="settings-view__identity">
-        <span>{{ t('settings.clientId') }}</span>
-        <code>{{ metaFormConfig.client_id }}</code>
-        <small>{{ t('settings.clientIdGenerated') }}</small>
-      </div>
+        <label class="settings-view__secret">
+          <span>{{ t('settings.jwtSecret') }}</span>
+          <input
+            v-model="metaFormConfig.INKCRE_JWT_SECRET"
+            type="password"
+            autocomplete="off"
+            placeholder="••••••••"
+          />
+          <small>{{ t('settings.jwtStoredLocally') }}</small>
+        </label>
+
+        <div class="settings-view__identity">
+          <span>{{ t('settings.clientId') }}</span>
+          <code>{{ metaFormConfig.client_id }}</code>
+          <small>{{ t('settings.clientIdGenerated') }}</small>
+        </div>
+
+        <!-- Client Configuration -->
+        <h3 class="settings-view__section-title">
+          {{ t('settings.clientConfig') }}
+        </h3>
+        <p class="settings-view__notice">{{ t('settings.clientConfigNotice') }}</p>
+        <InkInput
+          v-model="clientFormConfig.extension_registry_url"
+          :label="t('settings.extensionRegistryUrl')"
+          placeholder="https://..."
+        />
 
-      <!-- Client Configuration -->
-      <h2 class="settings-view__section-title">
-        {{ t('settings.clientConfig') }}
-      </h2>
-      <p class="settings-view__notice">{{ t('settings.clientConfigNotice') }}</p>
-      <InkInput
-        v-model="clientFormConfig.extension_registry_url"
-        :label="t('settings.extensionRegistryUrl')"
-        placeholder="https://..."
+        <!-- Language Selection -->
+        <h3 class="settings-view__section-title">{{ t('settings.language') }}</h3>
+        <label class="settings-view__locale">
+          <span>{{ t('settings.languageLabel') }}</span>
+          <select v-model="currentLocale">
+            <option v-for="locale in SUPPORT_LOCALES" :key="locale" :value="locale">
+              {{ LOCALE_NAMES[locale] }}
+            </option>
+          </select>
+        </label>
+      </InkForm>
+
+      <!-- Action Buttons -->
+      <div class="settings-view__actions">
+        <InkButton :text="t('settings.saveConfig')" theme="primary" @click="onSave" />
+
+        <InkDoubleCheck
+          :title="t('settings.resetConfirmTitle')"
+          :message="t('settings.resetConfirmMessage')"
+          @confirm="onReset"
+        >
+          <InkButton :text="t('settings.resetConfig')" theme="danger" />
+        </InkDoubleCheck>
+
+        <InkButton :text="t('settings.exportConfig')" @click="onExport" />
+        <InkButton :text="t('settings.importConfig')" @click="onImport" />
+      </div>
+      <p class="settings-view__export-note">{{ t('settings.exportExcludesSecret') }}</p>
+
+      <!-- Hidden file input for import -->
+      <input
+        ref="fileInput"
+        type="file"
+        accept=".json"
+        style="display: none"
+        @change="onFileSelected"
       />
+    </section>
 
-      <!-- Language Selection -->
-      <h2 class="settings-view__section-title">{{ t('settings.language') }}</h2>
-      <label class="settings-view__locale">
-        <span>{{ t('settings.languageLabel') }}</span>
-        <select v-model="currentLocale">
-          <option v-for="locale in SUPPORT_LOCALES" :key="locale" :value="locale">
-            {{ LOCALE_NAMES[locale] }}
-          </option>
-        </select>
-      </label>
-    </InkForm>
-
-    <!-- Action Buttons -->
-    <div class="settings-view__actions">
-      <InkButton :text="t('settings.saveConfig')" theme="primary" @click="onSave" />
-
-      <InkDoubleCheck
-        :title="t('settings.resetConfirmTitle')"
-        :message="t('settings.resetConfirmMessage')"
-        @confirm="onReset"
-      >
-        <InkButton :text="t('settings.resetConfig')" theme="danger" />
-      </InkDoubleCheck>
-
-      <InkButton :text="t('settings.exportConfig')" @click="onExport" />
-      <InkButton :text="t('settings.importConfig')" @click="onImport" />
-    </div>
-    <p class="settings-view__export-note">{{ t('settings.exportExcludesSecret') }}</p>
-
-    <!-- Hidden file input for import -->
-    <input
-      ref="fileInput"
-      type="file"
-      accept=".json"
-      style="display: none"
-      @change="onFileSelected"
-    />
+    <ClientList v-if="hasConnectedConfig" :key="allClientsRevision" />
   </main>
 </template>