diff --git a/AGENTS.md b/AGENTS.md
index a9f0edf03..b9a5675fc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -150,7 +150,7 @@ Concise but detailed reference for contributors working across the `moeru-ai/air
 
 ## Readability, Naming, and Comments
 
-- File names: camelCase.
+- Use kebab-case for all file names.
 - Prefer names that rely on the module boundary for context instead of repeating package, product, protocol, or transport prefixes inside every symbol. A well-named module should let exported functions use short action-first names; repeat the larger context only when the symbol crosses a boundary where that context is no longer obvious.
 - Name functions after the domain operation they perform, not after the implementation layer that happens to contain them. This keeps call sites readable after refactors and avoids names becoming stale when code moves between files.
 - Avoid names that encode multiple layers of ownership into one symbol. If a name needs several qualifiers to be understandable, reconsider the module boundary or introduce a clearer local concept.
diff --git a/apps/stage-pocket/src/main.ts b/apps/stage-pocket/src/main.ts
index ea3e71595..584baa7b2 100644
--- a/apps/stage-pocket/src/main.ts
+++ b/apps/stage-pocket/src/main.ts
@@ -6,6 +6,7 @@ import NProgress from 'nprogress'
 
 import { autoAnimatePlugin } from '@formkit/auto-animate/vue'
 import { isEnvTruthy } from '@proj-airi/stage-shared'
+import { trackButtonPlugin } from '@proj-airi/stage-ui/directives/track-button'
 import { MotionPlugin } from '@vueuse/motion'
 import { createPinia } from 'pinia'
 import { setupLayouts } from 'virtual:generated-layouts'
@@ -60,6 +61,7 @@ createApp(App)
   .use(pinia)
   .use(i18n)
   .use(Tres)
+  .use(trackButtonPlugin)
   .mount('#app')
 
 if (import.meta.env.DEV && !import.meta.env.SSR) {
diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-fade-on-hover.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-fade-on-hover.vue
index d18f2b0c4..efb9f25b3 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-fade-on-hover.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/controls-island-fade-on-hover.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { useElectronEventaInvoke } from '@proj-airi/electron-vueuse'
+import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
@@ -21,18 +22,30 @@ const props = withDefaults(defineProps<Props>(), {
 const uiStore = useControlsIslandStore()
 const enabled = computed(() => uiStore.fadeOnHoverEnabled)
 const { t } = useI18n()
+const { trackControlsIslandAction } = useAnalytics()
 
 const requestNotice = useElectronEventaInvoke(noticeWindowEventa.openWindow)
 const NOTICE_WINDOW_ID = 'fade-on-hover'
 
+function setFadeOnHoverEnabled(value: boolean) {
+  if (value)
+    uiStore.enableFadeOnHover()
+  else
+    uiStore.disableFadeOnHover()
+
+  trackControlsIslandAction({
+    action: value ? 'enable_fade_on_hover' : 'disable_fade_on_hover',
+  })
+}
+
 async function handleToggle() {
   if (enabled.value) {
-    uiStore.disableFadeOnHover()
+    setFadeOnHoverEnabled(false)
     return
   }
 
   if (uiStore.dontShowItAgainNoticeFadeOnHover) {
-    uiStore.enableFadeOnHover()
+    setFadeOnHoverEnabled(true)
     return
   }
 
@@ -42,8 +55,9 @@ async function handleToggle() {
       route: '/notice/fade-on-hover',
       type: 'fade-on-hover',
     })
-    if (acknowledged)
-      uiStore.enableFadeOnHover()
+    if (acknowledged) {
+      setFadeOnHoverEnabled(true)
+    }
   }
   catch (error) {
     console.error('Failed to open fade-on-hover notice:', error)
@@ -55,6 +69,7 @@ async function handleToggle() {
   <ControlButtonTooltip>
     <ControlButton
       :button-style="props.buttonStyle"
+      :aria-label="enabled ? t('tamagotchi.stage.controls-island.fade-on-hover.disable') : t('tamagotchi.stage.controls-island.fade-on-hover.enable')"
       :class="{ 'border-primary-300/70 shadow-[0_10px_24px_rgba(0,0,0,0.22)]': enabled }"
       @click="handleToggle"
     >
diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 3f477fcf6..68f9418d0 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -38,7 +38,7 @@ const { alwaysOnTop, controlsIslandIconSize } = storeToRefs(settingsStore)
 const openSettings = useElectronEventaInvoke(electronOpenSettings)
 const openChat = useElectronEventaInvoke(electronOpenChat)
 const isLinux = useElectronEventaInvoke(electron.app.isLinux)
-const closeWindow = useElectronEventaInvoke(electronAppQuit)
+const quitApp = useElectronEventaInvoke(electronAppQuit)
 const setAlwaysOnTop = useElectronEventaInvoke(electronWindowSetAlwaysOnTop)
 const centerMainWindow = useElectronEventaInvoke(electronCenterMainWindow)
 
@@ -94,6 +94,10 @@ function toggleAlwaysOnTop() {
   alwaysOnTop.value = !alwaysOnTop.value
 }
 
+function toggleControls() {
+  expanded.value = !expanded.value
+}
+
 // Grouped classes for icon / border / padding and combined style class
 const adjustStyleClasses = computed(() => {
   let isLarge: boolean
@@ -158,7 +162,12 @@ function resetMainWindowPosition() {
 
           <div grid grid-cols-3 gap-2>
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" @click="openSettings({ route: '/settings' })">
+              <ControlButton
+                v-track-button="{ name: 'controls_island_action', action: 'toggle_settings' }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="t('tamagotchi.stage.controls-island.open-settings')"
+                @click="openSettings({ route: '/settings' })"
+              >
                 <div i-solar:settings-minimalistic-outline :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
               </ControlButton>
               <template #tooltip>
@@ -169,7 +178,12 @@ function resetMainWindowPosition() {
             <ControlButtonTooltip disable-hoverable-content>
               <ControlsIslandProfilePicker placement="up" :open="blockingOverlays.has('profile-picker')" @update:open="setOverlay('profile-picker', $event)">
                 <template #default="{ toggle }">
-                  <ControlButton :button-style="adjustStyleClasses.button" @click="toggle">
+                  <ControlButton
+                    v-track-button="{ name: 'controls_island_action', action: 'toggle_profile_picker' }"
+                    :button-style="adjustStyleClasses.button"
+                    :aria-label="t('tamagotchi.stage.controls-island.switch-profile')"
+                    @click="toggle"
+                  >
                     <div i-solar:emoji-funny-square-broken :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
                   </ControlButton>
                 </template>
@@ -180,7 +194,12 @@ function resetMainWindowPosition() {
             </ControlButtonTooltip>
 
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" @click="refreshWindow">
+              <ControlButton
+                v-track-button="{ name: 'controls_island_action', action: 'refresh_window' }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="t('tamagotchi.stage.controls-island.refresh')"
+                @click="refreshWindow"
+              >
                 <div i-solar:refresh-linear :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
               </ControlButton>
               <template #tooltip>
@@ -189,7 +208,12 @@ function resetMainWindowPosition() {
             </ControlButtonTooltip>
 
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" @click="resetMainWindowPosition()">
+              <ControlButton
+                v-track-button="{ name: 'controls_island_action', action: 'center_main_window' }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="t('tamagotchi.stage.controls-island.center-main-window')"
+                @click="resetMainWindowPosition"
+              >
                 <div i-solar:target-linear :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
               </ControlButton>
               <template #tooltip>
@@ -198,7 +222,15 @@ function resetMainWindowPosition() {
             </ControlButtonTooltip>
 
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" @click="toggleDark()">
+              <ControlButton
+                v-track-button="{
+                  name: 'controls_island_action',
+                  action: isDark ? 'switch_to_light_mode' : 'switch_to_dark_mode',
+                }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="isDark ? t('tamagotchi.stage.controls-island.switch-to-light-mode') : t('tamagotchi.stage.controls-island.switch-to-dark-mode')"
+                @click="() => toggleDark()"
+              >
                 <Transition name="fade" mode="out-in">
                   <div v-if="isDark" i-solar:moon-outline :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
                   <div v-else i-solar:sun-2-outline :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
@@ -210,7 +242,15 @@ function resetMainWindowPosition() {
             </ControlButtonTooltip>
 
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" @click="toggleAlwaysOnTop()">
+              <ControlButton
+                v-track-button="{
+                  name: 'controls_island_action',
+                  action: alwaysOnTop ? 'unpin_from_top' : 'pin_on_top',
+                }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="alwaysOnTop ? t('tamagotchi.stage.controls-island.unpin-from-top') : t('tamagotchi.stage.controls-island.pin-on-top')"
+                @click="toggleAlwaysOnTop"
+              >
                 <div v-if="alwaysOnTop" i-solar:pin-bold :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
                 <div v-else i-solar:pin-linear :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300 opacity-50" />
               </ControlButton>
@@ -222,7 +262,14 @@ function resetMainWindowPosition() {
             <ControlsIslandFadeOnHover :icon-class="adjustStyleClasses.icon" :button-style="adjustStyleClasses.button" />
 
             <ControlButtonTooltip disable-hoverable-content>
-              <ControlButton :button-style="adjustStyleClasses.button" hover:bg-red-500 hover:text-white @click="closeWindow()">
+              <ControlButton
+                v-track-button="{ name: 'controls_island_action', action: 'close_app' }"
+                :button-style="adjustStyleClasses.button"
+                :aria-label="t('tamagotchi.stage.controls-island.close')"
+                hover:bg-red-500
+                hover:text-white
+                @click="() => quitApp()"
+              >
                 <div i-solar:close-circle-outline :class="adjustStyleClasses.icon" />
               </ControlButton>
               <template #tooltip>
@@ -236,7 +283,15 @@ function resetMainWindowPosition() {
       <!-- Main Controls -->
       <div flex flex-col gap-1>
         <ControlButtonTooltip side="left">
-          <ControlButton :button-style="adjustStyleClasses.button" @click="expanded = !expanded">
+          <ControlButton
+            v-track-button="{
+              name: 'controls_island_action',
+              action: expanded ? 'collapse_controls' : 'expand_controls',
+            }"
+            :button-style="adjustStyleClasses.button"
+            :aria-label="expanded ? t('tamagotchi.stage.controls-island.collapse') : t('tamagotchi.stage.controls-island.expand')"
+            @click="toggleControls"
+          >
             <div
               :class="[adjustStyleClasses.icon, expanded ? 'rotate-180' : 'rotate-0']"
               i-solar:alt-arrow-up-line-duotone scale-110 transition-all duration-300
@@ -249,7 +304,12 @@ function resetMainWindowPosition() {
         </ControlButtonTooltip>
 
         <ControlButtonTooltip side="left">
-          <ControlButton :button-style="adjustStyleClasses.button" @click="openChat">
+          <ControlButton
+            v-track-button="{ name: 'controls_island_action', action: 'toggle_chat' }"
+            :button-style="adjustStyleClasses.button"
+            :aria-label="t('tamagotchi.stage.controls-island.open-chat')"
+            @click="() => openChat()"
+          >
             <div i-solar:chat-line-line-duotone :class="adjustStyleClasses.icon" text="neutral-800 dark:neutral-300" />
           </ControlButton>
           <template #tooltip>
diff --git a/apps/stage-tamagotchi/src/renderer/main.ts b/apps/stage-tamagotchi/src/renderer/main.ts
index fa0a4fbe5..2d5232e5d 100644
--- a/apps/stage-tamagotchi/src/renderer/main.ts
+++ b/apps/stage-tamagotchi/src/renderer/main.ts
@@ -5,6 +5,7 @@ import Tres from '@tresjs/core'
 
 import { autoAnimatePlugin } from '@formkit/auto-animate/vue'
 import { PiniaColada } from '@pinia/colada'
+import { trackButtonPlugin } from '@proj-airi/stage-ui/directives/track-button'
 import { MotionPlugin } from '@vueuse/motion'
 import { createPinia } from 'pinia'
 import { setupLayouts } from 'virtual:generated-layouts'
@@ -53,4 +54,5 @@ createApp(App)
   .use(PiniaColada)
   .use(i18n)
   .use(Tres)
+  .use(trackButtonPlugin)
   .mount('#app')
diff --git a/apps/stage-tamagotchi/src/renderer/pages/about.vue b/apps/stage-tamagotchi/src/renderer/pages/about.vue
index b7272dd16..3cab98476 100644
--- a/apps/stage-tamagotchi/src/renderer/pages/about.vue
+++ b/apps/stage-tamagotchi/src/renderer/pages/about.vue
@@ -33,7 +33,6 @@ const {
 } = useElectronAutoUpdater()
 
 const {
-  trackUpdateCheckClicked,
   trackUpdateDownloaded,
   trackUpdateInstallClicked,
   trackSettingsChanged,
@@ -126,11 +125,6 @@ const isDowngradeUpdate = computed(() => {
 const getUpdaterPreferences = useElectronEventaInvoke(electronGetUpdaterPreferences)
 const setUpdaterPreferences = useElectronEventaInvoke(electronSetUpdaterPreferences)
 
-function handleCheckForUpdates() {
-  trackUpdateCheckClicked({ channel: selectedUpdateChannel.value })
-  return checkForUpdates()
-}
-
 function handleQuitAndInstall() {
   trackUpdateInstallClicked({ channel: selectedUpdateChannel.value, version: updateState.value.info?.version })
   quitAndInstall()
@@ -384,6 +378,7 @@ onMounted(() => {
 
                 <div :class="['flex flex-wrap gap-2']">
                   <Button
+                    v-track-button="{ name: 'update_check_clicked', channel: selectedUpdateChannel }"
                     :variant="isError ? 'caution' : 'secondary'"
                     :loading="isBusy"
                     :disabled="isDisabled"
@@ -397,7 +392,7 @@ onMounted(() => {
                           : isError
                             ? t('tamagotchi.stage.about.update.actions.retry-check')
                             : t('tamagotchi.stage.about.update.actions.check-for-updates')"
-                    @click="handleCheckForUpdates()"
+                    @click="checkForUpdates()"
                   />
                 </div>
               </div>
diff --git a/apps/stage-tamagotchi/src/renderer/pages/settings/modules/mcp.vue b/apps/stage-tamagotchi/src/renderer/pages/settings/modules/mcp.vue
index 8dcd24e8e..c51dc171b 100644
--- a/apps/stage-tamagotchi/src/renderer/pages/settings/modules/mcp.vue
+++ b/apps/stage-tamagotchi/src/renderer/pages/settings/modules/mcp.vue
@@ -42,7 +42,7 @@ import {
 } from './mcp-config'
 
 const { t } = useI18n()
-const { trackMcpServerAdded, trackMcpServerRemoved, trackMcpConnectionTestRun } = useAnalytics()
+const { trackMcpServerRemoved, trackMcpConnectionTestRun } = useAnalytics()
 const tn = (key: string, params?: Record<string, unknown>) => t(`settings.pages.modules.mcp-server.${key}`, params ?? {})
 
 const invokeOpenConfigFile = useElectronEventaInvoke(electronMcpOpenConfigFile)
@@ -215,7 +215,6 @@ function formatJsonDraft() {
 function addServer() {
   const server = createServerForm()
   servers.value.push(server)
-  trackMcpServerAdded()
   if (!testRowId.value)
     testRowId.value = server.rowId
 }
@@ -476,6 +475,7 @@ onMounted(async () => {
       </article>
 
       <Button
+        v-track-button="{ name: 'mcp_server_added' }"
         variant="secondary-muted" size="md" block :disabled="isBusy"
         icon="i-solar:add-circle-bold-duotone" :label="tn('actions.add-server')"
         @click="addServer"
diff --git a/apps/stage-web/src/main.ts b/apps/stage-web/src/main.ts
index f1ad59b80..58c361083 100644
--- a/apps/stage-web/src/main.ts
+++ b/apps/stage-web/src/main.ts
@@ -7,6 +7,7 @@ import NProgress from 'nprogress'
 import { autoAnimatePlugin } from '@formkit/auto-animate/vue'
 import { PiniaColada } from '@pinia/colada'
 import { isEnvTruthy } from '@proj-airi/stage-shared'
+import { trackButtonPlugin } from '@proj-airi/stage-ui/directives/track-button'
 import { MotionPlugin } from '@vueuse/motion'
 import { createPinia } from 'pinia'
 import { setupLayouts } from 'virtual:generated-layouts'
@@ -55,6 +56,7 @@ createApp(App)
   .use(PiniaColada)
   .use(i18n)
   .use(Tres)
+  .use(trackButtonPlugin)
   .mount('#app')
 
 if (import.meta.env.DEV && !import.meta.env.SSR) {
diff --git a/packages/stage-ui/README.md b/packages/stage-ui/README.md
index 8e0efd4dc..f379d9e00 100644
--- a/packages/stage-ui/README.md
+++ b/packages/stage-ui/README.md
@@ -2,6 +2,31 @@
 
 Shared core for stage
 
+## Button analytics
+
+Register the shared plugin once in each Vue application:
+
+```ts
+import { trackButtonPlugin } from '@proj-airi/stage-ui/directives/track-button'
+
+createApp(App)
+  .use(trackButtonPlugin)
+  .mount('#app')
+```
+
+Buttons that represent a product-analysis click intent can then declare a
+typed event without wrapping their business handler:
+
+```vue
+<Button
+  v-track-button="{ name: 'update_check_clicked', channel: selectedChannel }"
+  @click="checkForUpdates()"
+/>
+```
+
+Keep async outcomes, confirmed state changes, impressions, and lifecycle events
+in their owning business flows instead of attaching them to the initial click.
+
 ## Histoire (UI storyboard)
 
 https://histoire.dev/
diff --git a/packages/stage-ui/package.json b/packages/stage-ui/package.json
index 6003117b1..22794556a 100644
--- a/packages/stage-ui/package.json
+++ b/packages/stage-ui/package.json
@@ -26,6 +26,7 @@
     "./composables": "./src/composables/index.ts",
     "./constants/*": "./src/constants/*.ts",
     "./constants": "./src/constants/index.ts",
+    "./directives/*": "./src/directives/*.ts",
     "./libs/inference/adapters/*": "./src/libs/inference/adapters/*.ts",
     "./libs/inference": "./src/libs/inference/index.ts",
     "./libs/*": "./src/libs/*.ts",
diff --git a/packages/stage-ui/src/composables/use-analytics.test.ts b/packages/stage-ui/src/composables/use-analytics.test.ts
index 4270eb5a6..ee5e0f6b0 100644
--- a/packages/stage-ui/src/composables/use-analytics.test.ts
+++ b/packages/stage-ui/src/composables/use-analytics.test.ts
@@ -994,6 +994,28 @@ describe('useAnalytics conversation product events', () => {
     })
   })
 
+  it('emits stable controls-island actions and flushes reload actions immediately', () => {
+    analyticsMocks.isStageTamagotchiMock.mockReturnValue(true)
+    const analytics = useAnalytics()
+
+    analytics.trackControlsIslandAction({ action: 'toggle_chat' })
+    analytics.trackControlsIslandAction({ action: 'refresh_window' })
+
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenNthCalledWith(1, 'controls_island_action', {
+      action: 'toggle_chat',
+      app_surface: 'electron',
+    })
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenNthCalledWith(
+      2,
+      'controls_island_action',
+      {
+        action: 'refresh_window',
+        app_surface: 'electron',
+      },
+      { send_instantly: true, transport: 'sendBeacon' },
+    )
+  })
+
   it('emits desktop differentiator events for spotlight, widgets, updater, MCP, and pairing', () => {
     analyticsMocks.isStageTamagotchiMock.mockReturnValue(true)
     const analytics = useAnalytics()
diff --git a/packages/stage-ui/src/composables/use-analytics.ts b/packages/stage-ui/src/composables/use-analytics.ts
index 1d7e6993e..0bb573085 100644
--- a/packages/stage-ui/src/composables/use-analytics.ts
+++ b/packages/stage-ui/src/composables/use-analytics.ts
@@ -1,3 +1,4 @@
+import type { ControlsIslandAction } from '../stores/analytics/button-events'
 import type { SpeechOutputStopReason } from '../stores/speech-output-control'
 
 import posthog from 'posthog-js'
@@ -7,6 +8,7 @@ import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 import { useSharedAnalyticsStore } from '../stores/analytics'
+import { captureTrackButtonEvent } from '../stores/analytics/button-events'
 import { ensurePosthogInitialized, isPosthogAvailableInBuild } from '../stores/analytics/posthog'
 import { getAnalyticsPrivacyPolicyUrl } from '../stores/analytics/privacy-policy'
 import { useSettingsAnalytics } from '../stores/settings/analytics'
@@ -39,6 +41,8 @@ export type ProductAnalyticsEntry = 'app_start' | 'onboarding' | 'settings' | 'c
 export type MessageInputMode = 'text' | 'voice'
 export type ConversationEventSource = 'new_session' | 'fork' | 'history' | 'share_button' | 'unknown'
 export type AiUsageSource = 'reported' | 'estimated' | 'unavailable'
+/** Stable, low-cardinality actions emitted by the Electron controls island. */
+export type { ControlsIslandAction } from '../stores/analytics/button-events'
 
 /**
  * Full stage vocabulary of the cross-surface `oauth_callback_failed` event.
@@ -1203,6 +1207,10 @@ export function useAnalytics() {
   // server management. Input text never leaves the device — events carry
   // counts and low-cardinality ids only.
 
+  function trackControlsIslandAction(properties: { action: ControlsIslandAction }) {
+    captureTrackButtonEvent({ name: 'controls_island_action', ...properties })
+  }
+
   function trackSpotlightUsed() {
     if (!canCapture())
       return
@@ -1216,9 +1224,7 @@ export function useAnalytics() {
   }
 
   function trackUpdateCheckClicked(properties: { channel: string }) {
-    if (!canCapture())
-      return
-    posthog.capture('update_check_clicked', properties)
+    captureTrackButtonEvent({ name: 'update_check_clicked', ...properties })
   }
 
   function trackUpdateDownloaded(properties: { channel: string, version?: string }) {
@@ -1229,21 +1235,15 @@ export function useAnalytics() {
 
   /** User confirmed restart-and-install; the app quits right after. */
   function trackUpdateInstallClicked(properties: { channel: string, version?: string }) {
-    if (!canCapture())
-      return
-    posthog.capture('update_install_clicked', properties, { send_instantly: true, transport: 'sendBeacon' })
+    captureTrackButtonEvent({ name: 'update_install_clicked', ...properties })
   }
 
   function trackMcpServerAdded() {
-    if (!canCapture())
-      return
-    posthog.capture('mcp_server_added')
+    captureTrackButtonEvent({ name: 'mcp_server_added' })
   }
 
   function trackMcpServerRemoved() {
-    if (!canCapture())
-      return
-    posthog.capture('mcp_server_removed')
+    captureTrackButtonEvent({ name: 'mcp_server_removed' })
   }
 
   function trackMcpConnectionTestRun(properties: { success: boolean }) {
@@ -1380,6 +1380,7 @@ export function useAnalytics() {
     trackDeviceChannelConnected,
 
     trackDataAction,
+    trackControlsIslandAction,
     trackSpotlightUsed,
     trackWidgetOpened,
     trackUpdateCheckClicked,
diff --git a/packages/stage-ui/src/directives/track-button.test.ts b/packages/stage-ui/src/directives/track-button.test.ts
new file mode 100644
index 000000000..f4aaf4504
--- /dev/null
+++ b/packages/stage-ui/src/directives/track-button.test.ts
@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+
+import type { ObjectDirective } from 'vue'
+
+import type { TrackButtonEvent } from './track-button'
+
+import { describe, expect, it, vi } from 'vitest'
+import { createApp, h, nextTick, ref, withDirectives } from 'vue'
+
+import { createTrackButtonDirective, trackButtonPlugin } from './track-button'
+
+describe('trackButtonPlugin', () => {
+  it('registers the directive at app level', () => {
+    const app = createApp({ render: () => h('div') })
+
+    app.use(trackButtonPlugin)
+
+    expect(app.directive('track-button')).toBeDefined()
+  })
+})
+
+describe('createTrackButtonDirective', () => {
+  it('captures the current descriptor before the button handler runs', async () => {
+    const calls: string[] = []
+    const event = ref<TrackButtonEvent>({
+      name: 'controls_island_action',
+      action: 'switch_to_dark_mode',
+    })
+    const capture = vi.fn((value: TrackButtonEvent) => calls.push(`track:${'action' in value ? value.action : value.name}`))
+    const directive = createTrackButtonDirective(capture)
+    const host = document.createElement('div')
+    const app = createApp({
+      render: () => withDirectives(
+        h('button', {
+          onClick: () => calls.push('handler'),
+        }),
+        [[directive, event.value]],
+      ),
+    })
+
+    app.mount(host)
+    const button = host.querySelector('button')!
+
+    button.click()
+    expect(calls).toEqual(['track:switch_to_dark_mode', 'handler'])
+
+    calls.length = 0
+    event.value = {
+      name: 'controls_island_action',
+      action: 'switch_to_light_mode',
+    }
+    await nextTick()
+    button.click()
+    expect(calls).toEqual(['track:switch_to_light_mode', 'handler'])
+
+    app.unmount()
+  })
+
+  it('removes its listener when the button is unmounted', () => {
+    const capture = vi.fn()
+    const directive: ObjectDirective<HTMLElement, TrackButtonEvent> = createTrackButtonDirective(capture)
+    const host = document.createElement('div')
+    const app = createApp({
+      render: () => withDirectives(
+        h('button'),
+        [[directive, { name: 'mcp_server_added' } satisfies TrackButtonEvent]],
+      ),
+    })
+
+    app.mount(host)
+    const button = host.querySelector('button')!
+    app.unmount()
+    button.click()
+
+    expect(capture).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/stage-ui/src/directives/track-button.ts b/packages/stage-ui/src/directives/track-button.ts
new file mode 100644
index 000000000..4fa1ae8b2
--- /dev/null
+++ b/packages/stage-ui/src/directives/track-button.ts
@@ -0,0 +1,65 @@
+import type { ObjectDirective, Plugin } from 'vue'
+
+import type { TrackButtonEvent } from '../stores/analytics/button-events'
+
+import { captureTrackButtonEvent } from '../stores/analytics/button-events'
+
+export type { ControlsIslandAction, TrackButtonEvent } from '../stores/analytics/button-events'
+
+/**
+ * Creates the DOM directive used by the app-level tracking plugin.
+ *
+ * The listener deliberately receives no DOM event. This keeps `MouseEvent`
+ * objects out of analytics callbacks and reads the latest binding when a
+ * reactive event descriptor changes.
+ */
+export function createTrackButtonDirective(capture: (event: TrackButtonEvent) => void): ObjectDirective<HTMLElement, TrackButtonEvent> {
+  const events = new WeakMap<HTMLElement, TrackButtonEvent>()
+  const listeners = new WeakMap<HTMLElement, EventListener>()
+
+  return {
+    mounted(element, binding) {
+      events.set(element, binding.value)
+
+      const listener = () => {
+        const event = events.get(element)
+        if (event)
+          capture(event)
+      }
+
+      listeners.set(element, listener)
+      element.addEventListener('click', listener, { capture: true })
+    },
+    updated(element, binding) {
+      events.set(element, binding.value)
+    },
+    beforeUnmount(element) {
+      const listener = listeners.get(element)
+      if (listener)
+        element.removeEventListener('click', listener, { capture: true })
+
+      events.delete(element)
+      listeners.delete(element)
+    },
+  }
+}
+
+const vTrackButton = createTrackButtonDirective(captureTrackButtonEvent)
+
+/**
+ * Registers `v-track-button` once for a Vue application.
+ *
+ * Templates provide typed event descriptors while the directive owns DOM
+ * listener lifecycle and analytics opt-in checks.
+ */
+export const trackButtonPlugin: Plugin = {
+  install(app) {
+    app.directive('track-button', vTrackButton)
+  },
+}
+
+declare module 'vue' {
+  interface GlobalDirectives {
+    vTrackButton: typeof vTrackButton
+  }
+}
diff --git a/packages/stage-ui/src/stores/analytics/button-events.ts b/packages/stage-ui/src/stores/analytics/button-events.ts
new file mode 100644
index 000000000..461b8de2c
--- /dev/null
+++ b/packages/stage-ui/src/stores/analytics/button-events.ts
@@ -0,0 +1,110 @@
+import posthog from 'posthog-js'
+
+import { isStageCapacitor, isStageTamagotchi } from '@proj-airi/stage-shared'
+
+import { useSettingsAnalytics } from '../settings/analytics'
+import { ensurePosthogInitialized, isPosthogAvailableInBuild } from './posthog'
+
+/** Stable, low-cardinality actions emitted by the Electron controls island. */
+export type ControlsIslandAction
+  = | 'expand_controls'
+    | 'collapse_controls'
+    | 'toggle_settings'
+    | 'toggle_profile_picker'
+    | 'toggle_chat'
+    | 'refresh_window'
+    | 'center_main_window'
+    | 'switch_to_light_mode'
+    | 'switch_to_dark_mode'
+    | 'pin_on_top'
+    | 'unpin_from_top'
+    | 'enable_fade_on_hover'
+    | 'disable_fade_on_hover'
+    | 'close_app'
+
+/**
+ * Explicit product events that may be emitted directly from a button click.
+ *
+ * Add an event here only when clicking the button is itself the fact being
+ * measured. Async outcomes and confirmed state changes should remain in their
+ * owning business flow.
+ */
+export type TrackButtonEvent
+  = | {
+    name: 'controls_island_action'
+    action: ControlsIslandAction
+  }
+  | {
+    name: 'update_check_clicked'
+    channel: string
+  }
+  | {
+    name: 'update_install_clicked'
+    channel: string
+    version?: string
+  }
+  | {
+    name: 'mcp_server_added'
+  }
+  | {
+    name: 'mcp_server_removed'
+  }
+
+function canCapture(): boolean {
+  const settingsAnalytics = useSettingsAnalytics()
+  return isPosthogAvailableInBuild()
+    && settingsAnalytics.analyticsEnabled
+    && ensurePosthogInitialized(true)
+}
+
+function appSurface(): 'web' | 'mobile' | 'electron' {
+  if (isStageTamagotchi())
+    return 'electron'
+
+  if (isStageCapacitor())
+    return 'mobile'
+
+  return 'web'
+}
+
+/**
+ * Emits a typed button event through the existing analytics opt-in boundary.
+ *
+ * This is shared with the global directive and imperative analytics facade so
+ * both retain one event schema and transport policy.
+ */
+export function captureTrackButtonEvent(event: TrackButtonEvent) {
+  if (!canCapture())
+    return
+
+  switch (event.name) {
+    case 'controls_island_action': {
+      const properties = {
+        action: event.action,
+        app_surface: appSurface(),
+      }
+      if (event.action === 'refresh_window' || event.action === 'close_app') {
+        posthog.capture(event.name, properties, { send_instantly: true, transport: 'sendBeacon' })
+        return
+      }
+
+      posthog.capture(event.name, properties)
+      return
+    }
+    case 'update_check_clicked':
+      posthog.capture(event.name, { channel: event.channel })
+      return
+    case 'update_install_clicked':
+      posthog.capture(
+        event.name,
+        { channel: event.channel, ...(event.version && { version: event.version }) },
+        { send_instantly: true, transport: 'sendBeacon' },
+      )
+      return
+    case 'mcp_server_added':
+      posthog.capture(event.name)
+      return
+    case 'mcp_server_removed':
+      posthog.capture(event.name)
+  }
+}
diff --git a/packages/stage-ui/src/stores/exports.contract.test.ts b/packages/stage-ui/src/stores/exports.contract.test.ts
index 28a533911..a7d112204 100644
--- a/packages/stage-ui/src/stores/exports.contract.test.ts
+++ b/packages/stage-ui/src/stores/exports.contract.test.ts
@@ -30,6 +30,7 @@ describe('stage-ui exports contract', () => {
       './composables/*',
       './constants',
       './constants/*',
+      './directives/*',
       './libs',
       './libs/*',
       './libs/inference',
@@ -63,6 +64,7 @@ describe('stage-ui exports contract', () => {
 
     expect(exportsMap['./stores']).toBe('./src/stores/index.ts')
     expect(exportsMap['./stores/*']).toBe('./src/stores/*.ts')
+    expect(exportsMap['./directives/*']).toBe('./src/directives/*.ts')
     expect(exportsMap['./services/*']).toBe('./src/services/*.ts')
     expect(exportsMap['./tools/mcp']).toBe('./src/tools/mcp.ts')
     expect(exportsMap['./types']).toBe('./src/types/index.ts')