diff --git a/docs/guide/build-your-own-hub-ui.md b/docs/guide/build-your-own-hub-ui.md
index 83258683..f1b582ed 100644
--- a/docs/guide/build-your-own-hub-ui.md
+++ b/docs/guide/build-your-own-hub-ui.md
@@ -16,6 +16,7 @@ interface DevframeHubUi {
   viewer?: { distDir: string } // a standalone SPA served at the hub base
   embedded?: { entry: string } // a self-contained bootstrap at <base>embedded.js
   assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
+  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
 }
 ```
 
@@ -24,6 +25,14 @@ prebuilt assets: the viewer SPA is built with relative asset paths, and the
 embedded entry is one self-contained ES module that mounts your dock into any
 host page.
 
+`setup(ctx)` runs once during hub init — write your static, boot-time config
+to `ctx.staticConfig`, which is serialized into `ConnectionMeta.configs` and
+read by the client from the one connection handshake it already performs. The
+reference UI's `createUi({ branding })` uses it to set
+`ctx.staticConfig.ui = { branding, … }`; the hub never interprets what you
+write. It's the structured, read-only counterpart to `assets` (arbitrary
+served files).
+
 ## The client contracts
 
 A viewer renders from the hub's shared state and drives it through
diff --git a/docs/guide/devframe-definition.md b/docs/guide/devframe-definition.md
index e389d7e4..f9500deb 100644
--- a/docs/guide/devframe-definition.md
+++ b/docs/guide/devframe-definition.md
@@ -113,6 +113,7 @@ interface DevframeNodeContext {
   diagnostics: DevframeDiagnosticsHost
   agent: DevframeAgentHost // experimental
   services: DevframeServicesHost // typed cross-plugin service registry
+  staticConfig: Partial<DevframeConnectionConfigsRegistry> // this context's own ConnectionMeta.configs
 
   scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
 }
@@ -130,6 +131,22 @@ ctx.services.whenAvailable('my-plugin:sources', (sources) => {
 })
 ```
 
+### Static connection configs
+
+`ctx.staticConfig` is this context's own `ConnectionMeta.configs` — static, boot-time data delivered once through the connection handshake every client already performs, and read-only from the browser. It's a plain, **non-reactive** object: write it during `setup(ctx)`, never during the session (it's serialized once, after setup). Contrast it with `ctx.scope(id).settings`, which is mutable and synced bidirectionally over shared-state RPC for the life of the session.
+
+```ts
+declare module 'devframe/types' {
+  interface DevframeConnectionConfigsRegistry {
+    'my-plugin': { featureFlag: boolean }
+  }
+}
+
+ctx.staticConfig['my-plugin'] = { featureFlag: true }
+```
+
+`updater` receives whatever's been contributed to that key so far (or `undefined` on the first contribution), so multiple contributors sharing a key — a hub aggregating each installed devframe's own preference, for example — own their own merge semantics (overwrite, shallow-merge a record, …) rather than the host imposing one.
+
 ### Storage scopes
 
 `ctx.host.getStorageDir(scope)` places persisted state in one of three classes:
@@ -152,6 +169,7 @@ Each devframe-level host has a dedicated page:
 - [Shared State](./shared-state) — `ctx.rpc.sharedState`
 - [Diagnostics](./diagnostics) — `ctx.diagnostics`
 - [Agent-Native](./agent-native) — `ctx.agent`
+- [Cross-Plugin Services](./services) — `ctx.services`
 
 ## Browser setup
 
diff --git a/docs/guide/hub-initiate.md b/docs/guide/hub-initiate.md
index 2ae4ab67..9499a080 100644
--- a/docs/guide/hub-initiate.md
+++ b/docs/guide/hub-initiate.md
@@ -56,10 +56,27 @@ The hub is headless — `DevframeHubUi` is pure data, and whoever fills it decid
 interface DevframeHubUi {
   viewer?: { distDir: string } // a standalone SPA served at the namespace root
   embedded?: { entry: string } // a prebuilt bootstrap served at <base>embedded.js
+  assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
+  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
 }
 ```
 
-`@devframes/hub-ui`'s `createUi()` is the reference implementation: a standalone viewer plus the floating dock — one `<script type="module" src="/__devframes/embedded.js">` tag in the host page and the dock mounts itself, always visible. A viewer product supplies a different object to the same slot and reuses all the infrastructure; visibility policy (keyboard summon, passive modes) belongs entirely to the entry's author.
+`@devframes/hub-ui`'s `createUi()` is the reference implementation: a standalone viewer plus the floating dock — one `<script type="module" src="/__devframes/embedded.js">` tag in the host page and the dock mounts itself. A viewer product supplies a different object to the same slot and reuses all the infrastructure. Its `setup(ctx)` publishes the reference UI's config to `ctx.staticConfig.ui`, which rides `ConnectionMeta.configs.ui` to the client.
+
+`createUi()` takes a few options:
+
+- **`branding`** — rebrand the reference UI (logo, product name, primary color).
+- **`dockPreferences`** — dock-bar rendering: `categoryOrder`, floating-dock `maxVisibleItems`, and the first-run `defaultMode` (`'float'` / `'edge'`) and `defaultPosition`.
+- **`embeddedVisibility`** — the floating dock's reveal policy:
+  - `'normal'` (default) — the dock is shown immediately.
+  - `'passive'` — the dock starts hidden with a console hint; `Shift+Alt+D` reveals it, and the reveal persists per-origin so later sessions start shown.
+  - `'hidden'` — the dock starts hidden; `Shift+Alt+D` reveals it for the current session only.
+
+```ts
+createUi({ embeddedVisibility: 'passive', dockPreferences: { defaultMode: 'edge' } })
+```
+
+Each seeds a user-overridable preference — the config sets the default, the visitor's own choice (reveal/hide, float/edge, …) wins from then on.
 
 ## Renderer modules
 
diff --git a/examples/hub-hono-minimal/src/app.ts b/examples/hub-hono-minimal/src/app.ts
index ea2846a3..8096a056 100644
--- a/examples/hub-hono-minimal/src/app.ts
+++ b/examples/hub-hono-minimal/src/app.ts
@@ -39,9 +39,9 @@ export const hub: HubInstance = globalRef.__hubHonoMinimal ??= initHub({
     createAssetsDevframe({ watch: false }),
   ],
   // Rebrand the reference UI to Hono's own orange — one field, no CSS:
-  // `createUi`'s `branding` option publishes `branding.json`, which the dock
-  // fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+  // which the dock reads at connect time and feeds into `--devframe-primary`
+  // (see `@devframes/hub-ui`'s `primary-ramp.css`).
   ui: createUi({ branding: { primaryColor: '#e36002', productName: 'Devframes on Hono' } }),
   // Gate with devframe's interactive OTP (the default). The hub prints a
   // 6-digit code + magic link on startup, and the reference UI's authorization
diff --git a/examples/hub-next-minimal/src/client/hub.ts b/examples/hub-next-minimal/src/client/hub.ts
index 4c33e5f8..28b32aeb 100644
--- a/examples/hub-next-minimal/src/client/hub.ts
+++ b/examples/hub-next-minimal/src/client/hub.ts
@@ -73,12 +73,13 @@ async function loadHub(): Promise<HubInstance> {
   // `@devframes/next/hub` runs the socket on a side-car (Next routes can't
   // accept WS upgrades). This host overrides the default UI slot to rebrand
   // the reference viewer to Next.js/Vercel's monochrome black — one field, no
-  // CSS: `createUi`'s `branding` option publishes `branding.json`, which the
-  // dock fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // CSS: `createUi`'s `branding` option publishes
+  // `ConnectionMeta.configs.ui.branding`, which the dock reads at connect
+  // time and feeds into `--devframe-primary` (see `@devframes/hub-ui`'s
+  // `primary-ramp.css`).
   return createNextDevframeHub({
     devframes,
-    ui: (hubUi.createUi as typeof CreateUi)({ branding: { primaryColor: '#000000', productName: 'Devframes on Next.js' } }),
+    ui: (hubUi.createUi as typeof CreateUi)({ branding: { primaryColor: '#3f8ba9', productName: 'Devframes on Next.js' } }),
     // Serve the reference json-render frontend as a prebuilt renderer module
     // — the one-liner that makes `'json-render'` docks render in the prebuilt
     // viewer. Swap it for any community implementation of the same contract.
diff --git a/examples/hub-nitro-minimal/hub.ts b/examples/hub-nitro-minimal/hub.ts
index bd9caa51..99599a85 100644
--- a/examples/hub-nitro-minimal/hub.ts
+++ b/examples/hub-nitro-minimal/hub.ts
@@ -42,9 +42,9 @@ export const hub: HubInstance = globalRef.__hubNitroMinimal ??= initHub({
     createAssetsDevframe({ watch: false }),
   ],
   // Rebrand the reference UI to Nitro's own pink/red — one field, no CSS:
-  // `createUi`'s `branding` option publishes `branding.json`, which the dock
-  // fetches at boot and feeds into `--devframe-primary` (see
-  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+  // which the dock reads at connect time and feeds into `--devframe-primary`
+  // (see `@devframes/hub-ui`'s `primary-ramp.css`).
   ui: createUi({ branding: { primaryColor: '#ff2056', productName: 'Devframes on Nitro' } }),
   // Gate with devframe's interactive OTP (the default). The hub prints a
   // 6-digit code + magic link on startup, and the reference UI's authorization
diff --git a/examples/hub-rsbuild-minimal/rsbuild.config.ts b/examples/hub-rsbuild-minimal/rsbuild.config.ts
index 16109b51..a90e079b 100644
--- a/examples/hub-rsbuild-minimal/rsbuild.config.ts
+++ b/examples/hub-rsbuild-minimal/rsbuild.config.ts
@@ -77,9 +77,10 @@ export default defineConfig({
         base,
         devframes: builtinDevframes,
         // Rebrand the reference UI to Rsbuild's own orange — one field, no
-        // CSS: `createUi`'s `branding` option publishes `branding.json`,
-        // which the dock fetches at boot and feeds into `--devframe-primary`
-        // (see `@devframes/hub-ui`'s `primary-ramp.css`).
+        // CSS: `createUi`'s `branding` option publishes
+        // `ConnectionMeta.configs.ui.branding`, which the dock reads at
+        // connect time and feeds into `--devframe-primary` (see
+        // `@devframes/hub-ui`'s `primary-ramp.css`).
         ui: createUi({ branding: { primaryColor: '#ff5e00', productName: 'Devframes on Rsbuild' } }),
         // Serve the reference json-render frontend as a prebuilt renderer
         // module — the one-liner that makes `'json-render'` docks render in
diff --git a/examples/hub-vite-minimal/vite.config.ts b/examples/hub-vite-minimal/vite.config.ts
index 2f7735ed..7122b7c3 100644
--- a/examples/hub-vite-minimal/vite.config.ts
+++ b/examples/hub-vite-minimal/vite.config.ts
@@ -67,10 +67,10 @@ export default defineConfig({
       quiet: true,
       devframes: builtinDevframes,
       // Rebrand the reference UI to Vite's own purple — one field, no CSS:
-      // `createUi`'s `branding` option publishes `branding.json`, which the
-      // dock fetches at boot and feeds into `--devframe-primary` (see
-      // `@devframes/hub-ui`'s `primary-ramp.css`). Passing `ui` overrides the
-      // default `createUi()` the plugin would otherwise use.
+      // `createUi`'s `branding` option publishes `ConnectionMeta.configs.ui.branding`,
+      // which the dock reads at connect time and feeds into `--devframe-primary`
+      // (see `@devframes/hub-ui`'s `primary-ramp.css`). Passing `ui` overrides
+      // the default `createUi()` the plugin would otherwise use.
       ui: createUi({ branding: { primaryColor: '#646cff', productName: 'Devframes on Vite' } }),
       // Serve the reference json-render frontend as a prebuilt renderer
       // module — the one-liner that makes `'json-render'` docks render in
diff --git a/packages/devframe/src/node/context.ts b/packages/devframe/src/node/context.ts
index 5e3cd7ce..6cab7897 100644
--- a/packages/devframe/src/node/context.ts
+++ b/packages/devframe/src/node/context.ts
@@ -44,6 +44,7 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
     diagnostics: undefined!,
     agent: undefined!,
     services: undefined!,
+    staticConfig: {},
     scope: undefined!,
   } as unknown as DevframeNodeContext
 
diff --git a/packages/devframe/src/node/instance-shell.ts b/packages/devframe/src/node/instance-shell.ts
index f887f7bf..2b76e587 100644
--- a/packages/devframe/src/node/instance-shell.ts
+++ b/packages/devframe/src/node/instance-shell.ts
@@ -589,6 +589,14 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
       ...(result.mcp ? { mcp: result.mcp } : {}),
     }
 
+    // Whatever `setup(ctx)` wrote to `ctx.staticConfig` during
+    // `options.init(api)` — e.g. a hub aggregating each installed devframe's
+    // own dock-bar preferences — is in by now; bake it into the meta
+    // `options.mount` (and every host that re-serves this same meta at
+    // another base) publishes.
+    if (Object.keys(ctx.staticConfig).length > 0)
+      meta.configs = ctx.staticConfig
+
     await options.mount?.(ctx, meta, api)
 
     // A pinned origin means the banner and registry record needn't wait for a
diff --git a/packages/devframe/src/types/context.ts b/packages/devframe/src/types/context.ts
index c322c80a..6f50d7ae 100644
--- a/packages/devframe/src/types/context.ts
+++ b/packages/devframe/src/types/context.ts
@@ -64,6 +64,22 @@ export interface DevframeNodeContext {
    * absorb setup-order differences between provider and consumer.
    */
   services: DevframeServicesHost
+  /**
+   * This context's own {@link ConnectionMeta.configs} — static, boot-time
+   * config a host publishes once through the connection handshake and every
+   * client reads read-only. A plain, **non-reactive** object: mutate it
+   * during `setup(ctx)` (a plugin sets its keys, a hub aggregates across
+   * every installed devframe), never during the session — it's serialized
+   * once, after setup, and changing it afterwards reaches no client.
+   *
+   * ```ts
+   * ctx.staticConfig.dock = {
+   *   ...ctx.staticConfig.dock,
+   *   categoryOrder: { ...ctx.staticConfig.dock?.categoryOrder, ...myOrder },
+   * }
+   * ```
+   */
+  staticConfig: Partial<DevframeConnectionConfigsRegistry>
   /**
    * Create a namespace-scoped view of this context. The returned
    * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
@@ -205,4 +221,36 @@ export interface ConnectionMeta {
    * token same-origin until the requesting origin has been verified.
    */
   viewerOriginToken?: string
+  /**
+   * Static, host-declared configuration — baked in once at connect time and
+   * fixed for the life of the server (e.g. a hub's UI rebrand, or its
+   * aggregated dock-bar layout preferences). Read-only from the browser: a
+   * client only ever reads `rpc.connectionMeta.configs`, never writes to it.
+   *
+   * Contrast this with {@link DevframeSettingsRegistry} (`ctx.scope(ns).settings`)
+   * and a hub's `devframe:user-settings` shared-state key — both are
+   * mutable, user-editable, and synced bidirectionally over RPC for the
+   * life of the session. `configs` is the opposite: one-way, immutable,
+   * decided by whoever assembled the server.
+   *
+   * Each key is owned by one package, contributed via declaration merging:
+   *
+   * ```ts
+   * declare module 'devframe/types' {
+   *   interface DevframeConnectionConfigsRegistry {
+   *     'my-key': { some: 'shape' }
+   *   }
+   * }
+   * ```
+   */
+  configs?: Partial<DevframeConnectionConfigsRegistry>
 }
+
+/**
+ * Augmentation point for {@link ConnectionMeta.configs}. Empty by default —
+ * a package that wants to publish static, boot-time config through the
+ * connection handshake augments this interface with its own key (see
+ * {@link ConnectionMeta.configs} for the pattern). `@devframes/hub`
+ * augments it with `dock`; `@devframes/hub-ui` augments it with `ui`.
+ */
+export interface DevframeConnectionConfigsRegistry {}
diff --git a/packages/hub-ui/src/client/components/DockEmbedded.ts b/packages/hub-ui/src/client/components/DockEmbedded.ts
index a00f0a6c..c17241d6 100644
--- a/packages/hub-ui/src/client/components/DockEmbedded.ts
+++ b/packages/hub-ui/src/client/components/DockEmbedded.ts
@@ -1,5 +1,6 @@
 import type { DocksContext } from '@devframes/hub/client'
 import type { VueElementConstructor } from 'vue'
+import type { DockLayout } from './dock/dock-layout'
 import { defineCustomElement } from 'vue'
 import css from '../.generated/css'
 import Component from './dock/DockEmbedded.vue'
@@ -12,6 +13,7 @@ export const DockEmbedded = defineCustomElement(
   },
 ) as VueElementConstructor<{
   context: DocksContext
+  layout?: Partial<DockLayout>
 }>
 
 customElements.define('devframes-dock-embedded', DockEmbedded)
diff --git a/packages/hub-ui/src/client/components/dock/DockEdge.vue b/packages/hub-ui/src/client/components/dock/DockEdge.vue
index f0255d81..64b13995 100644
--- a/packages/hub-ui/src/client/components/dock/DockEdge.vue
+++ b/packages/hub-ui/src/client/components/dock/DockEdge.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { DocksContext } from '@devframes/hub/client'
 import type { CSSProperties } from 'vue'
-import type { HubDocksUserSettings } from '../../state/dock-settings'
+import type { DevframeDocksUserSettings } from '../../state/dock-settings'
 import type { DockEdge as DockEdgePosition, DockLayout } from './dock-layout'
 import { useEventListener } from '@vueuse/core'
 import { computed, h, onMounted, ref, useTemplateRef } from 'vue'
@@ -24,7 +24,7 @@ const props = defineProps<{
 
 const context = props.context
 const store = context.panel.store
-const settings = sharedStateToRef<HubDocksUserSettings>(context.docks.settings)
+const settings = sharedStateToRef<DevframeDocksUserSettings>(context.docks.settings)
 const layout = computed(() => resolveDockLayout(props.layout))
 
 const viewsContainer = useTemplateRef<HTMLElement>('viewsContainer')
diff --git a/packages/hub-ui/src/client/components/views-builtin/SettingsAdvanced.vue b/packages/hub-ui/src/client/components/views-builtin/SettingsAdvanced.vue
index deda08eb..c2c78247 100644
--- a/packages/hub-ui/src/client/components/views-builtin/SettingsAdvanced.vue
+++ b/packages/hub-ui/src/client/components/views-builtin/SettingsAdvanced.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { DocksContext } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { HubDocksUserSettings } from '../../state/dock-settings'
+import type { DevframeDocksUserSettings } from '../../state/dock-settings'
 import { DEFAULT_STATE_USER_SETTINGS } from '@devframes/hub/constants'
 import { useBranding } from '../../state/branding'
 import { useConfirm } from '../../state/confirm'
@@ -9,7 +9,7 @@ import { sharedStateToRef } from '../../state/docks'
 
 const props = defineProps<{
   context: DocksContext
-  settingsStore: SharedState<HubDocksUserSettings>
+  settingsStore: SharedState<DevframeDocksUserSettings>
 }>()
 
 const settings = sharedStateToRef(props.settingsStore)
diff --git a/packages/hub-ui/src/client/components/views-builtin/SettingsAppearance.vue b/packages/hub-ui/src/client/components/views-builtin/SettingsAppearance.vue
index daebda34..9c14e22d 100644
--- a/packages/hub-ui/src/client/components/views-builtin/SettingsAppearance.vue
+++ b/packages/hub-ui/src/client/components/views-builtin/SettingsAppearance.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { DocksContext } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { HubDocksUserSettings } from '../../state/dock-settings'
+import type { DevframeDocksUserSettings } from '../../state/dock-settings'
 import { computed } from 'vue'
 import { useBranding } from '../../state/branding'
 import { colorSchemePreference, setColorSchemePreference } from '../../state/color-mode'
@@ -10,7 +10,7 @@ import { isDockPopupSupported, requestDockPopupOpen, useIsDockPopupOpen } from '
 
 const props = defineProps<{
   context: DocksContext
-  settingsStore: SharedState<HubDocksUserSettings>
+  settingsStore: SharedState<DevframeDocksUserSettings>
 }>()
 
 const settings = sharedStateToRef(props.settingsStore)
diff --git a/packages/hub-ui/src/client/components/views-builtin/SettingsDocks.vue b/packages/hub-ui/src/client/components/views-builtin/SettingsDocks.vue
index ea29142e..86035a88 100644
--- a/packages/hub-ui/src/client/components/views-builtin/SettingsDocks.vue
+++ b/packages/hub-ui/src/client/components/views-builtin/SettingsDocks.vue
@@ -2,7 +2,7 @@
 import type { DevframeDockEntry } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
-import type { DevframeDockEntriesGrouped, HubDocksUserSettings } from '../../state/dock-settings'
+import type { DevframeDockEntriesGrouped, DevframeDocksUserSettings } from '../../state/dock-settings'
 import { useDraggable } from '@vueuse/core'
 import { computed, ref, useTemplateRef } from 'vue'
 import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, isCategoryHideable } from '../../state/dock-settings'
@@ -12,7 +12,7 @@ import DockIcon from '../dock/DockIcon.vue'
 
 const props = defineProps<{
   context: DocksContext
-  settingsStore: SharedState<HubDocksUserSettings>
+  settingsStore: SharedState<DevframeDocksUserSettings>
 }>()
 
 const settings = sharedStateToRef(props.settingsStore)
diff --git a/packages/hub-ui/src/client/constants.ts b/packages/hub-ui/src/client/constants.ts
index f5f8691d..161f95f3 100644
--- a/packages/hub-ui/src/client/constants.ts
+++ b/packages/hub-ui/src/client/constants.ts
@@ -1,10 +1,10 @@
 import type { DevframeViewBuiltin } from '@devframes/hub'
 
 /**
- * `window` event the "Hide" command dispatches to ask whoever mounted the
- * embedded dock to tear it down for the session. The hub-ui dock is always
- * visible by design — hiding is a page-lifetime action, and a reload brings
- * the dock back (see `src/client/embedded/index.ts`).
+ * `window` event the "Hide" command dispatches to conceal the embedded dock.
+ * The embedded bootstrap's visibility controller catches it and detaches the
+ * dock; the `Shift+Alt+D` reveal shortcut (or, in `passive` mode, a later
+ * reload) brings it back (see `src/client/embedded/visibility.ts`).
  */
 export const HUB_UI_HIDE_EVENT = 'devframes:hub-ui:hide'
 
diff --git a/packages/hub-ui/src/client/dock-preferences.ts b/packages/hub-ui/src/client/dock-preferences.ts
new file mode 100644
index 00000000..b57a0ad0
--- /dev/null
+++ b/packages/hub-ui/src/client/dock-preferences.ts
@@ -0,0 +1,26 @@
+/**
+ * The reference UI's dock-bar rendering preferences, set via
+ * `createUi({ dockPreferences })` and published as
+ * `ConnectionMeta.configs.ui.dockPreferences`. Read by the embedded dock and
+ * the standalone viewer at boot.
+ *
+ * Like the float/edge dock mode, these seed user-overridable state — the
+ * config sets the default, the visitor's own choice wins from then on.
+ */
+export interface DevframeDockPreferences {
+  /**
+   * The top-level dock-bar **category** ordering — a map of category id →
+   * ordering weight (lower sorts earlier), merged beneath
+   * `DEFAULT_CATEGORIES_ORDER`.
+   */
+  categoryOrder?: Record<string, number>
+  /**
+   * Preferred inline-item capacity for the floating dock bar before entries
+   * overflow. Edge mode ignores it — it shows every entry with no cutoff.
+   */
+  maxVisibleItems?: number
+  /** Seeds a first-run visitor's dock mode (float vs edge). */
+  defaultMode?: 'float' | 'edge'
+  /** Seeds a first-run visitor's dock position. */
+  defaultPosition?: 'left' | 'right' | 'top' | 'bottom'
+}
diff --git a/packages/hub-ui/src/client/embedded/index.ts b/packages/hub-ui/src/client/embedded/index.ts
index b069a6af..e907cb19 100644
--- a/packages/hub-ui/src/client/embedded/index.ts
+++ b/packages/hub-ui/src/client/embedded/index.ts
@@ -1,16 +1,17 @@
 import type { DockPanelStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
 import { useLocalStorage } from '@vueuse/core'
-import { HUB_UI_HIDE_EVENT } from '../constants'
+import { applyPrimaryColor, setBranding } from '../state/branding'
 import { DEFAULT_DOCK_PANEL_STORE } from '../state/docks'
+import { setupEmbeddedVisibility } from './visibility'
 
 /**
  * The floating-dock bootstrap the hub serves at `<base>embedded.js` — load
  * it with one `<script type="module" src="<base>embedded.js">` tag and the
- * dock mounts immediately. Always visible by design: visibility policy
- * belongs to whoever authors an embedded entry, and this one's policy is
- * "you asked for devtools, here they are". The "Hide" command removes the
- * dock for the session; a reload brings it back.
+ * dock mounts itself. Its reveal policy is `ConnectionMeta.configs.ui.embeddedVisibility`
+ * (`normal` / `passive` / `hidden`): `normal` shows immediately, the others
+ * start hidden and reveal with `Shift+Alt+D`. The "Hide" command conceals the
+ * dock; the shortcut (or, for `passive`, a later reload) brings it back.
  */
 let dockEl: HTMLElement | undefined
 
@@ -39,37 +40,57 @@ async function mountDock(): Promise<void> {
     simpleAuth: false,
   })
 
+  // The reference UI's dock-bar preferences (`createUi({ dockPreferences })`),
+  // delivered once via the connection handshake we just performed — fixed for
+  // the life of this server, never re-fetched.
+  const dockPreferences = rpc.connectionMeta.configs?.ui?.dockPreferences
+
+  const defaultStore = DEFAULT_DOCK_PANEL_STORE()
   const state = useLocalStorage<DockPanelStorage>(
     'devframes-dock-state',
-    DEFAULT_DOCK_PANEL_STORE(),
+    {
+      ...defaultStore,
+      // Seed a first-run visitor's mode/position from the configured
+      // defaults — `useLocalStorage`'s own `mergeDefaults` already limits
+      // this to a visitor with no stored preference yet.
+      ...(dockPreferences?.defaultMode ? { mode: dockPreferences.defaultMode } : {}),
+      ...(dockPreferences?.defaultPosition ? { position: dockPreferences.defaultPosition } : {}),
+    },
     { mergeDefaults: true },
   )
 
   // Resolve branding before the dock exists so the primary color and logo are
-  // in place on the first paint. Fetched from `<base>branding.json` (served
-  // where this script is), then overridden by any host-page channel.
-  const { resolveBranding, applyPrimaryColor } = await import('../state/branding')
-  const branding = await resolveBranding({
-    mode: 'embedded',
-    brandingUrl: new URL('branding.json', import.meta.url),
-  })
+  // in place on the first paint. Read from `ConnectionMeta.configs.ui.branding`,
+  // carried by the connection we just established above.
+  const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
 
   const { createDocksContext } = await import('../state/context')
   const context = await createDocksContext('embedded', rpc, state)
   setDevframeClientContext(context)
 
   const { DockEmbedded } = await import('../components/DockEmbedded')
-  dockEl = new DockEmbedded({ context }) as unknown as HTMLElement
+  dockEl = new DockEmbedded({
+    context,
+    ...(dockPreferences?.maxVisibleItems !== undefined ? { layout: { maxVisibleItems: dockPreferences.maxVisibleItems } } : {}),
+  }) as unknown as HTMLElement
   // Inline on the host element — beats the generated `:host` ramp defaults and
   // inherits through the shadow tree. The embedded bootstrap never touches the
   // host page's <title>/favicon (it's a guest there).
   applyPrimaryColor(dockEl, branding.primaryColor)
-  document.body.appendChild(dockEl)
-}
 
-window.addEventListener(HUB_UI_HIDE_EVENT, () => {
-  dockEl?.remove()
-  dockEl = undefined
-})
+  // Reveal policy: `normal` appends now; `passive`/`hidden` wait for the
+  // Shift+Alt+D reveal (the element is built and ready, just detached).
+  setupEmbeddedVisibility(
+    rpc.connectionMeta.configs?.ui?.embeddedVisibility ?? 'normal',
+    branding.productName,
+    {
+      show: () => {
+        if (dockEl && !dockEl.isConnected)
+          document.body.appendChild(dockEl)
+      },
+      hide: () => dockEl?.remove(),
+    },
+  )
+}
 
 void mountDock()
diff --git a/packages/hub-ui/src/client/embedded/visibility.ts b/packages/hub-ui/src/client/embedded/visibility.ts
new file mode 100644
index 00000000..50527854
--- /dev/null
+++ b/packages/hub-ui/src/client/embedded/visibility.ts
@@ -0,0 +1,134 @@
+import { HUB_UI_HIDE_EVENT } from '../constants'
+
+/**
+ * How the embedded floating dock reveals itself on a fresh page — the
+ * reference UI's port of Nuxt DevTools' opt-in overlay, published as
+ * `ConnectionMeta.configs.ui.embeddedVisibility` and set via
+ * `createUi({ embeddedVisibility })`.
+ *
+ * - `normal` (default) — the dock is shown immediately.
+ * - `passive` — the dock starts hidden and a console hint offers the reveal
+ *   shortcut; revealing persists per-origin, so later sessions on this
+ *   browser start shown. The "Hide" command returns to passive.
+ * - `hidden` — the dock starts hidden and the shortcut reveals it for the
+ *   current session only; nothing is persisted.
+ *
+ * Whatever the policy, the reveal state is a user-overridable preference —
+ * the same shape as the float/edge dock mode: the config seeds it, the
+ * visitor's own reveal/hide wins from then on.
+ */
+export type EmbeddedVisibility = 'normal' | 'passive' | 'hidden'
+
+/** Per-origin persisted reveal flag for `passive` mode. */
+const REVEAL_STORAGE_KEY = 'devframes-dock-revealed'
+
+function readPersistedReveal(): boolean {
+  try {
+    return localStorage.getItem(REVEAL_STORAGE_KEY) === 'true'
+  }
+  catch {
+    return false
+  }
+}
+
+function persistReveal(revealed: boolean): void {
+  try {
+    if (revealed)
+      localStorage.setItem(REVEAL_STORAGE_KEY, 'true')
+    else
+      localStorage.removeItem(REVEAL_STORAGE_KEY)
+  }
+  catch {
+    // Private-mode / disabled storage: reveal stays session-only, which is a
+    // safe degradation — the dock is still reachable via the shortcut.
+  }
+}
+
+function isMac(): boolean {
+  return typeof navigator !== 'undefined' && /mac/i.test(navigator.userAgent)
+}
+
+/** The reveal shortcut label, `Shift+Alt+D` (`⇧⌥D` on macOS). */
+function revealShortcutLabel(): string {
+  return isMac() ? '⇧⌥D' : 'Shift+Alt+D'
+}
+
+function printHint(label: string): void {
+  // Intentional user-facing hint (not a diagnostic) — the whole point of
+  // passive mode is this one console line pointing at the reveal shortcut.
+  // eslint-disable-next-line no-console
+  console.info(
+    `%c${label}%c is in passive mode — press %c${revealShortcutLabel()}%c to reveal the devtools.`,
+    'font-weight:bold',
+    '',
+    'font-weight:bold',
+    '',
+  )
+}
+
+/** `true` when the event is the reveal chord (Shift+Alt+D), layout-agnostic. */
+function isRevealChord(e: KeyboardEvent): boolean {
+  return e.shiftKey && e.altKey && !e.ctrlKey && !e.metaKey && e.code === 'KeyD'
+}
+
+export interface EmbeddedVisibilityHandlers {
+  /** Mount/attach the dock element. */
+  show: () => void
+  /** Detach the dock element. */
+  hide: () => void
+}
+
+/**
+ * Drive the embedded dock's reveal lifecycle for the resolved
+ * {@link EmbeddedVisibility} mode: decide whether to show on boot, wire the
+ * reveal shortcut and the "Hide" command's {@link HUB_UI_HIDE_EVENT}, and
+ * persist the reveal for `passive`.
+ *
+ * `label` is the resolved product name, used in the passive-mode console hint.
+ */
+export function setupEmbeddedVisibility(
+  mode: EmbeddedVisibility,
+  label: string,
+  handlers: EmbeddedVisibilityHandlers,
+): void {
+  let shown = mode === 'normal' || (mode === 'passive' && readPersistedReveal())
+
+  function reveal(): void {
+    if (shown)
+      return
+    shown = true
+    if (mode === 'passive')
+      persistReveal(true)
+    handlers.show()
+  }
+
+  function conceal(): void {
+    if (!shown)
+      return
+    shown = false
+    // `normal`/`hidden` hide for the session only; `passive` remembers it so
+    // the next load starts hidden again.
+    if (mode === 'passive')
+      persistReveal(false)
+    handlers.hide()
+  }
+
+  if (shown)
+    handlers.show()
+  else if (mode === 'passive')
+    printHint(label)
+
+  // Shift+Alt+D toggles the dock — the always-available "summon" chord.
+  window.addEventListener('keydown', (e) => {
+    if (!isRevealChord(e))
+      return
+    e.preventDefault()
+    if (shown)
+      conceal()
+    else
+      reveal()
+  }, { capture: true })
+
+  // The in-dock "Hide" command asks to conceal (reload/shortcut brings it back).
+  window.addEventListener(HUB_UI_HIDE_EVENT, conceal)
+}
diff --git a/packages/hub-ui/src/client/standalone/main.ts b/packages/hub-ui/src/client/standalone/main.ts
index ba4c9511..39dabd12 100644
--- a/packages/hub-ui/src/client/standalone/main.ts
+++ b/packages/hub-ui/src/client/standalone/main.ts
@@ -1,5 +1,6 @@
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
 import { watchEffect } from 'vue'
+import { applyDocumentHead, applyPrimaryColor, setBranding } from '../state/branding'
 import { isDark } from '../state/color-mode'
 
 // The standalone viewer — a vanilla shell served at the hub base itself
@@ -30,12 +31,10 @@ async function main(): Promise<void> {
   })
 
   // Resolve branding before mount; the standalone page owns its own head, so
-  // apply title/favicon/description here too.
-  const { resolveBranding, applyPrimaryColor, applyDocumentHead } = await import('../state/branding')
-  const branding = await resolveBranding({
-    mode: 'standalone',
-    brandingUrl: new URL('branding.json', document.baseURI),
-  })
+  // apply title/favicon/description here too. Read from
+  // `ConnectionMeta.configs.ui.branding`, carried by the connection we just
+  // established above.
+  const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
   applyDocumentHead(document, branding)
 
   const { createDocksContext } = await import('../state/context')
diff --git a/packages/hub-ui/src/client/state/branding.ts b/packages/hub-ui/src/client/state/branding.ts
index 9d4ad73e..d9c6ebcb 100644
--- a/packages/hub-ui/src/client/state/branding.ts
+++ b/packages/hub-ui/src/client/state/branding.ts
@@ -11,11 +11,12 @@ export type BrandingLogo = string | { light: string, dark: string }
 
 /**
  * Consumer-facing branding for the reference hub-ui. Every field is optional
- * and falls back to devframe's own identity. Delivered three ways, merged
- * field-by-field (later wins): the `branding.json` `createUi({ branding })`
- * publishes, then the host page (a `window.__DEVFRAME_BRANDING__` global or
- * `data-*` attrs on the embedding `<script>`, or `?query` params on the
- * standalone viewer).
+ * and falls back to devframe's own identity. Published as
+ * `ConnectionMeta.configs.ui.branding` via `createUi({ branding })`, and
+ * read from the one connection handshake the dock already performs —
+ * `ConnectionMeta` has its own cross-realm propagation (see
+ * `DEVFRAME_CONNECTION_KEY`), so branding needs no globals or query params
+ * of its own.
  */
 export interface DevframeBranding {
   /** Product name — the wordmark, window titles, and all user-visible copy. */
@@ -86,112 +87,6 @@ function resolveLogo(logo: BrandingLogo | undefined, dark: boolean): string | un
   return dark ? (logo.dark || logo.light) : logo.light
 }
 
-// --- Merge + host-page reading -------------------------------------------
-
-/** Field-level merge; later layers override earlier ones (empty values skip). */
-function mergeBranding(...layers: Array<DevframeBranding | undefined>): DevframeBranding {
-  const out: DevframeBranding = {}
-  for (const layer of layers) {
-    if (!layer || typeof layer !== 'object')
-      continue
-    for (const key of Object.keys(layer) as (keyof DevframeBranding)[]) {
-      const value = layer[key]
-      if (value !== undefined && value !== null && value !== '')
-        (out as Record<string, unknown>)[key] = value
-    }
-  }
-  return out
-}
-
-function readWindowGlobal(): DevframeBranding | undefined {
-  const global = (globalThis as { __DEVFRAME_BRANDING__?: unknown }).__DEVFRAME_BRANDING__
-  return global && typeof global === 'object' ? global as DevframeBranding : undefined
-}
-
-const SCRIPT_ATTR_MAP: Record<string, keyof DevframeBranding> = {
-  'data-product-name': 'productName',
-  'data-primary-color': 'primaryColor',
-  'data-logo': 'logo',
-  'data-tagline': 'tagline',
-  'data-window-title': 'windowTitle',
-}
-
-function findEmbeddedScript(): HTMLScriptElement | null {
-  if (typeof document === 'undefined')
-    return null
-  const current = document.currentScript as HTMLScriptElement | null
-  if (current?.src)
-    return current
-  const scripts = Array.from(document.querySelectorAll('script[src]')) as HTMLScriptElement[]
-  return scripts.find(script => /embedded\.js(?:$|[?#])/.test(script.src)) ?? null
-}
-
-function readScriptDataAttrs(): DevframeBranding {
-  const out: DevframeBranding = {}
-  const script = findEmbeddedScript()
-  if (!script)
-    return out
-  for (const [attr, key] of Object.entries(SCRIPT_ATTR_MAP)) {
-    const value = script.getAttribute(attr)
-    if (value != null)
-      (out as Record<string, unknown>)[key] = value
-  }
-  return out
-}
-
-const QUERY_PARAM_MAP: Record<string, keyof DevframeBranding> = {
-  productName: 'productName',
-  primaryColor: 'primaryColor',
-  logo: 'logo',
-  tagline: 'tagline',
-  windowTitle: 'windowTitle',
-}
-
-function readQueryParams(): DevframeBranding {
-  const out: DevframeBranding = {}
-  if (typeof location === 'undefined')
-    return out
-  const params = new URLSearchParams(location.search)
-  for (const [param, key] of Object.entries(QUERY_PARAM_MAP)) {
-    const value = params.get(param)
-    if (value != null)
-      (out as Record<string, unknown>)[key] = value
-  }
-  return out
-}
-
-async function fetchBrandingJson(url: string | URL): Promise<DevframeBranding | undefined> {
-  try {
-    const res = await fetch(url)
-    if (!res.ok)
-      return undefined
-    const json = await res.json()
-    return json && typeof json === 'object' ? json as DevframeBranding : undefined
-  }
-  catch {
-    // A missing branding.json (embedded-only without the assets seam, offline,
-    // etc.) is expected — fall back to defaults + any host-page override.
-    return undefined
-  }
-}
-
-/**
- * Resolve branding at boot: fetch the served `branding.json`, layer the
- * host-page channels over it (they win per field), install the result, and
- * return it. Awaited before the dock element mounts, so branding is applied on
- * the first paint.
- */
-export async function resolveBranding(options: {
-  mode: 'embedded' | 'standalone'
-  brandingUrl: string | URL
-}): Promise<ResolvedBranding> {
-  const fetched = await fetchBrandingJson(options.brandingUrl)
-  const hostPage = options.mode === 'embedded'
-    ? mergeBranding(readScriptDataAttrs(), readWindowGlobal())
-    : mergeBranding(readQueryParams(), readWindowGlobal())
-  return setBranding(mergeBranding(fetched, hostPage))
-}
-
 // --- Applying to the DOM --------------------------------------------------
 
 /** Set the primary color on the dock host element (retints the whole ramp). */
diff --git a/packages/hub-ui/src/client/state/commands.ts b/packages/hub-ui/src/client/state/commands.ts
index 1a216703..ab6d9eba 100644
--- a/packages/hub-ui/src/client/state/commands.ts
+++ b/packages/hub-ui/src/client/state/commands.ts
@@ -1,9 +1,8 @@
-import type { DevframeClientCommand, DevframeCommandEntry, DevframeCommandKeybinding, DevframeServerCommandEntry } from '@devframes/hub'
+import type { DevframeClientCommand, DevframeCommandEntry, DevframeCommandKeybinding, DevframeDocksUserSettings, DevframeServerCommandEntry } from '@devframes/hub'
 import type { CommandsContext, DevframeRpcClient } from '@devframes/hub/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { ShallowRef } from 'vue'
-import type { HubDocksUserSettings } from '../types'
 import { evaluateWhen } from 'devframe/utils/when'
 import { computed, markRaw, reactive, ref, watch } from 'vue'
 import { sharedStateToRef } from './docks'
@@ -15,7 +14,7 @@ const commandsContextByRpc = new WeakMap<DevframeRpcClient, CommandsContext>()
 export async function createCommandsContext(
   clientType: 'embedded' | 'standalone',
   rpc: DevframeRpcClient,
-  settingsState: SharedState<HubDocksUserSettings>,
+  settingsState: SharedState<DevframeDocksUserSettings>,
   whenContextProvider?: () => WhenContext,
 ): Promise<CommandsContext> {
   if (commandsContextByRpc.has(rpc)) {
diff --git a/packages/hub-ui/src/client/state/context.ts b/packages/hub-ui/src/client/state/context.ts
index 1df7ed40..07771410 100644
--- a/packages/hub-ui/src/client/state/context.ts
+++ b/packages/hub-ui/src/client/state/context.ts
@@ -3,11 +3,11 @@ import type { CommandsContext, DevframeRpcClient, DockClientScriptContext, DockE
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
-import type { HubDocksUserSettings } from './dock-settings'
+import type { DevframeDocksUserSettings } from './dock-settings'
 import { attachFrameNavClient } from '@devframes/hub/client'
 import { DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY } from '@devframes/hub/constants'
 import { computed, markRaw, reactive, ref, toRefs, watch, watchEffect } from 'vue'
-import { BUILTIN_ENTRIES, BUILTIN_ENTRY_SETTINGS, HUB_UI_HIDE_EVENT } from '../constants'
+import { BUILTIN_ENTRIES, BUILTIN_ENTRY_SETTINGS, DEFAULT_CATEGORIES_ORDER, HUB_UI_HIDE_EVENT } from '../constants'
 import { useBranding } from './branding'
 import { createCommandsContext } from './commands'
 import { docksGroupByCategories, getCategoryLabel, getGroupMembers, getGroupMembersGrouped, getRegisteredGroupIds, resolveCommandIcon, resolveGroupDefaultChild } from './dock-settings'
@@ -134,7 +134,7 @@ export async function createDocksContext(
   panelStore ||= ref(DEFAULT_DOCK_PANEL_STORE())
   let docksContext: DocksContext
 
-  let _settingsStorePromise: Promise<SharedState<HubDocksUserSettings>> | undefined
+  let _settingsStorePromise: Promise<SharedState<DevframeDocksUserSettings>> | undefined
   const getSettingsStore = async () => {
     if (!_settingsStorePromise) {
       _settingsStorePromise = rpc.sharedState.get(
@@ -353,8 +353,12 @@ export async function createDocksContext(
 
   // Settings store, `settings`, and `getWhenContext` are established earlier
   // (right before `switchEntry`) — its group→member resolution needs them.
+  // `categoryOrderOverride` folds in the reference UI's configured
+  // `dockPreferences.categoryOrder` (`createUi({ dockPreferences })`),
+  // delivered once via the connection handshake.
+  const categoryOrderOverride = rpc.connectionMeta.configs?.ui?.dockPreferences?.categoryOrder
   const groupedEntries = computed(() => {
-    return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true })
+    return docksGroupByCategories(entries.value, settings.value, { whenContext: getWhenContext(), collapseGroups: true, categoryOrderOverride })
   })
 
   // Initialize commands context with reactive when-context
@@ -404,8 +408,8 @@ export async function createDocksContext(
       // explicit visit and stays mounted.
       when: 'clientType == embedded',
       action: () => {
-        // Ask whoever mounted the embedded dock to tear it down for this
-        // session — a reload brings it back.
+        // Conceal the embedded dock — the Shift+Alt+D reveal shortcut (or a
+        // reload) brings it back. In passive mode this is remembered.
         window.dispatchEvent(new CustomEvent(HUB_UI_HIDE_EVENT))
       },
     },
@@ -511,6 +515,7 @@ export async function createDocksContext(
       entries,
       entryToStateMap: markRaw(dockEntryStateMap),
       groupedEntries,
+      categoryOrder: categoryOrderOverride ? { ...DEFAULT_CATEGORIES_ORDER, ...categoryOrderOverride } : DEFAULT_CATEGORIES_ORDER,
       settings: settingsStore,
       getStateById: (id: string) => dockEntryStateMap.get(id),
       switchEntry,
diff --git a/packages/hub-ui/src/client/state/dock-settings.ts b/packages/hub-ui/src/client/state/dock-settings.ts
index d882053c..5e7f3d6a 100644
--- a/packages/hub-ui/src/client/state/dock-settings.ts
+++ b/packages/hub-ui/src/client/state/dock-settings.ts
@@ -1,12 +1,13 @@
-import type { DevframeDockEntriesGrouped, DevframeDockEntry, DevframeViewGroup } from '@devframes/hub'
+import type { DevframeDockEntriesGrouped, DevframeDockEntry, DevframeDocksUserSettings, DevframeViewGroup } from '@devframes/hub'
 import type { Immutable } from 'devframe/utils/shared-state'
 import type { WhenContext } from 'devframe/utils/when'
-import type { HubDocksUserSettings } from '../types'
 import { evaluateWhen } from 'devframe/utils/when'
 import { DEFAULT_CATEGORIES_ORDER, INSPECTOR_DOCK_ID } from '../constants'
+// Registers hub-ui's reference-viewer settings onto DevframeDocksUserSettings.
+import '../types'
 
-export type { HubDocksUserSettings }
 export type { DevframeDockEntriesGrouped }
+export type { DevframeDocksUserSettings }
 
 /**
  * Synthetic category that collects pinned dock entries. Pinning re-buckets an
@@ -141,7 +142,7 @@ export function getEntryGroup(
 export function getGroupMembersGrouped(
   entries: DevframeDockEntry[],
   groupId: string,
-  settings?: Immutable<HubDocksUserSettings>,
+  settings?: Immutable<DevframeDocksUserSettings>,
   options?: { includeHidden?: boolean, whenContext?: WhenContext },
 ): DevframeDockEntriesGrouped {
   const members = entries.filter(e => e.type !== 'group' && e.groupId === groupId)
@@ -165,7 +166,7 @@ export function getGroupMembersGrouped(
 export function getGroupMembers(
   entries: DevframeDockEntry[],
   groupId: string,
-  settings?: Immutable<HubDocksUserSettings>,
+  settings?: Immutable<DevframeDocksUserSettings>,
   options?: { includeHidden?: boolean, whenContext?: WhenContext },
 ): DevframeDockEntry[] {
   return getGroupMembersGrouped(entries, groupId, settings, options).flatMap(([, items]) => items)
@@ -248,7 +249,7 @@ export function resolveGroupDefaultChild(
  */
 export function docksGroupByCategories(
   entries: DevframeDockEntry[],
-  settings: Immutable<HubDocksUserSettings>,
+  settings: Immutable<DevframeDocksUserSettings>,
   options?: { includeHidden?: boolean, whenContext?: WhenContext, collapseGroups?: boolean, ignoreCategoryHidden?: boolean, categoryOrderOverride?: Record<string, number> },
 ): DevframeDockEntriesGrouped {
   const { docksHidden, docksCategoriesHidden, docksCustomOrder, docksPinned } = settings
diff --git a/packages/hub-ui/src/client/stories/mock-context.ts b/packages/hub-ui/src/client/stories/mock-context.ts
index e4bc87d3..8678bb79 100644
--- a/packages/hub-ui/src/client/stories/mock-context.ts
+++ b/packages/hub-ui/src/client/stories/mock-context.ts
@@ -1,6 +1,5 @@
-import type { DevframeDockEntry } from '@devframes/hub'
+import type { DevframeDockEntry, DevframeDocksUserSettings } from '@devframes/hub'
 import type { DevframeRpcClient, DockPanelStorage, DocksContext, RpcClientEvents } from '@devframes/hub/client'
-import type { HubDocksUserSettings } from '../types'
 import { DEFAULT_STATE_USER_SETTINGS } from '@devframes/hub/constants'
 import { createEventEmitter } from 'devframe/utils/events'
 import { createSharedState } from 'devframe/utils/shared-state'
@@ -27,7 +26,7 @@ export interface CreateMockContextOptions {
   /** Overrides merged over the default panel store (mode, position, open, ...). */
   panel?: Partial<DockPanelStorage>
   /** Overrides merged over the default user settings (hidden, pinned, order, ...). */
-  settings?: Partial<HubDocksUserSettings>
+  settings?: Partial<DevframeDocksUserSettings>
   /** Entry id to pre-select (also opens the panel). */
   selectedId?: string | null
   /** Initial trust state. Defaults to `true`. */
@@ -36,7 +35,7 @@ export interface CreateMockContextOptions {
 
 function createMockRpc(
   entries: DevframeDockEntry[],
-  settings: Partial<HubDocksUserSettings>,
+  settings: Partial<DevframeDocksUserSettings>,
   initialTrusted: boolean,
 ): MockRpcClient {
   const docksState = createSharedState({ initialValue: entries, enablePatches: false })
diff --git a/packages/hub-ui/src/client/types.ts b/packages/hub-ui/src/client/types.ts
index 1fe4d601..f30e46eb 100644
--- a/packages/hub-ui/src/client/types.ts
+++ b/packages/hub-ui/src/client/types.ts
@@ -1,24 +1,36 @@
-import type { DevframeDocksUserSettings, DevframeViewLauncher } from '@devframes/hub/types'
+import type { DevframeViewLauncher } from '@devframes/hub/types'
 // Importing the hub-mounted json-render integration registers its
 // `'json-render'` dock entry (a serializable `view` ref, not a live handle)
 // on the hub's open dock union via declaration merging.
 import '@devframes/json-render/hub'
 
 /**
- * hub-ui user settings — the hub's {@link DevframeDocksUserSettings} widened
- * with the toggles only this viewer ships.
- *
- * The extra fields are optional so the hub's `DEFAULT_STATE_USER_SETTINGS()`
- * (which knows nothing about them) stays assignable; an absent value reads as
- * its documented default.
+ * hub-ui's reference-viewer settings, merged onto the hub's generic
+ * {@link DevframeDocksUserSettings} — the hub core stays unaware of them.
+ * Every field is optional so the hub's `DEFAULT_STATE_USER_SETTINGS()` (which
+ * knows nothing about them) stays assignable; an absent value reads as the
+ * documented default.
  */
-export interface HubDocksUserSettings extends DevframeDocksUserSettings {
-  /**
-   * Reveal the Devframe Inspector dock (the "devtools for the devtools"
-   * meta-introspection panel). Hidden by default — an absent value keeps the
-   * dock out of the dock bar until the user opts in from Settings → Advanced.
-   */
-  showDevframeInspector?: boolean
+declare module '@devframes/hub/types' {
+  interface DevframeDocksUserSettings {
+    /** Show the address-bar chrome on iframe dock views. Defaults to shown. */
+    showIframeAddressBar?: boolean
+    /** Close the floating dock panel when clicking outside it. */
+    closeOnOutsideClick?: boolean
+    /**
+     * Auto-collapse the edge-mode toolbar to a small handle when idle (no
+     * hover or drag) and the panel content is closed, instead of permanently
+     * spanning the full edge. Off by default — an absent value preserves the
+     * default edge-mode behavior; opt in from Settings → Appearance.
+     */
+    autoCollapseEdgeToolbar?: boolean
+    /**
+     * Reveal the Devframe Inspector dock (the "devtools for the devtools"
+     * meta-introspection panel). Hidden by default — an absent value keeps the
+     * dock out of the dock bar until the user opts in from Settings → Advanced.
+     */
+    showDevframeInspector?: boolean
+  }
 }
 
 /**
diff --git a/packages/hub-ui/src/index.ts b/packages/hub-ui/src/index.ts
index 8dfe2ad3..ba198408 100644
--- a/packages/hub-ui/src/index.ts
+++ b/packages/hub-ui/src/index.ts
@@ -1,11 +1,25 @@
 import type { DevframeHubUi } from '@devframes/hub/initiate'
+import type { DevframeDockPreferences } from './client/dock-preferences'
+import type { EmbeddedVisibility } from './client/embedded/visibility'
 import type { DevframeBranding } from './client/state/branding'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+export type { DevframeDockPreferences } from './client/dock-preferences'
+export type { EmbeddedVisibility } from './client/embedded/visibility'
 export type { DevframeBranding } from './client/state/branding'
 
+declare module 'devframe/types' {
+  interface DevframeConnectionConfigsRegistry {
+    ui: {
+      branding?: DevframeBranding
+      embeddedVisibility?: EmbeddedVisibility
+      dockPreferences?: DevframeDockPreferences
+    }
+  }
+}
+
 /**
  * The built client assets live next to the built entry (`dist/index.mjs` →
  * `dist/client/`). When this module runs from source instead (tests and
@@ -29,12 +43,33 @@ export interface CreateUiOptions {
   embedded?: boolean
   /**
    * Rebrand the reference UI — logo, product name, primary color, and more.
-   * Published as `<base>branding.json` (via the hub's generic `assets` seam)
-   * and fetched by the dock at boot. Reaches both the embedded dock and the
-   * standalone viewer. A host page can still override any field at runtime via
-   * `window.__DEVFRAME_BRANDING__` / `<script data-*>` / `?query` params.
+   * Published as `ConnectionMeta.configs.ui.branding`, read by the dock at
+   * boot from the one connection handshake it already performs. Reaches
+   * both the embedded dock and the standalone viewer.
    */
   branding?: DevframeBranding
+  /**
+   * How the embedded floating dock reveals itself on a fresh page:
+   *
+   * - `'normal'` (default) — shown immediately.
+   * - `'passive'` — starts hidden with a console hint; `Shift+Alt+D` reveals
+   *   it, and the reveal persists per-origin so later sessions start shown.
+   * - `'hidden'` — starts hidden; `Shift+Alt+D` reveals it for the current
+   *   session only.
+   *
+   * Published as `ConnectionMeta.configs.ui.embeddedVisibility`. Like the
+   * float/edge dock mode, it seeds a user-overridable preference — the
+   * visitor's own reveal/hide wins from then on. Applies to the embedded
+   * dock only; the standalone viewer is an explicit visit and always shows.
+   */
+  embeddedVisibility?: EmbeddedVisibility
+  /**
+   * Dock-bar rendering preferences — category ordering, floating-dock
+   * inline-item capacity, and the first-run float/edge mode and position.
+   * Published as `ConnectionMeta.configs.ui.dockPreferences`; each seeds a
+   * user-overridable preference the visitor's own choice then wins.
+   */
+  dockPreferences?: DevframeDockPreferences
 }
 
 /**
@@ -63,6 +98,15 @@ export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
     ...(options.embedded !== false
       ? { embedded: { entry: join(client, 'embedded.js') } }
       : {}),
-    assets: { 'branding.json': () => JSON.stringify(options.branding || {}) },
+    // Publish the reference UI's config through the generic `ctx.staticConfig`
+    // — it rides the connection handshake to every mounted frame and the
+    // standalone viewer as `ConnectionMeta.configs.ui`.
+    setup(ctx) {
+      ctx.staticConfig.ui = {
+        branding: options.branding || {},
+        ...(options.embeddedVisibility ? { embeddedVisibility: options.embeddedVisibility } : {}),
+        ...(options.dockPreferences ? { dockPreferences: options.dockPreferences } : {}),
+      }
+    },
   }
 }
diff --git a/packages/hub/src/client/__tests__/host.test.ts b/packages/hub/src/client/__tests__/host.test.ts
index 37dad14a..8b358fc9 100644
--- a/packages/hub/src/client/__tests__/host.test.ts
+++ b/packages/hub/src/client/__tests__/host.test.ts
@@ -157,6 +157,22 @@ describe('createDevframeClientHost', () => {
     host.dispose()
   })
 
+  it('merges the host-page categoryOrder option beneath DEFAULT_CATEGORIES_ORDER', async () => {
+    const { rpc, states } = createStubRpc()
+    const host = await createDevframeClientHost({ rpc, categoryOrder: { app: -200, web: 999 } })
+
+    states.get('devframe:docks')!.push([
+      iframeEntry('app-entry', { category: 'app' }),
+      iframeEntry('web-entry', { category: 'web' }),
+      iframeEntry('framework-entry', { category: 'framework' }),
+    ])
+
+    expect(host.context.docks.categoryOrder).toMatchObject({ app: -200, web: 999, framework: -100 })
+    // `app` (-200, from the option) now sorts ahead of `framework` (-100, default).
+    expect(host.context.docks.groupedEntries.map(([cat]) => cat)).toEqual(['app', 'framework', 'web'])
+    host.dispose()
+  })
+
   it('switches entries with activation/deactivation events and when-context updates', async () => {
     const { rpc, states } = createStubRpc()
     const host = await createDevframeClientHost({ rpc })
diff --git a/packages/hub/src/client/docks.ts b/packages/hub/src/client/docks.ts
index 54194dc6..4eba597f 100644
--- a/packages/hub/src/client/docks.ts
+++ b/packages/hub/src/client/docks.ts
@@ -95,6 +95,14 @@ export interface DocksEntriesContext {
   entries: DevframeDockEntry[]
   entryToStateMap: Map<string, DockEntryState>
   groupedEntries: DevframeDockEntriesGrouped
+  /**
+   * The resolved top-level category ordering — `DEFAULT_CATEGORIES_ORDER`,
+   * overridden by every installed devframe's own `dock.categoryOrder`
+   * (`ConnectionMeta.configs.dock.categoryOrder`), overridden again by the
+   * host page's own `createDevframeClientHost({ categoryOrder })`. Fixed
+   * for the life of the session — resolved once at boot.
+   */
+  readonly categoryOrder: Record<string, number>
   settings: SharedState<DevframeDocksUserSettings>
   /**
    * Get the state of a dock entry by its ID
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index 7bef46a1..55c073e4 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -80,7 +80,7 @@ export interface DevframeClientHostOptions {
    *
    * Keys are merged over `DEFAULT_CATEGORIES_ORDER`, so the host app only
    * lists the categories it wants to move; any category absent from the map
-   * keeps its default weight (falling back to `0`).
+   * keeps its default weight.
    *
    * @example
    * ```ts
@@ -136,6 +136,13 @@ export async function createDevframeClientHost(
   const frameNavAdapters = new Map<string, () => void>()
   const loadScriptsEnabled = options.loadClientScripts ?? true
 
+  // Resolved once at boot, fixed for the session: the default table overridden
+  // by this host page's own explicit option.
+  const categoryOrder: Record<string, number> = {
+    ...DEFAULT_CATEGORIES_ORDER,
+    ...options.categoryOrder,
+  }
+
   const panel = createPanelContext(clientType)
   const docks = createDocksContext()
   const commands = createCommandsContext()
@@ -322,7 +329,7 @@ export async function createDevframeClientHost(
     }
 
     docks.entries = entries
-    docks.groupedEntries = groupByCategory(entries)
+    docks.groupedEntries = groupByCategory(entries, categoryOrder)
     if (selectedId && !entryToStateMap.has(selectedId))
       selectedId = null
   }
@@ -341,6 +348,7 @@ export async function createDevframeClientHost(
       entries: [],
       entryToStateMap,
       groupedEntries: [],
+      categoryOrder,
       settings,
       getStateById: id => entryToStateMap.get(id),
       switchEntry,
@@ -522,7 +530,7 @@ function createPanelContext(clientType: DockClientType): DocksPanelContext {
   }
 }
 
-function groupByCategory(entries: DevframeDockEntry[]): DevframeDockEntriesGrouped {
+function groupByCategory(entries: DevframeDockEntry[], categoryOrder: Record<string, number>): DevframeDockEntriesGrouped {
   // Index registered groups so a member whose `groupId` resolves takes its
   // OUTER bucket from the group's category, not its own (which becomes the
   // member's in-group sub-category). Orphan members — a `groupId` with no
@@ -547,6 +555,6 @@ function groupByCategory(entries: DevframeDockEntry[]): DevframeDockEntriesGroup
     list.push(entry)
   }
   return [...groups.entries()].sort(
-    ([a], [b]) => (DEFAULT_CATEGORIES_ORDER[a] ?? 0) - (DEFAULT_CATEGORIES_ORDER[b] ?? 0),
+    ([a], [b]) => (categoryOrder[a] ?? 0) - (categoryOrder[b] ?? 0),
   )
 }
diff --git a/packages/hub/src/constants.ts b/packages/hub/src/constants.ts
index f9859a88..35179d0b 100644
--- a/packages/hub/src/constants.ts
+++ b/packages/hub/src/constants.ts
@@ -38,7 +38,5 @@ export const DEFAULT_STATE_USER_SETTINGS: () => DevframeDocksUserSettings = () =
   docksCategoriesHidden: [],
   docksPinned: [],
   docksCustomOrder: {},
-  showIframeAddressBar: false,
-  closeOnOutsideClick: false,
   commandShortcuts: {},
 })
diff --git a/packages/hub/src/node/__tests__/initiate.test.ts b/packages/hub/src/node/__tests__/initiate.test.ts
index a59777e2..51c666a6 100644
--- a/packages/hub/src/node/__tests__/initiate.test.ts
+++ b/packages/hub/src/node/__tests__/initiate.test.ts
@@ -174,6 +174,54 @@ describe('initHub', () => {
     }
   })
 
+  it('serves whatever the ui slot\'s setup(ctx) writes to ctx.staticConfig as ConnectionMeta.configs', async () => {
+    const wsPort = await getPort({ port: 18225, host: '127.0.0.1' })
+    const alpha = makeFrame('alpha', makeDist('<!doctype html><title>frame a</title>'))
+
+    const hub = initHub({
+      base: DEVFRAMES_HUB_BASE,
+      auth: false,
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+      devframes: [alpha],
+      ui: {
+        setup(ctx) {
+          ;(ctx.staticConfig as Record<string, unknown>).ui = { branding: { productName: 'Test Hub' } }
+        },
+      },
+    })
+
+    try {
+      await hub.ready
+      const origin = 'http://localhost:5173'
+
+      // The hub's own meta carries what the ui slot published…
+      const hubMeta = await (await hub.handler(new Request(`${origin}/__devframes/__connection.json`))).json()
+      expect(hubMeta.configs).toEqual({ ui: { branding: { productName: 'Test Hub' } } })
+
+      // …and every per-frame meta carries the identical document.
+      const frameMeta = await (await hub.handler(new Request(`${origin}/__devframes/alpha/__connection.json`))).json()
+      expect(frameMeta.configs).toEqual(hubMeta.configs)
+    }
+    finally {
+      await hub.close()
+    }
+  })
+
+  it('omits ConnectionMeta.configs entirely when the ui slot writes nothing', async () => {
+    const wsPort = await getPort({ port: 18226, host: '127.0.0.1' })
+    const hub = initHub({ base: DEVFRAMES_HUB_BASE, auth: false, host: '127.0.0.1', ws: { port: wsPort }, devframes: [makeFrame('alpha')] })
+
+    try {
+      await hub.ready
+      const meta = await (await hub.handler(new Request(`http://localhost:5173/__devframes/__connection.json`))).json()
+      expect(meta.configs).toBeUndefined()
+    }
+    finally {
+      await hub.close()
+    }
+  })
+
   it('aggregate MCP: one endpoint lists tools from every mounted frame', async () => {
     const wsPort = await getPort({ port: 18230, host: '127.0.0.1' })
     const hub = initHub({ base: DEVFRAMES_HUB_BASE, auth: false, host: '127.0.0.1', ws: { port: wsPort }, mcp: true, devframes: [makeFrame('alpha'), makeFrame('beta')] })
diff --git a/packages/hub/src/node/initiate.ts b/packages/hub/src/node/initiate.ts
index 1a736c82..f75c04aa 100644
--- a/packages/hub/src/node/initiate.ts
+++ b/packages/hub/src/node/initiate.ts
@@ -119,12 +119,22 @@ export interface DevframeHubUi {
   }
   /**
    * Extra UI-owned files the hub serves at `<base><key>`, each produced lazily
-   * from memory. Keys are base-relative paths (e.g. `branding.json`); the
-   * content-type is inferred from the key's extension. A generic seam a viewer
-   * uses to publish small runtime documents (the reference UI serves its
-   * branding this way) without teaching the hub anything about their meaning.
+   * from memory. Keys are base-relative paths; the content-type is inferred
+   * from the key's extension. A generic seam a viewer uses to publish
+   * arbitrary runtime documents without teaching the hub anything about
+   * their meaning.
    */
   assets?: Record<string, () => string | Uint8Array>
+  /**
+   * A setup hook run once during hub init with the hub context — the UI
+   * slot's chance to publish its own static, boot-time config through the
+   * generic `ctx.staticConfig` (serialized into `ConnectionMeta.configs`).
+   * The reference UI's `createUi()` uses it to set
+   * `ctx.staticConfig.ui = { branding, … }`, reaching every mounted frame and
+   * the standalone viewer through the one connection handshake they perform.
+   * The hub stays policy-free about what the UI writes.
+   */
+  setup?: (ctx: DevframeHubContext) => void | Promise<void>
 }
 
 export type DevframesInput = Array<
@@ -485,6 +495,12 @@ export function initHub(options: InitHubOptions): HubInstance {
 
       await options.configure?.(ctx)
 
+      // The UI slot publishes its own static config (branding, dock
+      // preferences, …) into `ctx.staticConfig` — run last so it can see the
+      // installed devframes. The instance shell serializes `ctx.staticConfig`
+      // into the connection meta right after this `init` returns.
+      await options.ui?.setup?.(ctx)
+
       // Publish the renderer manifest — one `ClientScriptEntry` per dock
       // `type`, `importFrom` base-absolute so it resolves to the served module
       // from any page depth. Clients read it from shared state and import a
@@ -523,6 +539,10 @@ export function initHub(options: InitHubOptions): HubInstance {
     },
 
     mount(ctx, meta) {
+      // `meta.configs` already carries whatever `ctx.staticConfig` collected
+      // during init — the UI slot's `setup(ctx)` (branding, dock preferences,
+      // …) and any devframe's own contributions. Nothing to add here.
+
       // Hub-level discovery endpoints, registered before the viewer's static
       // mount so its SPA-fallback can't swallow them.
       app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta)
@@ -572,9 +592,9 @@ export function initHub(options: InitHubOptions): HubInstance {
         })
       }
 
-      // UI-owned assets (e.g. the reference viewer's `branding.json`), served
-      // from memory. Registered before the viewer's SPA catch-all so these exact
-      // routes win, mirroring the discovery endpoints above.
+      // UI-owned assets, served from memory. Registered before the viewer's
+      // SPA catch-all so these exact routes win, mirroring the discovery
+      // endpoints above.
       for (const [key, produce] of Object.entries(options.ui?.assets ?? {})) {
         app.use(joinURL(base, key), (event) => {
           event.res.headers.set('Content-Type', assetContentType(key))
diff --git a/packages/hub/src/types/settings.ts b/packages/hub/src/types/settings.ts
index 6ff453b6..32f4da7e 100644
--- a/packages/hub/src/types/settings.ts
+++ b/packages/hub/src/types/settings.ts
@@ -1,19 +1,32 @@
 import type { DevframeCommandShortcutOverrides } from './commands'
 
+/**
+ * Persisted per-user dock + command settings, synced over the
+ * `devframe:user-settings` shared state. The generic base carries the hub's
+ * own dock-registry and command model that every viewer shares; a viewer
+ * augments it with its own reference-UI toggles via declaration merging:
+ *
+ * ```ts
+ * declare module '@devframes/hub/types' {
+ *   interface DevframeDocksUserSettings {
+ *     myViewerToggle?: boolean
+ *   }
+ * }
+ * ```
+ *
+ * Augmented fields are optional so the hub's `DEFAULT_STATE_USER_SETTINGS()`
+ * (which knows nothing about them) stays assignable — an absent value reads
+ * as the viewer's documented default.
+ */
 export interface DevframeDocksUserSettings {
+  /** Ids of dock entries the user has hidden from the bar. */
   docksHidden: string[]
+  /** Category ids the user has collapsed/hidden on the bar. */
   docksCategoriesHidden: string[]
+  /** Ids of dock entries the user has pinned. */
   docksPinned: string[]
+  /** Per-entry sort weight overriding the registry's default order. */
   docksCustomOrder: Record<string, number>
-  showIframeAddressBar: boolean
-  closeOnOutsideClick: boolean
+  /** Per-command keybinding overrides (empty array = shortcut disabled). */
   commandShortcuts: DevframeCommandShortcutOverrides
-  /**
-   * Auto-collapse the edge-mode toolbar to a small handle when idle (no
-   * hover or drag) and the panel content is closed, instead of permanently
-   * spanning the full edge. Off by default — an absent value preserves
-   * today's edge-mode behavior for existing users; opt in from
-   * Settings → Appearance.
-   */
-  autoCollapseEdgeToolbar?: boolean
 }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
index 1de3a0a3..38bfd4a1 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
@@ -6,6 +6,8 @@ export interface CreateUiOptions {
   viewer?: boolean;
   embedded?: boolean;
   branding?: DevframeBranding;
+  embeddedVisibility?: EmbeddedVisibility;
+  dockPreferences?: DevframeDockPreferences;
 }
 export interface DevframeBranding {
   productName?: string;
@@ -16,6 +18,16 @@ export interface DevframeBranding {
   favicon?: string;
   windowTitle?: string;
 }
+export interface DevframeDockPreferences {
+  categoryOrder?: Record<string, number>;
+  maxVisibleItems?: number;
+  defaultMode?: 'float' | 'edge';
+  defaultPosition?: 'left' | 'right' | 'top' | 'bottom';
+}
+// #endregion
+
+// #region Types
+export type EmbeddedVisibility = 'normal' | 'passive' | 'hidden';
 // #endregion
 
 // #region Functions
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 0f0daa53..a3940459 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -97,6 +97,7 @@ export interface DocksEntriesContext {
   entries: DevframeDockEntry[];
   entryToStateMap: Map<string, DockEntryState>;
   groupedEntries: DevframeDockEntriesGrouped;
+  readonly categoryOrder: Record<string, number>;
   settings: SharedState<DevframeDocksUserSettings>;
   getStateById: (_: string) => DockEntryState | undefined;
   switchEntry: (_?: string | null) => Promise<boolean>;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
index 93346b37..3906052a 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
@@ -122,10 +122,7 @@ export interface DevframeDocksUserSettings {
   docksCategoriesHidden: string[];
   docksPinned: string[];
   docksCustomOrder: Record<string, number>;
-  showIframeAddressBar: boolean;
-  closeOnOutsideClick: boolean;
   commandShortcuts: DevframeCommandShortcutOverrides;
-  autoCollapseEdgeToolbar?: boolean;
 }
 export interface DevframeHubContext extends DevframeNodeContext {
   readonly host: DevframeHost;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
index 489cc7ad..19a6e873 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
@@ -10,6 +10,7 @@ export interface DevframeHubUi {
     entry: string;
   };
   assets?: Record<string, () => string | Uint8Array>;
+  setup?: (_: DevframeHubContext) => void | Promise<void>;
 }
 export interface DockRendererRegistration {
   type: string;
diff --git a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts
index 86ecc7c1..8d837a04 100644
--- a/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts
@@ -75,6 +75,7 @@ export interface ConnectionMeta {
   baseUrl?: string;
   authToken?: string;
   viewerOriginToken?: string;
+  configs?: Partial<DevframeConnectionConfigsRegistry>;
 }
 export interface ConnectionMetaSse {
   path?: string;
@@ -128,6 +129,7 @@ export interface DevframeCliOptions {
   configure?: (_: CAC) => void;
   flags?: CliFlagsSchema;
 }
+export interface DevframeConnectionConfigsRegistry {}
 export interface DevframeDefineDiagnosticsOptions<Codes extends Record<string, DiagnosticDefinition>> {
   docsBase?: string | ((_: keyof Codes) => string | undefined);
   codes: Codes;
@@ -191,6 +193,7 @@ export interface DevframeNodeContext {
   diagnostics: DevframeDiagnosticsHost;
   agent: DevframeAgentHost;
   services: DevframeServicesHost;
+  staticConfig: Partial<DevframeConnectionConfigsRegistry>;
   scope: {
     <NS extends string>(_: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>;
     (_?: null | ''): DevframeNodeContext;
diff --git a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts
index 89f6a49d..481ccc85 100644
--- a/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts
@@ -19,6 +19,7 @@ export { DevframeAgentHostEvents }
 export { DevframeBrowserContext }
 export { DevframeCapabilities }
 export { DevframeCliOptions }
+export { DevframeConnectionConfigsRegistry }
 export { DevframeDefineDiagnosticsOptions }
 export { DevframeDefinition }
 export { DevframeDeploymentKind }
diff --git a/tests/exports.test.ts b/tests/exports.test.ts
index 4ffdea6f..21cddfd5 100644
--- a/tests/exports.test.ts
+++ b/tests/exports.test.ts
@@ -5,6 +5,12 @@ import { describePackagesApiSnapshots } from 'tsnapi/vitest'
 describePackagesApiSnapshots({
   cwd: fileURLToPath(new URL('..', import.meta.url)),
   filter(ctx) {
+    // Only snapshot first-party workspace packages. Auto-discovery can walk
+    // into `node_modules` depending on the installed layout (e.g. pnpm's
+    // `shamefullyHoist`), which would try to snapshot dependencies like
+    // `@babel/runtime` and crash on their directory-valued `exports`.
+    if (/[\\/]node_modules[\\/]/.test(ctx.packageRoot))
+      return false
     const pkg = JSON.parse(
       readFileSync(`${ctx.packageRoot}/package.json`, 'utf8'),
     )