From f2a5f2b128af5dc96e98ab45e6fc2144a24bf07d Mon Sep 17 00:00:00 2001
From: Ada Vale <104856138+AdaInTheLab@users.noreply.github.com>
Date: Fri, 29 May 2026 04:30:52 -0400
Subject: [PATCH 1/2] @ feat(vip): VIP tiers + first-login pack + recurring
 tier gifts (#233, #234)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a spawn-driven VipPerks feature covering two board items:

  #233 — first-time-login pack: the first time a player ever spawns, a
  configured VIP-gift template is delivered straight into their inventory
  (items dropped at feet, linked commands run). Once-ever, guarded by the
  new first_login_grants table.

  #234 — recurring tier gifts: players carry an admin-assigned VIP tier
  (new player_metadata.vip_tier, admin-editable tier names in settings).
  On spawn, each tier-gift rule for that tier is materialized once as a
  repeatable vip_gifts row; the existing /vip claim flow then drives the
  daily/weekly cadence. No tier ("pleb") = nothing.

Spawn-driven rather than timer-driven: a player must be online to claim or
receive items anyway, so doing the work on connect stays idempotent across
reconnects without a background sweep.

Backend:
- migration 012: player_metadata.vip_tier + first_login_grants
- VipPerksFeature + VipPerksSettings (persisted JSON, VoteRewards pattern)
- FirstLoginGrantRepository; VipGiftRepository.HasGiftByNameAndPeriod;
  PlayerMetadataRepository.SetTier/GetPlayerIdsByTier (SetTier writes only
  vip_tier so it never clobbers name colour / tag / notes)
- VipPerksController (settings + tiers); PlayerMetadataController tier route

Frontend:
- VIP tier dropdown in PlayerEditDialog
- VIP Perks settings tab (tiers, first-login pack, tier-gift rules)
- api/types/i18n (en translated; other locales English placeholders)

Tests: PlayerMetadata (tier set/clear, no-clobber both ways, by-tier query),
FirstLoginGrant (once-ever), VipGift (has-by-name-and-period). 10 new, green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@
---
 frontend/src/api/players.ts                   |   5 +
 frontend/src/api/vipperks.ts                  |  16 +
 frontend/src/components/PlayerEditDialog.vue  |  40 ++-
 frontend/src/i18n/locales/de.ts               |  30 ++
 frontend/src/i18n/locales/en.ts               |  32 ++
 frontend/src/i18n/locales/es.ts               |  30 ++
 frontend/src/i18n/locales/fr.ts               |  30 ++
 frontend/src/i18n/locales/ja.ts               |  30 ++
 frontend/src/i18n/locales/ko.ts               |  30 ++
 frontend/src/i18n/locales/zh-CN.ts            |  30 ++
 frontend/src/i18n/locales/zh-TW.ts            |  30 ++
 frontend/src/types/index.ts                   |  17 +
 frontend/src/views/SettingsView.vue           | 185 ++++++++++-
 .../FirstLoginGrantRepositoryTests.cs         |  54 ++++
 .../PlayerMetadataRepositoryTests.cs          | 102 ++++++
 .../Repositories/VipGiftRepositoryTests.cs    |  44 +++
 src/KitsuneCommand.Tests/TestDbFixture.cs     |  25 ++
 .../Config/Migrations/012_vip_tiers.sql       |  15 +
 .../Data/Entities/FirstLoginGrant.cs          |  13 +
 .../Data/Entities/PlayerMetadata.cs           |   7 +
 .../Repositories/FirstLoginGrantRepository.cs |  47 +++
 .../Repositories/PlayerMetadataRepository.cs  |  39 +++
 .../Data/Repositories/VipGiftRepository.cs    |  17 +
 .../Features/VipPerksFeature.cs               | 305 ++++++++++++++++++
 .../Features/VipPerksSettings.cs              |  70 ++++
 .../Controllers/PlayerMetadataController.cs   |  16 +
 .../Web/Controllers/VipPerksController.cs     |  77 +++++
 src/KitsuneCommand/Web/Models/PlayerModels.cs |   6 +
 28 files changed, 1338 insertions(+), 4 deletions(-)
 create mode 100644 frontend/src/api/vipperks.ts
 create mode 100644 src/KitsuneCommand.Tests/Repositories/FirstLoginGrantRepositoryTests.cs
 create mode 100644 src/KitsuneCommand.Tests/Repositories/PlayerMetadataRepositoryTests.cs
 create mode 100644 src/KitsuneCommand.Tests/Repositories/VipGiftRepositoryTests.cs
 create mode 100644 src/KitsuneCommand/Config/Migrations/012_vip_tiers.sql
 create mode 100644 src/KitsuneCommand/Data/Entities/FirstLoginGrant.cs
 create mode 100644 src/KitsuneCommand/Data/Repositories/FirstLoginGrantRepository.cs
 create mode 100644 src/KitsuneCommand/Features/VipPerksFeature.cs
 create mode 100644 src/KitsuneCommand/Features/VipPerksSettings.cs
 create mode 100644 src/KitsuneCommand/Web/Controllers/VipPerksController.cs

diff --git a/frontend/src/api/players.ts b/frontend/src/api/players.ts
index 6482edb..2c15ad1 100644
--- a/frontend/src/api/players.ts
+++ b/frontend/src/api/players.ts
@@ -76,3 +76,8 @@ export async function updatePlayerMetadata(
 export async function setAdminLevel(entityId: number, level: number): Promise<void> {
   await apiClient.post(`/api/players/${entityId}/admin-level`, { level })
 }
+
+export async function setPlayerTier(playerId: string, tier: string | null): Promise<PlayerMetadata> {
+  const response = await apiClient.put(`/api/players/metadata/${encodeURIComponent(playerId)}/tier`, { tier })
+  return response.data.data
+}
diff --git a/frontend/src/api/vipperks.ts b/frontend/src/api/vipperks.ts
new file mode 100644
index 0000000..69b056d
--- /dev/null
+++ b/frontend/src/api/vipperks.ts
@@ -0,0 +1,16 @@
+import apiClient from './client'
+import type { VipPerksSettings } from '@/types'
+
+export async function getVipPerksSettings(): Promise<VipPerksSettings> {
+  const response = await apiClient.get('/api/vipperks/settings')
+  return response.data.data
+}
+
+export async function updateVipPerksSettings(settings: VipPerksSettings): Promise<void> {
+  await apiClient.put('/api/vipperks/settings', settings)
+}
+
+export async function getVipTiers(): Promise<string[]> {
+  const response = await apiClient.get('/api/vipperks/tiers')
+  return response.data.data ?? []
+}
diff --git a/frontend/src/components/PlayerEditDialog.vue b/frontend/src/components/PlayerEditDialog.vue
index cefd611..572d3d7 100644
--- a/frontend/src/components/PlayerEditDialog.vue
+++ b/frontend/src/components/PlayerEditDialog.vue
@@ -1,8 +1,9 @@
 <script setup lang="ts">
-import { ref, watch } from 'vue'
+import { ref, watch, computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { usePlayersStore } from '@/stores/players'
-import { updatePlayerMetadata, setAdminLevel } from '@/api/players'
+import { updatePlayerMetadata, setAdminLevel, setPlayerTier } from '@/api/players'
+import { getVipTiers } from '@/api/vipperks'
 import { useToast } from 'primevue/usetoast'
 import Dialog from 'primevue/dialog'
 import Button from 'primevue/button'
@@ -29,6 +30,15 @@ const customTag = ref('')
 const adminLevel = ref(1000)
 const notes = ref('')
 
+// VIP tier — '' means no tier ("pleb"). The available tier names are defined
+// in the VipPerks feature settings; fetched fresh each time the dialog opens.
+const vipTier = ref('')
+const availableTiers = ref<string[]>([])
+const tierOptions = computed(() => [
+  { label: t('players.tierNone'), value: '' },
+  ...availableTiers.value.map((name) => ({ label: name, value: name })),
+])
+
 const tagPresets = [
   { label: 'VIP', value: 'VIP' },
   { label: 'Supporter', value: 'Supporter' },
@@ -43,13 +53,19 @@ const adminLevelOptions = [
 ]
 
 // Load current metadata when dialog opens
-watch(visible, (v) => {
+watch(visible, async (v) => {
   if (v && props.player) {
     const meta = playersStore.getMetadata(props.player.playerId)
     nameColor.value = meta?.nameColor ?? null
     customTag.value = meta?.customTag ?? ''
     adminLevel.value = props.player.adminLevel ?? 1000
     notes.value = meta?.notes ?? ''
+    vipTier.value = meta?.vipTier ?? ''
+    try {
+      availableTiers.value = await getVipTiers()
+    } catch {
+      availableTiers.value = []
+    }
   }
 })
 
@@ -65,6 +81,10 @@ async function save() {
       notes: notes.value || null,
     })
 
+    // Save VIP tier separately — it's a distinct column written on its own
+    // route so it never clobbers the name colour / tag / notes above.
+    await setPlayerTier(props.player.playerId, vipTier.value || null)
+
     // Change admin level if needed
     const currentIsAdmin = props.player.isAdmin
     const wantsAdmin = adminLevel.value < 1000
@@ -149,6 +169,19 @@ async function save() {
         />
       </div>
 
+      <!-- VIP Tier -->
+      <div class="field">
+        <label>{{ t('players.vipTier') }}</label>
+        <Select
+          v-model="vipTier"
+          :options="tierOptions"
+          optionLabel="label"
+          optionValue="value"
+          class="full-width"
+        />
+        <small class="field-hint">{{ t('players.vipTierHint') }}</small>
+      </div>
+
       <!-- Notes -->
       <div class="field">
         <label>{{ t('players.notes') }}</label>
@@ -172,6 +205,7 @@ async function save() {
 .edit-form { display: flex; flex-direction: column; gap: 1rem; }
 .field { display: flex; flex-direction: column; gap: 0.35rem; }
 .field label { font-size: 0.85rem; font-weight: 600; color: var(--kc-text-secondary); }
+.field-hint { font-size: 0.75rem; color: var(--kc-text-secondary); opacity: 0.8; }
 .color-row { display: flex; align-items: center; gap: 0.75rem; }
 .color-preview { font-weight: 600; font-size: 1rem; }
 .tag-row { display: flex; gap: 0.5rem; }
diff --git a/frontend/src/i18n/locales/de.ts b/frontend/src/i18n/locales/de.ts
index 216bdb2..dccb17f 100644
--- a/frontend/src/i18n/locales/de.ts
+++ b/frontend/src/i18n/locales/de.ts
@@ -182,6 +182,9 @@ const de = {
     nameColor: 'Namensfarbe',
     customTag: 'Eigener Tag',
     adminLevel: 'Admin-Stufe',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: 'Notizen',
     adminLevelAdmin: 'Admin',
     adminLevelModerator: 'Moderator',
@@ -840,6 +843,33 @@ const de = {
     voteRewardsSaved: 'Stimm-Belohnungs-Einstellungen gespeichert',
     failedToLoadVoteRewards: 'Stimm-Belohnungs-Einstellungen konnten nicht geladen werden',
     failedToLoadVoteGrants: 'Stimm-Vergaben-Protokoll konnte nicht geladen werden',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart
     serverRestartTitle: 'Geplanter Server-Neustart',
     serverRestartSubtitle: 'Planen Sie einen täglichen Neustart mit spielerfreundlichen In-Game-Warnungen.',
diff --git a/frontend/src/i18n/locales/en.ts b/frontend/src/i18n/locales/en.ts
index 1a5b251..d2d4e67 100644
--- a/frontend/src/i18n/locales/en.ts
+++ b/frontend/src/i18n/locales/en.ts
@@ -179,6 +179,9 @@ const en = {
     nameColor: 'Name Color',
     customTag: 'Custom Tag',
     adminLevel: 'Admin Level',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: 'Notes',
     adminLevelAdmin: 'Admin',
     adminLevelModerator: 'Moderator',
@@ -859,6 +862,35 @@ const en = {
     voteRewardsSaved: 'Vote-rewards settings saved',
     failedToLoadVoteRewards: 'Failed to load vote-rewards settings',
     failedToLoadVoteGrants: 'Failed to load vote-grants log',
+
+    // VIP Perks (board #233, #234)
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart
     serverRestartTitle: 'Graceful Server Restart',
     serverRestartSubtitle: 'Schedule a daily restart with player-friendly in-game warnings.',
diff --git a/frontend/src/i18n/locales/es.ts b/frontend/src/i18n/locales/es.ts
index 0adb532..490af83 100644
--- a/frontend/src/i18n/locales/es.ts
+++ b/frontend/src/i18n/locales/es.ts
@@ -182,6 +182,9 @@ const es = {
     nameColor: 'Color del nombre',
     customTag: 'Etiqueta personalizada',
     adminLevel: 'Nivel de admin',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: 'Notas',
     adminLevelAdmin: 'Admin',
     adminLevelModerator: 'Moderador',
@@ -840,6 +843,33 @@ const es = {
     voteRewardsSaved: 'Ajustes de recompensas de voto guardados',
     failedToLoadVoteRewards: 'No se pudieron cargar los ajustes de recompensas de voto',
     failedToLoadVoteGrants: 'No se pudo cargar el registro de otorgamientos de voto',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart
     serverRestartTitle: 'Reinicio planificado del servidor',
     serverRestartSubtitle: 'Programe un reinicio diario con avisos en el juego amigables para los jugadores.',
diff --git a/frontend/src/i18n/locales/fr.ts b/frontend/src/i18n/locales/fr.ts
index b7782ea..3a10c56 100644
--- a/frontend/src/i18n/locales/fr.ts
+++ b/frontend/src/i18n/locales/fr.ts
@@ -182,6 +182,9 @@ const fr = {
     nameColor: 'Couleur du nom',
     customTag: 'Tag personnalisé',
     adminLevel: 'Niveau admin',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: 'Notes',
     adminLevelAdmin: 'Admin',
     adminLevelModerator: 'Modérateur',
@@ -840,6 +843,33 @@ const fr = {
     voteRewardsSaved: 'Paramètres de récompenses de vote enregistrés',
     failedToLoadVoteRewards: 'Impossible de charger les paramètres de récompenses de vote',
     failedToLoadVoteGrants: 'Impossible de charger le journal des attributions de vote',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart
     serverRestartTitle: 'Redémarrage planifié du serveur',
     serverRestartSubtitle: 'Planifiez un redémarrage quotidien avec des avertissements en jeu adaptés aux joueurs.',
diff --git a/frontend/src/i18n/locales/ja.ts b/frontend/src/i18n/locales/ja.ts
index 4abcb67..7f5911d 100644
--- a/frontend/src/i18n/locales/ja.ts
+++ b/frontend/src/i18n/locales/ja.ts
@@ -183,6 +183,9 @@ const ja: Messages = {
     nameColor: '名前の色',
     customTag: 'カスタムタグ',
     adminLevel: '管理者レベル',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: 'メモ',
     adminLevelAdmin: '管理者',
     adminLevelModerator: 'モデレーター',
@@ -864,6 +867,33 @@ const ja: Messages = {
     voteRewardsSaved: 'Vote-rewards settings saved',
     failedToLoadVoteRewards: 'Failed to load vote-rewards settings',
     failedToLoadVoteGrants: 'Failed to load vote-grants log',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart (English placeholders — translations TBD)
     serverRestartTitle: 'Graceful Server Restart',
     serverRestartSubtitle: 'Schedule a daily restart with player-friendly in-game warnings.',
diff --git a/frontend/src/i18n/locales/ko.ts b/frontend/src/i18n/locales/ko.ts
index 9b94339..b597715 100644
--- a/frontend/src/i18n/locales/ko.ts
+++ b/frontend/src/i18n/locales/ko.ts
@@ -183,6 +183,9 @@ const ko: Messages = {
     nameColor: '이름 색상',
     customTag: '커스텀 태그',
     adminLevel: '관리자 레벨',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: '메모',
     adminLevelAdmin: '관리자',
     adminLevelModerator: '중재자',
@@ -864,6 +867,33 @@ const ko: Messages = {
     voteRewardsSaved: 'Vote-rewards settings saved',
     failedToLoadVoteRewards: 'Failed to load vote-rewards settings',
     failedToLoadVoteGrants: 'Failed to load vote-grants log',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart (English placeholders — translations TBD)
     serverRestartTitle: 'Graceful Server Restart',
     serverRestartSubtitle: 'Schedule a daily restart with player-friendly in-game warnings.',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index 6aaabef..ccf476b 100644
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -183,6 +183,9 @@ const zhCN: Messages = {
     nameColor: '名称颜色',
     customTag: '自定义标签',
     adminLevel: '管理员等级',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: '备注',
     adminLevelAdmin: '管理员',
     adminLevelModerator: '版主',
@@ -864,6 +867,33 @@ const zhCN: Messages = {
     voteRewardsSaved: 'Vote-rewards settings saved',
     failedToLoadVoteRewards: 'Failed to load vote-rewards settings',
     failedToLoadVoteGrants: 'Failed to load vote-grants log',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart (English placeholders — translations TBD)
     serverRestartTitle: 'Graceful Server Restart',
     serverRestartSubtitle: 'Schedule a daily restart with player-friendly in-game warnings.',
diff --git a/frontend/src/i18n/locales/zh-TW.ts b/frontend/src/i18n/locales/zh-TW.ts
index 909eb08..06953f0 100644
--- a/frontend/src/i18n/locales/zh-TW.ts
+++ b/frontend/src/i18n/locales/zh-TW.ts
@@ -183,6 +183,9 @@ const zhTW: Messages = {
     nameColor: '名稱顏色',
     customTag: '自訂標籤',
     adminLevel: '管理員等級',
+    vipTier: 'VIP Tier',
+    vipTierHint: 'Tier gifts are assigned automatically when the player connects. "None" = no tier (pleb).',
+    tierNone: 'None (pleb)',
     notes: '備註',
     adminLevelAdmin: '管理員',
     adminLevelModerator: '版主',
@@ -864,6 +867,33 @@ const zhTW: Messages = {
     voteRewardsSaved: 'Vote-rewards settings saved',
     failedToLoadVoteRewards: 'Failed to load vote-rewards settings',
     failedToLoadVoteGrants: 'Failed to load vote-grants log',
+    vipPerks: 'VIP Perks',
+    vipPerksTitle: 'VIP Perks',
+    vipPerksSubtitle: 'First-login starter pack and recurring tier gifts.',
+    vipPerksMasterToggle: 'Enable VIP perks',
+    vipPerksMasterToggleHint: 'Master switch. When off, neither the first-login pack nor tier gifts are granted.',
+    vipPerksSaved: 'VIP perks settings saved',
+    failedToLoadVipPerks: 'Failed to load VIP perks settings',
+    vipPerksTiersHeader: 'VIP Tiers',
+    vipPerksTiersHint: 'Define tier names here, then assign a player their tier from the player editor.',
+    vipPerksTierNamePlaceholder: 'e.g. VIP',
+    vipPerksAddTier: 'Add Tier',
+    vipPerksFirstLoginHeader: 'First-Login Pack',
+    vipPerksFirstLoginHint: 'Delivered straight to the inventory the first time a player ever connects. One-shot.',
+    vipPerksFirstLoginEnable: 'Enable first-login pack',
+    vipPerksTemplateName: 'VIP gift template name',
+    vipPerksTemplateNameHint: 'Name of a VIP gift template (created under player ID "_template_" in VIP Gifts).',
+    vipPerksFirstLoginMessage: 'Welcome message (optional)',
+    vipPerksFirstLoginMessageHint: 'Private message sent on first login. Token: {playerToken}.',
+    vipPerksTierGiftsHeader: 'Recurring Tier Gifts',
+    vipPerksTierGiftsHint: 'Assign each tier a recurring gift. Players claim it in-game with /vip on the chosen cadence.',
+    vipPerksRuleTier: 'Tier',
+    vipPerksRuleTierPlaceholder: 'Select tier',
+    vipPerksRulePeriod: 'Period',
+    vipPerksAddTierGift: 'Add Tier Gift',
+    vipPerksPeriodDaily: 'Daily',
+    vipPerksPeriodWeekly: 'Weekly',
+    vipPerksPeriodMonthly: 'Monthly',
     // Server Restart (English placeholders — translations TBD)
     serverRestartTitle: 'Graceful Server Restart',
     serverRestartSubtitle: 'Schedule a daily restart with player-friendly in-game warnings.',
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index acce5e7..15c8ba4 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -513,5 +513,22 @@ export interface PlayerMetadata {
   nameColor: string | null
   customTag: string | null
   notes: string | null
+  vipTier: string | null
   updatedAt: string
 }
+
+// ─── VIP Perks (board #233, #234) ────────────────────
+export interface TierGiftRule {
+  tier: string
+  templateName: string
+  period: string // 'daily' | 'weekly' | 'monthly'
+}
+
+export interface VipPerksSettings {
+  enabled: boolean
+  tiers: string[]
+  firstLoginPackEnabled: boolean
+  firstLoginTemplateName: string
+  firstLoginMessage: string
+  tierGifts: TierGiftRule[]
+}
diff --git a/frontend/src/views/SettingsView.vue b/frontend/src/views/SettingsView.vue
index 71e2de9..d1bc001 100644
--- a/frontend/src/views/SettingsView.vue
+++ b/frontend/src/views/SettingsView.vue
@@ -11,12 +11,13 @@ import {
 } from '@/api/settings'
 import { getVoteSettings, updateVoteSettings } from '@/api/bloodmoonvote'
 import { getVoteRewardsSettings, updateVoteRewardsSettings, getVoteGrants } from '@/api/voterewards'
+import { getVipPerksSettings, updateVipPerksSettings } from '@/api/vipperks'
 import { getRestartSettings, updateRestartSettings, triggerRestartNow } from '@/api/restart'
 import { getTicketSettings, updateTicketSettings } from '@/api/tickets'
 import { getDiscordSettings, updateDiscordSettings, getDiscordStatus, testDiscordConnection } from '@/api/discord'
 import { restartServer } from '@/api/serverControl'
 import type { UserResponse, CreateUserRequest } from '@/api/users'
-import type { ChatCommandSettings, PointsSettings, TeleportSettings, StoreSettings, BloodMoonVoteSettings, TicketSettings, DiscordSettings, DiscordStatus, VoteRewardsSettings, VoteGrant, GracefulRestartSettings } from '@/types'
+import type { ChatCommandSettings, PointsSettings, TeleportSettings, StoreSettings, BloodMoonVoteSettings, TicketSettings, DiscordSettings, DiscordStatus, VoteRewardsSettings, VoteGrant, GracefulRestartSettings, VipPerksSettings } from '@/types'
 import { VOTE_REWARD_TYPE } from '@/types'
 import { usePermissions } from '@/composables/usePermissions'
 import { useToast } from 'primevue/usetoast'
@@ -717,6 +718,76 @@ async function refreshDiscordStatus() {
   } catch { /* ignore */ }
 }
 
+// ---- VIP Perks Tab (board #233, #234) ----
+//
+// Backed by VipPerksController (REST) + VipPerksFeature (spawn-driven grants).
+// Tier names are free-form and admin-editable; the first-login pack and the
+// recurring tier gifts both reference VIP-gift templates by name.
+const vipPerksSettings = ref<VipPerksSettings>({
+  enabled: false,
+  tiers: [],
+  firstLoginPackEnabled: false,
+  firstLoginTemplateName: '',
+  firstLoginMessage: '',
+  tierGifts: [],
+})
+const loadingVipPerks = ref(false)
+const savingVipPerks = ref(false)
+
+const vipPeriodOptions = [
+  { label: t('settings.vipPerksPeriodDaily'), value: 'daily' },
+  { label: t('settings.vipPerksPeriodWeekly'), value: 'weekly' },
+  { label: t('settings.vipPerksPeriodMonthly'), value: 'monthly' },
+]
+
+// Literal placeholder kept as a const so vue-i18n doesn't try to interpolate {player}.
+const vipFirstLoginPlaceholder = "Welcome, {player}! Enjoy your starter pack."
+
+async function fetchVipPerksSettings() {
+  loadingVipPerks.value = true
+  try {
+    vipPerksSettings.value = await getVipPerksSettings()
+    // Defensive: server may omit empty collections.
+    vipPerksSettings.value.tiers ??= []
+    vipPerksSettings.value.tierGifts ??= []
+  } catch {
+    toast.add({ severity: 'error', summary: t('common.error'), detail: t('settings.failedToLoadVipPerks'), life: 3000 })
+  } finally {
+    loadingVipPerks.value = false
+  }
+}
+
+function addVipTier() {
+  vipPerksSettings.value.tiers.push('')
+}
+function removeVipTier(idx: number) {
+  vipPerksSettings.value.tiers.splice(idx, 1)
+}
+function addTierGift() {
+  vipPerksSettings.value.tierGifts.push({ tier: '', templateName: '', period: 'weekly' })
+}
+function removeTierGift(idx: number) {
+  vipPerksSettings.value.tierGifts.splice(idx, 1)
+}
+
+async function handleSaveVipPerks() {
+  savingVipPerks.value = true
+  try {
+    // Drop blank tier names so they don't pollute the dropdown / rules.
+    vipPerksSettings.value.tiers = vipPerksSettings.value.tiers
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0)
+    await updateVipPerksSettings(vipPerksSettings.value)
+    toast.add({ severity: 'success', summary: t('common.success'), detail: t('settings.vipPerksSaved'), life: 3000 })
+    await fetchVipPerksSettings()
+  } catch (err: any) {
+    const detail = err.response?.data?.message || t('settings.failedToSaveSettings')
+    toast.add({ severity: 'error', summary: t('common.error'), detail, life: 3000 })
+  } finally {
+    savingVipPerks.value = false
+  }
+}
+
 onMounted(() => {
   if (isAdmin.value) {
     fetchUsers()
@@ -729,6 +800,7 @@ onMounted(() => {
     fetchDiscordSettings()
     fetchVoteRewardsSettings()
     fetchVoteGrants()
+    fetchVipPerksSettings()
     fetchRestartSettings()
   }
 })
@@ -750,6 +822,7 @@ onMounted(() => {
         <Tab v-if="isAdmin" value="7">{{ t('settings.tickets') }}</Tab>
         <Tab v-if="isAdmin" value="8">Discord</Tab>
         <Tab v-if="isAdmin" value="9">{{ t('settings.voteRewards') }}</Tab>
+        <Tab v-if="isAdmin" value="11">{{ t('settings.vipPerks') }}</Tab>
         <Tab v-if="isAdmin" value="10">{{ t('settings.serverRestart') }}</Tab>
       </TabList>
       <TabPanels>
@@ -1522,6 +1595,97 @@ onMounted(() => {
           </div>
         </TabPanel>
 
+        <!-- VIP Perks Tab (board #233, #234) -->
+        <TabPanel v-if="isAdmin" value="11">
+          <div v-if="loadingVipPerks" class="loading-state">{{ t('settings.loadingSettings') }}</div>
+          <div v-else class="settings-section">
+            <Card class="settings-card">
+              <template #title>{{ t('settings.vipPerksTitle') }}</template>
+              <template #subtitle>{{ t('settings.vipPerksSubtitle') }}</template>
+              <template #content>
+                <div class="toggle-row">
+                  <label>{{ t('settings.vipPerksMasterToggle') }}</label>
+                  <ToggleSwitch v-model="vipPerksSettings.enabled" />
+                </div>
+                <small class="settings-hint">{{ t('settings.vipPerksMasterToggleHint') }}</small>
+              </template>
+            </Card>
+
+            <!-- Tiers -->
+            <Card class="settings-card">
+              <template #title>{{ t('settings.vipPerksTiersHeader') }}</template>
+              <template #subtitle>{{ t('settings.vipPerksTiersHint') }}</template>
+              <template #content>
+                <div v-for="(_, idx) in vipPerksSettings.tiers" :key="`tier-${idx}`" class="vip-row">
+                  <InputText v-model="vipPerksSettings.tiers[idx]" class="form-input" :placeholder="t('settings.vipPerksTierNamePlaceholder')" />
+                  <Button icon="pi pi-trash" text severity="danger" @click="removeVipTier(idx)" />
+                </div>
+                <Button :label="t('settings.vipPerksAddTier')" icon="pi pi-plus" text severity="secondary" @click="addVipTier" />
+              </template>
+            </Card>
+
+            <!-- First-login pack (#233) -->
+            <Card class="settings-card">
+              <template #title>{{ t('settings.vipPerksFirstLoginHeader') }}</template>
+              <template #subtitle>{{ t('settings.vipPerksFirstLoginHint') }}</template>
+              <template #content>
+                <div class="toggle-row">
+                  <label>{{ t('settings.vipPerksFirstLoginEnable') }}</label>
+                  <ToggleSwitch v-model="vipPerksSettings.firstLoginPackEnabled" />
+                </div>
+                <div class="form-group">
+                  <label class="form-label">{{ t('settings.vipPerksTemplateName') }}</label>
+                  <InputText v-model="vipPerksSettings.firstLoginTemplateName" class="form-input" />
+                  <small class="settings-hint">{{ t('settings.vipPerksTemplateNameHint') }}</small>
+                </div>
+                <div class="form-group">
+                  <label class="form-label">{{ t('settings.vipPerksFirstLoginMessage') }}</label>
+                  <InputText v-model="vipPerksSettings.firstLoginMessage" class="form-input" :placeholder="vipFirstLoginPlaceholder" />
+                  <small class="settings-hint">{{ t('settings.vipPerksFirstLoginMessageHint', { playerToken: '{player}' }) }}</small>
+                </div>
+              </template>
+            </Card>
+
+            <!-- Recurring tier gifts (#234) -->
+            <Card class="settings-card">
+              <template #title>{{ t('settings.vipPerksTierGiftsHeader') }}</template>
+              <template #subtitle>{{ t('settings.vipPerksTierGiftsHint') }}</template>
+              <template #content>
+                <div v-for="(rule, idx) in vipPerksSettings.tierGifts" :key="`rule-${idx}`" class="vip-gift-rule">
+                  <div class="form-group">
+                    <label class="form-label">{{ t('settings.vipPerksRuleTier') }}</label>
+                    <Select
+                      v-model="rule.tier"
+                      :options="vipPerksSettings.tiers"
+                      :placeholder="t('settings.vipPerksRuleTierPlaceholder')"
+                      class="form-input"
+                    />
+                  </div>
+                  <div class="form-group">
+                    <label class="form-label">{{ t('settings.vipPerksTemplateName') }}</label>
+                    <InputText v-model="rule.templateName" class="form-input" />
+                  </div>
+                  <div class="form-group">
+                    <label class="form-label">{{ t('settings.vipPerksRulePeriod') }}</label>
+                    <Select v-model="rule.period" :options="vipPeriodOptions" optionLabel="label" optionValue="value" class="form-input" />
+                  </div>
+                  <Button icon="pi pi-trash" text severity="danger" @click="removeTierGift(idx)" />
+                </div>
+                <Button :label="t('settings.vipPerksAddTierGift')" icon="pi pi-plus" text severity="secondary" @click="addTierGift" />
+              </template>
+            </Card>
+
+            <Button
+              :label="t('settings.saveSettings')"
+              icon="pi pi-save"
+              @click="handleSaveVipPerks"
+              :loading="savingVipPerks"
+              severity="info"
+              class="save-btn"
+            />
+          </div>
+        </TabPanel>
+
         <!-- Server Restart Tab -->
         <TabPanel v-if="isAdmin" value="10">
           <div v-if="loadingRestart" class="loading-state">{{ t('settings.loadingSettings') }}</div>
@@ -1826,6 +1990,25 @@ onMounted(() => {
   margin-top: 0.25rem;
 }
 
+/* VIP Perks rows */
+.vip-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+.vip-row .form-input { flex: 1; }
+.vip-gift-rule {
+  display: flex;
+  align-items: flex-end;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  padding-bottom: 0.75rem;
+  margin-bottom: 0.75rem;
+  border-bottom: 1px solid var(--kc-border, rgba(255,255,255,0.08));
+}
+.vip-gift-rule .form-group { flex: 1; min-width: 140px; margin-bottom: 0; }
+
 .loading-state {
   padding: 2rem;
   text-align: center;
diff --git a/src/KitsuneCommand.Tests/Repositories/FirstLoginGrantRepositoryTests.cs b/src/KitsuneCommand.Tests/Repositories/FirstLoginGrantRepositoryTests.cs
new file mode 100644
index 0000000..82670f4
--- /dev/null
+++ b/src/KitsuneCommand.Tests/Repositories/FirstLoginGrantRepositoryTests.cs
@@ -0,0 +1,54 @@
+using NUnit.Framework;
+using KitsuneCommand.Data;
+using KitsuneCommand.Data.Repositories;
+
+namespace KitsuneCommand.Tests.Repositories
+{
+    [TestFixture]
+    public class FirstLoginGrantRepositoryTests
+    {
+        private string _dbPath;
+        private DbConnectionFactory _db;
+        private FirstLoginGrantRepository _repo;
+
+        [OneTimeSetUp]
+        public void OneTimeSetUp()
+        {
+            _dbPath = TestDbFixture.CreateTempDatabase();
+            _db = TestDbFixture.CreateFactory(_dbPath);
+            _repo = new FirstLoginGrantRepository(_db);
+        }
+
+        [OneTimeTearDown]
+        public void OneTimeTearDown() => TestDbFixture.Cleanup(_dbPath);
+
+        [SetUp]
+        public void SetUp()
+        {
+            using var conn = _db.CreateConnection();
+            Dapper.SqlMapper.Execute(conn, "DELETE FROM first_login_grants");
+        }
+
+        [Test]
+        public void TryClaim_ReturnsTrue_OnFirstCall_ThenFalse()
+        {
+            Assert.That(_repo.TryClaim("p1", "Player One"), Is.True, "first claim should succeed");
+            Assert.That(_repo.TryClaim("p1", "Player One"), Is.False, "second claim must be a no-op");
+        }
+
+        [Test]
+        public void HasGrant_ReflectsClaimState()
+        {
+            Assert.That(_repo.HasGrant("p1"), Is.False);
+            _repo.TryClaim("p1", "Player One");
+            Assert.That(_repo.HasGrant("p1"), Is.True);
+        }
+
+        [Test]
+        public void TryClaim_IsPerPlayer()
+        {
+            Assert.That(_repo.TryClaim("p1", "One"), Is.True);
+            Assert.That(_repo.TryClaim("p2", "Two"), Is.True, "a different player still gets their first pack");
+        }
+    }
+}
diff --git a/src/KitsuneCommand.Tests/Repositories/PlayerMetadataRepositoryTests.cs b/src/KitsuneCommand.Tests/Repositories/PlayerMetadataRepositoryTests.cs
new file mode 100644
index 0000000..32b3ab7
--- /dev/null
+++ b/src/KitsuneCommand.Tests/Repositories/PlayerMetadataRepositoryTests.cs
@@ -0,0 +1,102 @@
+using System.Linq;
+using NUnit.Framework;
+using KitsuneCommand.Data;
+using KitsuneCommand.Data.Entities;
+using KitsuneCommand.Data.Repositories;
+
+namespace KitsuneCommand.Tests.Repositories
+{
+    [TestFixture]
+    public class PlayerMetadataRepositoryTests
+    {
+        private string _dbPath;
+        private DbConnectionFactory _db;
+        private PlayerMetadataRepository _repo;
+
+        [OneTimeSetUp]
+        public void OneTimeSetUp()
+        {
+            _dbPath = TestDbFixture.CreateTempDatabase();
+            _db = TestDbFixture.CreateFactory(_dbPath);
+            _repo = new PlayerMetadataRepository(_db);
+        }
+
+        [OneTimeTearDown]
+        public void OneTimeTearDown() => TestDbFixture.Cleanup(_dbPath);
+
+        [SetUp]
+        public void SetUp()
+        {
+            using var conn = _db.CreateConnection();
+            Dapper.SqlMapper.Execute(conn, "DELETE FROM player_metadata");
+        }
+
+        [Test]
+        public void SetTier_CreatesRow_WhenPlayerHasNoMetadata()
+        {
+            _repo.SetTier("p1", "VIP");
+
+            var meta = _repo.GetByPlayerId("p1");
+            Assert.That(meta, Is.Not.Null);
+            Assert.That(meta.VipTier, Is.EqualTo("VIP"));
+        }
+
+        [Test]
+        public void SetTier_DoesNotClobberNameColorOrNotes()
+        {
+            _repo.Upsert(new PlayerMetadata { PlayerId = "p1", NameColor = "FF0000", CustomTag = "tag", Notes = "hi" });
+
+            _repo.SetTier("p1", "VIP+");
+
+            var meta = _repo.GetByPlayerId("p1");
+            Assert.That(meta.VipTier, Is.EqualTo("VIP+"));
+            Assert.That(meta.NameColor, Is.EqualTo("FF0000"), "name colour must survive a tier change");
+            Assert.That(meta.CustomTag, Is.EqualTo("tag"));
+            Assert.That(meta.Notes, Is.EqualTo("hi"));
+        }
+
+        [Test]
+        public void Upsert_DoesNotClobberTier()
+        {
+            _repo.SetTier("p1", "VIP");
+
+            // A subsequent metadata edit (e.g. setting a name colour) must not wipe the tier.
+            _repo.Upsert(new PlayerMetadata { PlayerId = "p1", NameColor = "00FF00" });
+
+            var meta = _repo.GetByPlayerId("p1");
+            Assert.That(meta.VipTier, Is.EqualTo("VIP"), "tier must survive an Upsert");
+            Assert.That(meta.NameColor, Is.EqualTo("00FF00"));
+        }
+
+        [Test]
+        public void SetTier_ClearsTier_WhenGivenNullOrEmpty()
+        {
+            _repo.SetTier("p1", "VIP");
+            _repo.SetTier("p1", "");
+
+            var meta = _repo.GetByPlayerId("p1");
+            Assert.That(meta.VipTier, Is.Null, "empty string normalizes to NULL (pleb)");
+        }
+
+        [Test]
+        public void GetPlayerIdsByTier_ReturnsOnlyMatchingPlayers()
+        {
+            _repo.SetTier("a", "VIP");
+            _repo.SetTier("b", "VIP");
+            _repo.SetTier("c", "VIP+");
+            _repo.SetTier("d", "");
+
+            var vip = _repo.GetPlayerIdsByTier("VIP").OrderBy(x => x).ToList();
+            Assert.That(vip, Is.EqualTo(new[] { "a", "b" }));
+            Assert.That(_repo.GetPlayerIdsByTier("VIP+"), Is.EquivalentTo(new[] { "c" }));
+        }
+
+        [Test]
+        public void GetPlayerIdsByTier_ReturnsEmpty_ForNullOrEmptyTier()
+        {
+            _repo.SetTier("a", "VIP");
+            Assert.That(_repo.GetPlayerIdsByTier(""), Is.Empty);
+            Assert.That(_repo.GetPlayerIdsByTier(null), Is.Empty);
+        }
+    }
+}
diff --git a/src/KitsuneCommand.Tests/Repositories/VipGiftRepositoryTests.cs b/src/KitsuneCommand.Tests/Repositories/VipGiftRepositoryTests.cs
new file mode 100644
index 0000000..531530b
--- /dev/null
+++ b/src/KitsuneCommand.Tests/Repositories/VipGiftRepositoryTests.cs
@@ -0,0 +1,44 @@
+using NUnit.Framework;
+using KitsuneCommand.Data;
+using KitsuneCommand.Data.Entities;
+using KitsuneCommand.Data.Repositories;
+
+namespace KitsuneCommand.Tests.Repositories
+{
+    [TestFixture]
+    public class VipGiftRepositoryTests
+    {
+        private string _dbPath;
+        private DbConnectionFactory _db;
+        private VipGiftRepository _repo;
+
+        [OneTimeSetUp]
+        public void OneTimeSetUp()
+        {
+            _dbPath = TestDbFixture.CreateTempDatabase();
+            _db = TestDbFixture.CreateFactory(_dbPath);
+            _repo = new VipGiftRepository(_db);
+        }
+
+        [OneTimeTearDown]
+        public void OneTimeTearDown() => TestDbFixture.Cleanup(_dbPath);
+
+        [SetUp]
+        public void SetUp()
+        {
+            using var conn = _db.CreateConnection();
+            Dapper.SqlMapper.Execute(conn, "DELETE FROM vip_gifts");
+        }
+
+        [Test]
+        public void HasGiftByNameAndPeriod_MatchesOnAllThreeKeys()
+        {
+            _repo.Insert(new VipGift { PlayerId = "p1", PlayerName = "One", Name = "Weekly Crate", ClaimPeriod = "weekly" });
+
+            Assert.That(_repo.HasGiftByNameAndPeriod("p1", "Weekly Crate", "weekly"), Is.True);
+            Assert.That(_repo.HasGiftByNameAndPeriod("p1", "Weekly Crate", "daily"), Is.False, "different period");
+            Assert.That(_repo.HasGiftByNameAndPeriod("p1", "Other", "weekly"), Is.False, "different name");
+            Assert.That(_repo.HasGiftByNameAndPeriod("p2", "Weekly Crate", "weekly"), Is.False, "different player");
+        }
+    }
+}
diff --git a/src/KitsuneCommand.Tests/TestDbFixture.cs b/src/KitsuneCommand.Tests/TestDbFixture.cs
index 07d9a82..eb4a925 100644
--- a/src/KitsuneCommand.Tests/TestDbFixture.cs
+++ b/src/KitsuneCommand.Tests/TestDbFixture.cs
@@ -62,6 +62,12 @@ public static void InitializeSchema(string databasePath)
             // continuous-migration property; it just needs the
             // tables the test under exercise references).
             connection.Execute(Schema011);
+
+            // 008_player_metadata.sql + 012_vip_tiers.sql — player_metadata with the
+            // vip_tier column folded in, plus the first_login_grants table. The
+            // production path is two migrations (008 creates the table, 012 ALTERs
+            // in vip_tier); the test DB just creates the final shape directly.
+            connection.Execute(Schema012);
         }
 
         /// <summary>
@@ -351,6 +357,25 @@ CREATE TABLE IF NOT EXISTS pack_relay_settings (
     publisher_slug        TEXT,
     updated_at            TEXT NOT NULL DEFAULT (datetime('now'))
 );
+";
+
+        // Mirrors Config/Migrations/008_player_metadata.sql + 012_vip_tiers.sql.
+        // Update all three when the schema changes.
+        private const string Schema012 = @"
+CREATE TABLE IF NOT EXISTS player_metadata (
+    player_id TEXT PRIMARY KEY,
+    name_color TEXT,
+    custom_tag TEXT,
+    notes TEXT,
+    vip_tier TEXT,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS first_login_grants (
+    player_id  TEXT PRIMARY KEY NOT NULL,
+    player_name TEXT,
+    granted_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
 ";
 
         #endregion
diff --git a/src/KitsuneCommand/Config/Migrations/012_vip_tiers.sql b/src/KitsuneCommand/Config/Migrations/012_vip_tiers.sql
new file mode 100644
index 0000000..df8f5cb
--- /dev/null
+++ b/src/KitsuneCommand/Config/Migrations/012_vip_tiers.sql
@@ -0,0 +1,15 @@
+-- VIP tiers + first-login pack support (board #233, #234)
+
+-- Classify players into admin-defined VIP tiers. null / empty = no tier ("pleb").
+-- Tier names themselves live in the VipPerks feature settings, not here, so admins
+-- can add/rename tiers without a migration. This column just records assignment.
+ALTER TABLE player_metadata ADD COLUMN vip_tier TEXT;
+
+-- One row per player, ever. Presence = the first-time-login item pack has already
+-- been delivered to this player. PRIMARY KEY gives us the once-ever idempotency
+-- guard for free (INSERT OR IGNORE returns 0 rows on a repeat spawn).
+CREATE TABLE IF NOT EXISTS first_login_grants (
+    player_id  TEXT PRIMARY KEY NOT NULL,
+    player_name TEXT,
+    granted_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
diff --git a/src/KitsuneCommand/Data/Entities/FirstLoginGrant.cs b/src/KitsuneCommand/Data/Entities/FirstLoginGrant.cs
new file mode 100644
index 0000000..97944a4
--- /dev/null
+++ b/src/KitsuneCommand/Data/Entities/FirstLoginGrant.cs
@@ -0,0 +1,13 @@
+namespace KitsuneCommand.Data.Entities
+{
+    /// <summary>
+    /// Maps to the first_login_grants table. One row per player, ever — its
+    /// presence means the first-time-login item pack has already been delivered.
+    /// </summary>
+    public class FirstLoginGrant
+    {
+        public string PlayerId { get; set; }
+        public string PlayerName { get; set; }
+        public string GrantedAt { get; set; }
+    }
+}
diff --git a/src/KitsuneCommand/Data/Entities/PlayerMetadata.cs b/src/KitsuneCommand/Data/Entities/PlayerMetadata.cs
index c54b13b..568f0a4 100644
--- a/src/KitsuneCommand/Data/Entities/PlayerMetadata.cs
+++ b/src/KitsuneCommand/Data/Entities/PlayerMetadata.cs
@@ -6,6 +6,13 @@ public class PlayerMetadata
         public string NameColor { get; set; }
         public string CustomTag { get; set; }
         public string Notes { get; set; }
+
+        /// <summary>
+        /// VIP tier name (matches an entry in VipPerksSettings.Tiers).
+        /// null / empty = no tier ("pleb"). Set via SetTier, never via Upsert
+        /// — see PlayerMetadataRepository for why the two paths are kept apart.
+        /// </summary>
+        public string VipTier { get; set; }
         public string UpdatedAt { get; set; }
     }
 }
diff --git a/src/KitsuneCommand/Data/Repositories/FirstLoginGrantRepository.cs b/src/KitsuneCommand/Data/Repositories/FirstLoginGrantRepository.cs
new file mode 100644
index 0000000..aeaf762
--- /dev/null
+++ b/src/KitsuneCommand/Data/Repositories/FirstLoginGrantRepository.cs
@@ -0,0 +1,47 @@
+using Dapper;
+using KitsuneCommand.Data.Entities;
+
+namespace KitsuneCommand.Data.Repositories
+{
+    public interface IFirstLoginGrantRepository
+    {
+        /// <summary>
+        /// Records that a player has received their first-login pack. Returns true
+        /// if this is the first time (row inserted), false if a row already existed
+        /// (INSERT OR IGNORE matched the primary key). This is the once-ever
+        /// idempotency primitive: claim the slot FIRST, deliver the pack second,
+        /// so two rapid spawn events can't double-deliver.
+        /// </summary>
+        bool TryClaim(string playerId, string playerName);
+
+        /// <summary>Has this player already received their first-login pack?</summary>
+        bool HasGrant(string playerId);
+    }
+
+    public class FirstLoginGrantRepository : IFirstLoginGrantRepository
+    {
+        private readonly DbConnectionFactory _db;
+
+        public FirstLoginGrantRepository(DbConnectionFactory db)
+        {
+            _db = db;
+        }
+
+        public bool TryClaim(string playerId, string playerName)
+        {
+            using var conn = _db.CreateConnection();
+            var rows = conn.Execute(
+                "INSERT OR IGNORE INTO first_login_grants (player_id, player_name) VALUES (@PlayerId, @PlayerName)",
+                new { PlayerId = playerId, PlayerName = playerName });
+            return rows > 0;
+        }
+
+        public bool HasGrant(string playerId)
+        {
+            using var conn = _db.CreateConnection();
+            return conn.ExecuteScalar<int>(
+                "SELECT COUNT(*) FROM first_login_grants WHERE player_id = @PlayerId",
+                new { PlayerId = playerId }) > 0;
+        }
+    }
+}
diff --git a/src/KitsuneCommand/Data/Repositories/PlayerMetadataRepository.cs b/src/KitsuneCommand/Data/Repositories/PlayerMetadataRepository.cs
index 3378e54..658654d 100644
--- a/src/KitsuneCommand/Data/Repositories/PlayerMetadataRepository.cs
+++ b/src/KitsuneCommand/Data/Repositories/PlayerMetadataRepository.cs
@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using System.Linq;
 using Dapper;
 using KitsuneCommand.Data.Entities;
 
@@ -10,6 +11,20 @@ public interface IPlayerMetadataRepository
         IEnumerable<PlayerMetadata> GetAll();
         void Upsert(PlayerMetadata metadata);
         void Delete(string playerId);
+
+        /// <summary>
+        /// Sets (or clears, when tier is null/empty) a player's VIP tier without
+        /// touching name_color / custom_tag / notes. Kept separate from Upsert
+        /// because Upsert overwrites those three columns wholesale — routing a
+        /// tier change through it would wipe a player's chat colour. Creates the
+        /// metadata row if it doesn't exist yet.
+        /// </summary>
+        void SetTier(string playerId, string tier);
+
+        /// <summary>
+        /// Returns the player_ids currently assigned to the given tier.
+        /// </summary>
+        IEnumerable<string> GetPlayerIdsByTier(string tier);
     }
 
     public class PlayerMetadataRepository : IPlayerMetadataRepository
@@ -55,5 +70,29 @@ public void Delete(string playerId)
             conn.Execute("DELETE FROM player_metadata WHERE player_id = @PlayerId",
                 new { PlayerId = playerId });
         }
+
+        public void SetTier(string playerId, string tier)
+        {
+            // Normalize empty string to null so "pleb" is consistently NULL in the
+            // column — keeps GetPlayerIdsByTier filtering and the IS NULL semantics simple.
+            var normalized = string.IsNullOrWhiteSpace(tier) ? null : tier.Trim();
+            using var conn = _db.CreateConnection();
+            conn.Execute(@"
+                INSERT INTO player_metadata (player_id, vip_tier, updated_at)
+                VALUES (@PlayerId, @Tier, datetime('now'))
+                ON CONFLICT(player_id) DO UPDATE SET
+                    vip_tier = @Tier,
+                    updated_at = datetime('now')",
+                new { PlayerId = playerId, Tier = normalized });
+        }
+
+        public IEnumerable<string> GetPlayerIdsByTier(string tier)
+        {
+            if (string.IsNullOrWhiteSpace(tier)) return new List<string>();
+            using var conn = _db.CreateConnection();
+            return conn.Query<string>(
+                "SELECT player_id FROM player_metadata WHERE vip_tier = @Tier",
+                new { Tier = tier.Trim() }).ToList();
+        }
     }
 }
diff --git a/src/KitsuneCommand/Data/Repositories/VipGiftRepository.cs b/src/KitsuneCommand/Data/Repositories/VipGiftRepository.cs
index 4fe1ee0..3ff90a4 100644
--- a/src/KitsuneCommand/Data/Repositories/VipGiftRepository.cs
+++ b/src/KitsuneCommand/Data/Repositories/VipGiftRepository.cs
@@ -30,6 +30,14 @@ public interface IVipGiftRepository
 
         // Claiming
         void MarkAsClaimed(int giftId);
+
+        /// <summary>
+        /// True if the player already has a gift with this name + claim period.
+        /// Used by the VipPerks feature to avoid assigning the same recurring tier
+        /// gift twice — the repeatable row is created once, then the existing
+        /// GetPendingForPlayer / MarkAsClaimed cadence drives re-claims.
+        /// </summary>
+        bool HasGiftByNameAndPeriod(string playerId, string name, string claimPeriod);
     }
 
     /// <summary>
@@ -218,5 +226,14 @@ UPDATE vip_gifts
                 WHERE id = @Id",
                 new { Id = giftId });
         }
+
+        public bool HasGiftByNameAndPeriod(string playerId, string name, string claimPeriod)
+        {
+            using var conn = _db.CreateConnection();
+            return conn.ExecuteScalar<int>(@"
+                SELECT COUNT(*) FROM vip_gifts
+                WHERE player_id = @PlayerId AND name = @Name AND claim_period = @ClaimPeriod",
+                new { PlayerId = playerId, Name = name, ClaimPeriod = claimPeriod }) > 0;
+        }
     }
 }
diff --git a/src/KitsuneCommand/Features/VipPerksFeature.cs b/src/KitsuneCommand/Features/VipPerksFeature.cs
new file mode 100644
index 0000000..958aa58
--- /dev/null
+++ b/src/KitsuneCommand/Features/VipPerksFeature.cs
@@ -0,0 +1,305 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using KitsuneCommand.Abstractions.Models;
+using KitsuneCommand.Configuration;
+using KitsuneCommand.Core;
+using KitsuneCommand.Data.Entities;
+using KitsuneCommand.Data.Repositories;
+using Newtonsoft.Json;
+
+namespace KitsuneCommand.Features
+{
+    /// <summary>
+    /// VIP perks driven off player spawn (board #233, #234):
+    ///
+    ///   • #233 — first-time-login pack. The first time a player ever spawns, the
+    ///     configured VIP-gift template is delivered straight into their inventory
+    ///     (items dropped at their feet, linked commands run). One-shot, guarded by
+    ///     the first_login_grants table so it never repeats.
+    ///
+    ///   • #234 — recurring tier gifts. Players carry an admin-assigned VIP tier
+    ///     (player_metadata.vip_tier). On spawn, each tier-gift rule for that tier
+    ///     is materialized once as a repeatable vip_gifts row; the existing /vip
+    ///     claim flow then drives the daily/weekly cadence. "Plebs" (no tier) get
+    ///     nothing.
+    ///
+    /// Spawn-driven rather than timer-driven: a player must be online to claim a
+    /// gift or receive items anyway, so doing the work on connect avoids a
+    /// background sweep entirely while staying idempotent across reconnects.
+    /// </summary>
+    public class VipPerksFeature : FeatureBase<VipPerksSettings>
+    {
+        private readonly ISettingsRepository _settingsRepo;
+        private readonly IVipGiftRepository _vipGiftRepo;
+        private readonly IFirstLoginGrantRepository _firstLoginRepo;
+        private readonly IPlayerMetadataRepository _metadataRepo;
+        private readonly LivePlayerManager _playerManager;
+        private const string SettingsKey = "VipPerks";
+
+        // Items are dropped via the game API which needs the player entity to be
+        // fully spawned. PlayerSpawnedEvent can fire a beat before the EntityPlayer
+        // is ready, so we wait briefly before delivering the first-login pack.
+        private const int FirstLoginDeliveryDelayMs = 3000;
+
+        private static readonly HashSet<string> ValidPeriods =
+            new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "daily", "weekly", "monthly" };
+
+        public VipPerksFeature(
+            ModEventBus eventBus,
+            ConfigManager config,
+            ISettingsRepository settingsRepo,
+            IVipGiftRepository vipGiftRepo,
+            IFirstLoginGrantRepository firstLoginRepo,
+            IPlayerMetadataRepository metadataRepo,
+            LivePlayerManager playerManager)
+            : base(eventBus, config)
+        {
+            _settingsRepo = settingsRepo;
+            _vipGiftRepo = vipGiftRepo;
+            _firstLoginRepo = firstLoginRepo;
+            _metadataRepo = metadataRepo;
+            _playerManager = playerManager;
+        }
+
+        protected override void OnEnable()
+        {
+            LoadPersistedSettings();
+            EventBus.Subscribe<PlayerSpawnedEvent>(OnPlayerSpawned);
+            Log.Out($"[KitsuneCommand] VipPerks feature enabled. Master={Settings.Enabled}, "
+                  + $"tiers={Settings.Tiers.Count}, firstLoginPack={Settings.FirstLoginPackEnabled}, "
+                  + $"tierGiftRules={Settings.TierGifts.Count}.");
+        }
+
+        protected override void OnDisable()
+        {
+            EventBus.Unsubscribe<PlayerSpawnedEvent>(OnPlayerSpawned);
+            Log.Out("[KitsuneCommand] VipPerks feature disabled.");
+        }
+
+        /// <summary>
+        /// Replaces settings in memory and persists them. No restart needed —
+        /// the next spawn sees the new config.
+        /// </summary>
+        public void UpdateSettings(VipPerksSettings newSettings)
+        {
+            Settings = newSettings ?? new VipPerksSettings();
+            if (Settings.Tiers == null) Settings.Tiers = new List<string>();
+            if (Settings.TierGifts == null) Settings.TierGifts = new List<TierGiftRule>();
+
+            try
+            {
+                _settingsRepo.Set(SettingsKey, JsonConvert.SerializeObject(Settings));
+                Log.Out($"[KitsuneCommand] VipPerks settings updated. Master={Settings.Enabled}.");
+            }
+            catch (Exception ex)
+            {
+                Log.Warning($"[KitsuneCommand] Failed to persist VipPerks settings: {ex.Message}");
+            }
+        }
+
+        // ─── Spawn handler ────────────────────────────────────────────────
+
+        private void OnPlayerSpawned(PlayerSpawnedEvent e)
+        {
+            if (!Settings.Enabled) return;
+            if (string.IsNullOrEmpty(e.PlayerId)) return;
+
+            // Only act on "joined the server" spawns. Death and teleport republish
+            // PlayerSpawnedEvent too, and we don't want to re-run perk logic every
+            // time a VIP dies. NewGame / LoadedGame / Enter / JoinMultiplayer all
+            // represent a (re)connect; Died and Teleport do not.
+            // Fully qualified: the game also defines a global `RespawnType`, so the
+            // bare name would bind to the wrong enum and fail to compare with the
+            // Abstractions one carried on the event.
+            if (e.RespawnType == Abstractions.Models.RespawnType.Died
+             || e.RespawnType == Abstractions.Models.RespawnType.Teleport)
+                return;
+
+            // Offload off the publishing thread. DB work runs immediately; item
+            // delivery waits for the entity to settle. Errors are swallowed per
+            // concern so one failure can't starve the other.
+            _ = Task.Run(async () =>
+            {
+                try { AssignTierGifts(e.PlayerId, e.PlayerName); }
+                catch (Exception ex) { Log.Warning($"[KitsuneCommand] VipPerks: tier-gift assign failed for {e.PlayerName}: {ex.Message}"); }
+
+                try { await MaybeDeliverFirstLoginPackAsync(e).ConfigureAwait(false); }
+                catch (Exception ex) { Log.Warning($"[KitsuneCommand] VipPerks: first-login pack failed for {e.PlayerName}: {ex.Message}"); }
+            });
+        }
+
+        // ─── #233 first-login pack ────────────────────────────────────────
+
+        private async Task MaybeDeliverFirstLoginPackAsync(PlayerSpawnedEvent e)
+        {
+            if (!Settings.FirstLoginPackEnabled) return;
+            if (string.IsNullOrWhiteSpace(Settings.FirstLoginTemplateName)) return;
+
+            // Cheap pre-check so we don't resolve the template for the 99% case of
+            // a returning player who already has their pack.
+            if (_firstLoginRepo.HasGrant(e.PlayerId)) return;
+
+            // Resolve the template BEFORE claiming the once-ever slot. If the admin
+            // typo'd the template name, we must not burn the player's first-login
+            // grant on an empty delivery — leave it unclaimed so a fixed config
+            // still works on their next connect.
+            var template = _vipGiftRepo.GetTemplateByName(Settings.FirstLoginTemplateName);
+            if (template == null)
+            {
+                Log.Warning($"[KitsuneCommand] VipPerks: first-login template '{Settings.FirstLoginTemplateName}' "
+                          + $"not found (player_id = '{VipGiftSentinels.TemplatePlayerId}'). Skipping pack for {e.PlayerName}.");
+                return;
+            }
+
+            // Atomically claim the slot. If another spawn beat us to it, stop.
+            if (!_firstLoginRepo.TryClaim(e.PlayerId, e.PlayerName))
+                return;
+
+            var items = _vipGiftRepo.GetItemsForGift(template.Id).ToList();
+            var commands = _vipGiftRepo.GetCommandsForGift(template.Id).ToList();
+
+            // Give the entity a moment to finish spawning before dropping items.
+            await Task.Delay(FirstLoginDeliveryDelayMs).ConfigureAwait(false);
+
+            foreach (var item in items)
+            {
+                try
+                {
+                    var result = _playerManager.GiveItemToPlayer(e.EntityId, item.ItemName, item.Count, item.Quality);
+                    Log.Out($"[KitsuneCommand] VipPerks: first-login item {item.ItemName} x{item.Count} → {e.PlayerName}: {result?.Message}");
+                }
+                catch (Exception ex)
+                {
+                    Log.Warning($"[KitsuneCommand] VipPerks: failed to give {item.ItemName} to {e.PlayerName}: {ex.Message}");
+                }
+            }
+
+            foreach (var cmdDef in commands)
+            {
+                var cmd = cmdDef.Command
+                    .Replace("{entityId}", e.EntityId.ToString())
+                    .Replace("{playerId}", e.PlayerId)
+                    .Replace("{playerName}", e.PlayerName ?? "");
+                ExecuteConsoleCommand(cmd);
+            }
+
+            if (!string.IsNullOrWhiteSpace(Settings.FirstLoginMessage) && !string.IsNullOrEmpty(e.PlayerName))
+            {
+                var msg = Settings.FirstLoginMessage.Replace("{player}", e.PlayerName).Replace("\"", "'");
+                ExecuteConsoleCommand($"pm \"{e.PlayerName}\" \"{msg}\"");
+            }
+
+            Log.Out($"[KitsuneCommand] VipPerks: delivered first-login pack '{template.Name}' "
+                  + $"({items.Count} item(s), {commands.Count} command(s)) to {e.PlayerName}.");
+        }
+
+        // ─── #234 recurring tier gifts ────────────────────────────────────
+
+        private void AssignTierGifts(string playerId, string playerName)
+        {
+            if (Settings.TierGifts == null || Settings.TierGifts.Count == 0) return;
+
+            var tier = _metadataRepo.GetByPlayerId(playerId)?.VipTier;
+            if (string.IsNullOrWhiteSpace(tier)) return; // pleb — no tier gifts
+
+            // Ignore a tier that's no longer in the configured list (e.g. admin
+            // renamed/removed it but a stale assignment lingers on a player).
+            if (!Settings.Tiers.Any(t => string.Equals(t, tier, StringComparison.OrdinalIgnoreCase)))
+                return;
+
+            foreach (var rule in Settings.TierGifts)
+            {
+                if (!string.Equals(rule.Tier, tier, StringComparison.OrdinalIgnoreCase)) continue;
+                if (string.IsNullOrWhiteSpace(rule.TemplateName)) continue;
+
+                var period = (rule.Period ?? "").Trim().ToLowerInvariant();
+                if (!ValidPeriods.Contains(period))
+                {
+                    Log.Warning($"[KitsuneCommand] VipPerks: tier '{rule.Tier}' rule has invalid period '{rule.Period}' — skipping.");
+                    continue;
+                }
+
+                var template = _vipGiftRepo.GetTemplateByName(rule.TemplateName);
+                if (template == null)
+                {
+                    Log.Warning($"[KitsuneCommand] VipPerks: tier-gift template '{rule.TemplateName}' not found — skipping.");
+                    continue;
+                }
+
+                // Assign once. After that, GetPendingForPlayer + /vip drive re-claims.
+                if (_vipGiftRepo.HasGiftByNameAndPeriod(playerId, template.Name, period))
+                    continue;
+
+                CloneTemplateForPlayer(template, playerId, playerName, period);
+                Log.Out($"[KitsuneCommand] VipPerks: assigned {period} gift '{template.Name}' to {playerName} (tier {tier}).");
+            }
+        }
+
+        /// <summary>
+        /// Clones a template's items + commands into a new repeatable vip_gifts row
+        /// for the player. Mirrors VoteRewardsFeature's VIP-gift clone path.
+        /// </summary>
+        private void CloneTemplateForPlayer(VipGift template, string playerId, string playerName, string period)
+        {
+            var templateItems = _vipGiftRepo.GetItemsForGift(template.Id).Select(i => i.Id).ToList();
+            var templateCommands = _vipGiftRepo.GetCommandsForGift(template.Id).Select(c => c.Id).ToList();
+
+            var gift = new VipGift
+            {
+                PlayerId = playerId,
+                PlayerName = playerName,
+                Name = template.Name,
+                Description = string.IsNullOrWhiteSpace(template.Description)
+                    ? $"VIP {period} gift"
+                    : template.Description,
+                ClaimPeriod = period
+            };
+            var newId = _vipGiftRepo.Insert(gift);
+            _vipGiftRepo.SetGiftItems(newId, templateItems);
+            _vipGiftRepo.SetGiftCommands(newId, templateCommands);
+        }
+
+        // ─── Bootstrap / helpers ──────────────────────────────────────────
+
+        private void LoadPersistedSettings()
+        {
+            try
+            {
+                var json = _settingsRepo.Get(SettingsKey);
+                if (!string.IsNullOrEmpty(json))
+                {
+                    var loaded = JsonConvert.DeserializeObject<VipPerksSettings>(json);
+                    if (loaded != null) Settings = loaded;
+                }
+            }
+            catch (Exception ex)
+            {
+                Log.Warning($"[KitsuneCommand] Failed to load VipPerks settings, using defaults: {ex.Message}");
+            }
+
+            if (Settings.Tiers == null) Settings.Tiers = new List<string>();
+            if (Settings.TierGifts == null) Settings.TierGifts = new List<TierGiftRule>();
+        }
+
+        /// <summary>
+        /// Executes a console command on the main thread. Fire-and-forget from a
+        /// background thread; same marshaling pattern as VipGiftController / TaskScheduleFeature.
+        /// </summary>
+        private static void ExecuteConsoleCommand(string command)
+        {
+            if (string.IsNullOrWhiteSpace(command)) return;
+
+            var waitHandle = new ManualResetEventSlim(false);
+            ModEntry.MainThreadContext.Post(_ =>
+            {
+                try { SdtdConsole.Instance.ExecuteSync(command, null); }
+                catch (Exception ex) { Log.Warning($"[KitsuneCommand] VipPerks: command '{command}' failed: {ex.Message}"); }
+                finally { waitHandle.Set(); }
+            }, null);
+            waitHandle.Wait(TimeSpan.FromSeconds(10));
+        }
+    }
+}
diff --git a/src/KitsuneCommand/Features/VipPerksSettings.cs b/src/KitsuneCommand/Features/VipPerksSettings.cs
new file mode 100644
index 0000000..b411237
--- /dev/null
+++ b/src/KitsuneCommand/Features/VipPerksSettings.cs
@@ -0,0 +1,70 @@
+using System.Collections.Generic;
+
+namespace KitsuneCommand.Features
+{
+    /// <summary>
+    /// One recurring gift granted to a VIP tier. The feature clones the named
+    /// VIP-gift template (a vip_gifts row under the sentinel "_template_" player_id)
+    /// into a repeatable vip_gifts row for each player in <see cref="Tier"/>, then
+    /// the existing /vip claim flow handles the daily/weekly cadence.
+    /// </summary>
+    public class TierGiftRule
+    {
+        /// <summary>Tier name this rule applies to. Must match an entry in VipPerksSettings.Tiers.</summary>
+        public string Tier { get; set; } = "";
+
+        /// <summary>Name of the VIP-gift template (player_id = "_template_") to clone.</summary>
+        public string TemplateName { get; set; } = "";
+
+        /// <summary>Claim cadence for the cloned gift: "daily", "weekly", or "monthly".</summary>
+        public string Period { get; set; } = "weekly";
+    }
+
+    /// <summary>
+    /// Settings for the VipPerks feature — covers both board items:
+    ///   #233 a one-time pack auto-delivered on a player's first-ever spawn, and
+    ///   #234 recurring daily/weekly gifts gated by an admin-assigned VIP tier.
+    ///
+    /// Persisted as a JSON blob in the `settings` table under key "VipPerks",
+    /// same pattern as VoteRewardsSettings.
+    /// </summary>
+    public class VipPerksSettings
+    {
+        /// <summary>Master toggle. When off, neither the first-login pack nor tier gifts run.</summary>
+        public bool Enabled { get; set; } = false;
+
+        /// <summary>
+        /// Admin-defined tier names (e.g. ["VIP", "VIP+"]). A player whose
+        /// player_metadata.vip_tier is null / empty / not in this list is a "pleb"
+        /// and receives no tier gifts. Order is display-only.
+        /// </summary>
+        public List<string> Tiers { get; set; } = new List<string>();
+
+        // ─── #233 first-time-login pack ──────────────────────────────────
+
+        /// <summary>When true, a player's first-ever spawn auto-delivers FirstLoginTemplateName.</summary>
+        public bool FirstLoginPackEnabled { get; set; } = false;
+
+        /// <summary>
+        /// VIP-gift template (player_id = "_template_") whose items + commands are
+        /// delivered directly into the player's inventory on first spawn. Items are
+        /// dropped at the player's feet; linked commands run with {entityId}/{playerId}/{playerName}
+        /// substitution. Unlike normal VIP gifts there is no /vip claim step.
+        /// </summary>
+        public string FirstLoginTemplateName { get; set; } = "";
+
+        /// <summary>
+        /// Optional private message sent to the player when the pack lands.
+        /// Tokens: {player}. Empty = silent.
+        /// </summary>
+        public string FirstLoginMessage { get; set; } = "";
+
+        // ─── #234 recurring tier gifts ───────────────────────────────────
+
+        /// <summary>
+        /// Tier → recurring gift rules. Evaluated when a VIP player spawns; the
+        /// matching templates are assigned (once) as repeatable vip_gifts rows.
+        /// </summary>
+        public List<TierGiftRule> TierGifts { get; set; } = new List<TierGiftRule>();
+    }
+}
diff --git a/src/KitsuneCommand/Web/Controllers/PlayerMetadataController.cs b/src/KitsuneCommand/Web/Controllers/PlayerMetadataController.cs
index 81e9694..06a7d66 100644
--- a/src/KitsuneCommand/Web/Controllers/PlayerMetadataController.cs
+++ b/src/KitsuneCommand/Web/Controllers/PlayerMetadataController.cs
@@ -66,5 +66,21 @@ public IHttpActionResult UpdateMetadata(string playerId, [FromBody] UpdatePlayer
             _metadataRepo.Upsert(metadata);
             return Ok(ApiResponse.Ok(metadata));
         }
+
+        /// <summary>
+        /// Set (or clear) a player's VIP tier. Kept on its own route because it
+        /// writes only the vip_tier column — UpdateMetadata overwrites name colour
+        /// / tag / notes, so folding tier into that body would clobber them.
+        /// </summary>
+        [HttpPut]
+        [Route("{playerId}/tier")]
+        public IHttpActionResult SetTier(string playerId, [FromBody] SetVipTierRequest request)
+        {
+            if (request == null)
+                return BadRequest("Request body is required.");
+
+            _metadataRepo.SetTier(playerId, request.Tier);
+            return Ok(ApiResponse.Ok(_metadataRepo.GetByPlayerId(playerId)));
+        }
     }
 }
diff --git a/src/KitsuneCommand/Web/Controllers/VipPerksController.cs b/src/KitsuneCommand/Web/Controllers/VipPerksController.cs
new file mode 100644
index 0000000..08e5eaa
--- /dev/null
+++ b/src/KitsuneCommand/Web/Controllers/VipPerksController.cs
@@ -0,0 +1,77 @@
+using System.Linq;
+using System.Web.Http;
+using KitsuneCommand.Features;
+using KitsuneCommand.Web.Auth;
+using KitsuneCommand.Web.Models;
+
+namespace KitsuneCommand.Web.Controllers
+{
+    /// <summary>
+    /// REST surface for the VipPerks feature (board #233, #234).
+    ///
+    ///   GET    /api/vipperks/settings   — current config (admin)
+    ///   PUT    /api/vipperks/settings   — overwrite config (admin)
+    ///   GET    /api/vipperks/tiers      — just the tier-name list (admin)
+    ///
+    /// Mirrors VoteRewardsController: pull the feature instance from the
+    /// FeatureManager rather than DI-ing it directly.
+    /// </summary>
+    [Authorize]
+    [RoutePrefix("api/vipperks")]
+    public class VipPerksController : ApiController
+    {
+        private readonly FeatureManager _featureManager;
+
+        public VipPerksController(FeatureManager featureManager)
+        {
+            _featureManager = featureManager;
+        }
+
+        private VipPerksFeature GetFeature()
+        {
+            return _featureManager.GetAllFeatures()
+                .OfType<VipPerksFeature>()
+                .FirstOrDefault();
+        }
+
+        [HttpGet]
+        [Route("settings")]
+        [RoleAuthorize("admin")]
+        public IHttpActionResult GetSettings()
+        {
+            var feature = GetFeature();
+            if (feature == null)
+                return Ok(ApiResponse.Error(404, "VipPerks feature not available."));
+            return Ok(ApiResponse.Ok(feature.Settings));
+        }
+
+        [HttpPut]
+        [Route("settings")]
+        [RoleAuthorize("admin")]
+        public IHttpActionResult UpdateSettings([FromBody] VipPerksSettings model)
+        {
+            if (model == null)
+                return BadRequest("Request body is required.");
+
+            var feature = GetFeature();
+            if (feature == null)
+                return Ok(ApiResponse.Error(404, "VipPerks feature not available."));
+
+            feature.UpdateSettings(model);
+            return Ok(ApiResponse.Ok($"VIP perks: {(model.Enabled ? "enabled" : "disabled")}"));
+        }
+
+        /// <summary>
+        /// Lightweight list of configured tier names, for the player-edit tier
+        /// dropdown. Returns an empty list if the feature isn't available.
+        /// </summary>
+        [HttpGet]
+        [Route("tiers")]
+        [RoleAuthorize("admin")]
+        public IHttpActionResult GetTiers()
+        {
+            var feature = GetFeature();
+            return Ok(ApiResponse.Ok(feature?.Settings?.Tiers ?? new System.Collections.Generic.List<string>()));
+        }
+    }
+}
diff --git a/src/KitsuneCommand/Web/Models/PlayerModels.cs b/src/KitsuneCommand/Web/Models/PlayerModels.cs
index 116f931..4cc9bf0 100644
--- a/src/KitsuneCommand/Web/Models/PlayerModels.cs
+++ b/src/KitsuneCommand/Web/Models/PlayerModels.cs
@@ -66,6 +66,12 @@ public class SetAdminLevelRequest
         public int Level { get; set; }
     }
 
+    public class SetVipTierRequest
+    {
+        /// <summary>Tier name to assign. null / empty clears the tier ("pleb").</summary>
+        public string Tier { get; set; }
+    }
+
     public class GiveItemResult
     {
         public bool Success { get; set; }

From 2e6e02718cf73a05b544f6ee2ed2e986b6694d39 Mon Sep 17 00:00:00 2001
From: Ada Vale <104856138+AdaInTheLab@users.noreply.github.com>
Date: Fri, 29 May 2026 04:51:46 -0400
Subject: [PATCH 2/2] @ test(vip): frontend vitest coverage for VIP perks
 (#233, #234)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

codecov/patch flagged the frontend changes (coverage is frontend-only via
vitest). Adds:
- api/vipperks.test.ts — full coverage of the new API module
- players.test.ts — setPlayerTier (encoded id, null-clear)
- PlayerEditDialog.test.ts — tier load on open + save wires setPlayerTier
- SettingsViewVipPerks.test.ts — renders the VIP Perks panel and exercises
  fetch / add+remove tier / add+remove tier-gift / save handlers

+20 tests (89 total green). SettingsView.vue 0% -> 47.6%; the new VIP perks
panel + handlers are the covered portion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@
---
 frontend/src/__tests__/api/players.test.ts    |  14 ++
 frontend/src/__tests__/api/vipperks.test.ts   |  56 ++++++++
 .../components/PlayerEditDialog.test.ts       | 105 +++++++++++++++
 .../components/SettingsViewVipPerks.test.ts   | 122 ++++++++++++++++++
 4 files changed, 297 insertions(+)
 create mode 100644 frontend/src/__tests__/api/vipperks.test.ts
 create mode 100644 frontend/src/__tests__/components/PlayerEditDialog.test.ts
 create mode 100644 frontend/src/__tests__/components/SettingsViewVipPerks.test.ts

diff --git a/frontend/src/__tests__/api/players.test.ts b/frontend/src/__tests__/api/players.test.ts
index 48ee166..f5e9e27 100644
--- a/frontend/src/__tests__/api/players.test.ts
+++ b/frontend/src/__tests__/api/players.test.ts
@@ -22,6 +22,7 @@ import {
   giveItem,
   getAllPlayerMetadata,
   updatePlayerMetadata,
+  setPlayerTier,
 } from '@/api/players'
 
 describe('Players API', () => {
@@ -96,4 +97,17 @@ describe('Players API', () => {
     await updatePlayerMetadata('abc', { nameColor: '#00ff00' })
     expect(mockPut).toHaveBeenCalledWith('/api/players/metadata/abc', { nameColor: '#00ff00' })
   })
+
+  it('setPlayerTier calls PUT /api/players/metadata/{id}/tier with the tier', async () => {
+    mockPut.mockResolvedValue({ data: { data: { playerId: 'abc', vipTier: 'VIP' } } })
+    const result = await setPlayerTier('abc', 'VIP')
+    expect(mockPut).toHaveBeenCalledWith('/api/players/metadata/abc/tier', { tier: 'VIP' })
+    expect(result.vipTier).toBe('VIP')
+  })
+
+  it('setPlayerTier sends null to clear the tier and encodes the id', async () => {
+    mockPut.mockResolvedValue({ data: { data: { playerId: 'EOS_x/y', vipTier: null } } })
+    await setPlayerTier('EOS_x/y', null)
+    expect(mockPut).toHaveBeenCalledWith('/api/players/metadata/EOS_x%2Fy/tier', { tier: null })
+  })
 })
diff --git a/frontend/src/__tests__/api/vipperks.test.ts b/frontend/src/__tests__/api/vipperks.test.ts
new file mode 100644
index 0000000..447bccd
--- /dev/null
+++ b/frontend/src/__tests__/api/vipperks.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const mockGet = vi.fn()
+const mockPut = vi.fn()
+
+vi.mock('@/api/client', () => ({
+  default: {
+    get: (...args: any[]) => mockGet(...args),
+    put: (...args: any[]) => mockPut(...args),
+  },
+}))
+
+import { getVipPerksSettings, updateVipPerksSettings, getVipTiers } from '@/api/vipperks'
+import type { VipPerksSettings } from '@/types'
+
+const sampleSettings: VipPerksSettings = {
+  enabled: true,
+  tiers: ['VIP', 'VIP+'],
+  firstLoginPackEnabled: true,
+  firstLoginTemplateName: 'starter',
+  firstLoginMessage: 'hi {player}',
+  tierGifts: [{ tier: 'VIP', templateName: 'weekly-crate', period: 'weekly' }],
+}
+
+describe('VipPerks API', () => {
+  beforeEach(() => {
+    mockGet.mockReset()
+    mockPut.mockReset()
+  })
+
+  it('getVipPerksSettings calls GET /api/vipperks/settings', async () => {
+    mockGet.mockResolvedValue({ data: { data: sampleSettings } })
+    const result = await getVipPerksSettings()
+    expect(mockGet).toHaveBeenCalledWith('/api/vipperks/settings')
+    expect(result).toEqual(sampleSettings)
+  })
+
+  it('updateVipPerksSettings calls PUT /api/vipperks/settings with the body', async () => {
+    mockPut.mockResolvedValue({ data: {} })
+    await updateVipPerksSettings(sampleSettings)
+    expect(mockPut).toHaveBeenCalledWith('/api/vipperks/settings', sampleSettings)
+  })
+
+  it('getVipTiers returns the tier list', async () => {
+    mockGet.mockResolvedValue({ data: { data: ['VIP', 'VIP+'] } })
+    const result = await getVipTiers()
+    expect(mockGet).toHaveBeenCalledWith('/api/vipperks/tiers')
+    expect(result).toEqual(['VIP', 'VIP+'])
+  })
+
+  it('getVipTiers returns [] when data is null', async () => {
+    mockGet.mockResolvedValue({ data: { data: null } })
+    const result = await getVipTiers()
+    expect(result).toEqual([])
+  })
+})
diff --git a/frontend/src/__tests__/components/PlayerEditDialog.test.ts b/frontend/src/__tests__/components/PlayerEditDialog.test.ts
new file mode 100644
index 0000000..93cce95
--- /dev/null
+++ b/frontend/src/__tests__/components/PlayerEditDialog.test.ts
@@ -0,0 +1,105 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia } from 'pinia'
+import PrimeVue from 'primevue/config'
+import PlayerEditDialog from '@/components/PlayerEditDialog.vue'
+
+const mockUpdatePlayerMetadata = vi.fn()
+const mockSetAdminLevel = vi.fn()
+const mockSetPlayerTier = vi.fn()
+const mockGetVipTiers = vi.fn()
+
+vi.mock('@/api/players', () => ({
+  updatePlayerMetadata: (...a: any[]) => mockUpdatePlayerMetadata(...a),
+  setAdminLevel: (...a: any[]) => mockSetAdminLevel(...a),
+  setPlayerTier: (...a: any[]) => mockSetPlayerTier(...a),
+}))
+vi.mock('@/api/vipperks', () => ({
+  getVipTiers: () => mockGetVipTiers(),
+}))
+
+// Store returns no cached metadata by default → tier starts as '' (pleb).
+const mockGetMetadata = vi.fn(() => undefined)
+vi.mock('@/stores/players', () => ({
+  usePlayersStore: () => ({ getMetadata: mockGetMetadata }),
+}))
+
+const player = {
+  playerId: 'EOS_abc',
+  playerName: 'Alice',
+  entityId: 42,
+  isAdmin: false,
+  adminLevel: 1000,
+}
+
+function mountDialog() {
+  return mount(PlayerEditDialog, {
+    props: { player, visible: false },
+    global: {
+      plugins: [createPinia(), [PrimeVue, { theme: 'none' }]],
+      stubs: {
+        Dialog: { template: '<div><slot /><slot name="footer" /></div>', props: ['visible', 'header', 'modal'] },
+        Button: { template: '<button @click="$emit(\'click\')">{{ label }}</button>', props: ['label', 'icon', 'loading', 'text', 'severity', 'size'] },
+        InputText: { template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />', props: ['modelValue', 'placeholder'] },
+        Textarea: { template: '<textarea />', props: ['modelValue', 'rows', 'placeholder'] },
+        ColorPicker: { template: '<input />', props: ['modelValue'] },
+        Select: {
+          template: '<select :data-testid="$attrs[\'data-testid\']" @change="$emit(\'update:modelValue\', $event.target.value)"><slot /></select>',
+          props: ['modelValue', 'options', 'optionLabel', 'optionValue'],
+        },
+      },
+    },
+  })
+}
+
+describe('PlayerEditDialog — VIP tier', () => {
+  beforeEach(() => {
+    mockUpdatePlayerMetadata.mockReset().mockResolvedValue({})
+    mockSetAdminLevel.mockReset().mockResolvedValue(undefined)
+    mockSetPlayerTier.mockReset().mockResolvedValue({})
+    mockGetVipTiers.mockReset().mockResolvedValue(['VIP', 'VIP+'])
+    mockGetMetadata.mockReset().mockReturnValue(undefined)
+  })
+
+  it('loads available tiers when opened', async () => {
+    const wrapper = mountDialog()
+    await wrapper.setProps({ visible: true })
+    await flushPromises()
+    expect(mockGetVipTiers).toHaveBeenCalled()
+  })
+
+  it('seeds the tier from cached metadata', async () => {
+    mockGetMetadata.mockReturnValue({ playerId: 'EOS_abc', vipTier: 'VIP+' })
+    const wrapper = mountDialog()
+    await wrapper.setProps({ visible: true })
+    await flushPromises()
+    // Save and assert the seeded tier is sent back.
+    await wrapper.find('button:last-of-type').trigger('click')
+    await flushPromises()
+    expect(mockSetPlayerTier).toHaveBeenCalledWith('EOS_abc', 'VIP+')
+  })
+
+  it('saves metadata and tier together, without touching admin level for a normal player', async () => {
+    const wrapper = mountDialog()
+    await wrapper.setProps({ visible: true })
+    await flushPromises()
+
+    await wrapper.find('button:last-of-type').trigger('click')
+    await flushPromises()
+
+    expect(mockUpdatePlayerMetadata).toHaveBeenCalledWith('EOS_abc', expect.any(Object))
+    expect(mockSetPlayerTier).toHaveBeenCalledWith('EOS_abc', null) // '' → null
+    expect(mockSetAdminLevel).not.toHaveBeenCalled()
+  })
+
+  it('falls back to no tiers when the lookup fails', async () => {
+    mockGetVipTiers.mockRejectedValue(new Error('no backend'))
+    const wrapper = mountDialog()
+    await wrapper.setProps({ visible: true })
+    await flushPromises()
+    // Still saves cleanly with an empty tier.
+    await wrapper.find('button:last-of-type').trigger('click')
+    await flushPromises()
+    expect(mockSetPlayerTier).toHaveBeenCalledWith('EOS_abc', null)
+  })
+})
diff --git a/frontend/src/__tests__/components/SettingsViewVipPerks.test.ts b/frontend/src/__tests__/components/SettingsViewVipPerks.test.ts
new file mode 100644
index 0000000..ae7c030
--- /dev/null
+++ b/frontend/src/__tests__/components/SettingsViewVipPerks.test.ts
@@ -0,0 +1,122 @@
+// Focused coverage for the VIP Perks tab of SettingsView. We render ONLY that
+// panel (the TabPanel stub renders its slot solely for value === "11"), so the
+// other tabs' templates never execute — their fetch-on-mount calls are mocked
+// to resolve with harmless shapes purely so onMounted doesn't throw.
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia } from 'pinia'
+import PrimeVue from 'primevue/config'
+
+const mockGetVipPerks = vi.fn()
+const mockUpdateVipPerks = vi.fn()
+
+vi.mock('@/api/vipperks', () => ({
+  getVipPerksSettings: () => mockGetVipPerks(),
+  updateVipPerksSettings: (...a: any[]) => mockUpdateVipPerks(...a),
+  getVipTiers: () => Promise.resolve([]),
+}))
+
+// Every other tab's data source — resolve with shapes safe to assign.
+vi.mock('@/api/auth', () => ({ changePassword: vi.fn() }))
+vi.mock('@/api/users', () => ({
+  getUsers: () => Promise.resolve([]), createUser: vi.fn(), updateUser: vi.fn(),
+  resetUserPassword: vi.fn(), deleteUser: vi.fn(),
+}))
+vi.mock('@/api/settings', () => ({
+  getChatCommandSettings: () => Promise.resolve({}), updateChatCommandSettings: vi.fn(),
+  getPointsSettings: () => Promise.resolve({}), updatePointsSettings: vi.fn(),
+  getTeleportSettings: () => Promise.resolve({}), updateTeleportSettings: vi.fn(),
+  getStoreSettings: () => Promise.resolve({}), updateStoreSettings: vi.fn(),
+}))
+vi.mock('@/api/bloodmoonvote', () => ({ getVoteSettings: () => Promise.resolve({}), updateVoteSettings: vi.fn() }))
+vi.mock('@/api/voterewards', () => ({
+  getVoteRewardsSettings: () => Promise.resolve({ enabled: false, providers: [] }),
+  updateVoteRewardsSettings: vi.fn(),
+  getVoteGrants: () => Promise.resolve([]),
+}))
+vi.mock('@/api/restart', () => ({ getRestartSettings: () => Promise.resolve({}), updateRestartSettings: vi.fn(), triggerRestartNow: vi.fn() }))
+vi.mock('@/api/tickets', () => ({ getTicketSettings: () => Promise.resolve({}), updateTicketSettings: vi.fn() }))
+vi.mock('@/api/discord', () => ({
+  getDiscordSettings: () => Promise.resolve({}), updateDiscordSettings: vi.fn(),
+  getDiscordStatus: () => Promise.resolve({ isConnected: false }), testDiscordConnection: vi.fn(),
+}))
+vi.mock('@/api/serverControl', () => ({ restartServer: vi.fn() }))
+vi.mock('@/composables/usePermissions', () => ({ usePermissions: () => ({ isAdmin: { value: true } }) }))
+vi.mock('primevue/useconfirm', () => ({ useConfirm: () => ({ require: vi.fn() }) }))
+
+import SettingsView from '@/views/SettingsView.vue'
+
+const sample = {
+  enabled: true,
+  tiers: ['VIP'],
+  firstLoginPackEnabled: false,
+  firstLoginTemplateName: '',
+  firstLoginMessage: '',
+  tierGifts: [{ tier: 'VIP', templateName: 'crate', period: 'weekly' }],
+}
+
+const slotStub = (name: string) => ({ name, template: '<div><slot /></div>' })
+
+function mountView() {
+  return mount(SettingsView, {
+    global: {
+      plugins: [createPinia(), [PrimeVue, { theme: 'none' }]],
+      stubs: {
+        Tabs: slotStub('Tabs'),
+        TabList: slotStub('TabList'),
+        TabPanels: slotStub('TabPanels'),
+        Tab: { name: 'Tab', template: '<div><slot /></div>', props: ['value'] },
+        // Render a panel's content only for the VIP Perks tab.
+        TabPanel: { name: 'TabPanel', props: ['value'], template: '<div v-if="value === \'11\'"><slot /></div>' },
+        Card: { name: 'Card', template: '<div><slot name="title" /><slot name="subtitle" /><slot name="content" /></div>' },
+        // No explicit @click emit: the parent's @click is a native fall-through
+        // listener on the stub's root <button>, so emitting here too would fire
+        // the handler twice. Let trigger('click') hit the native listener once.
+        Button: { name: 'Button', props: ['label', 'icon'], template: '<button :data-icon="icon">{{ label }}</button>' },
+        InputText: { name: 'InputText', props: ['modelValue'], template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />' },
+        ToggleSwitch: { name: 'ToggleSwitch', props: ['modelValue'], template: '<input type="checkbox" />' },
+        Select: { name: 'Select', props: ['modelValue', 'options'], template: '<select />' },
+        // Unused-by-this-panel components — empty stubs are fine.
+        Message: true, InputNumber: true, DataTable: true, Column: true, Tag: true, Dialog: true,
+      },
+    },
+  })
+}
+
+describe('SettingsView — VIP Perks tab', () => {
+  beforeEach(() => {
+    mockGetVipPerks.mockReset().mockResolvedValue({ ...sample, tierGifts: [...sample.tierGifts], tiers: [...sample.tiers] })
+    mockUpdateVipPerks.mockReset().mockResolvedValue(undefined)
+  })
+
+  it('fetches VIP perks settings on mount and renders the panel', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    expect(mockGetVipPerks).toHaveBeenCalled()
+    expect(wrapper.text()).toContain('settings.vipPerksTitle')
+  })
+
+  it('add/remove tier + tier gift and save all run', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const byLabel = (label: string) => wrapper.findAll('button').find((b) => b.text() === label)!
+
+    await byLabel('settings.vipPerksAddTier').trigger('click')
+    await byLabel('settings.vipPerksAddTierGift').trigger('click')
+
+    const trashes = wrapper.findAll('button[data-icon="pi pi-trash"]')
+    await trashes[0].trigger('click')                       // removeVipTier
+    await trashes[trashes.length - 1].trigger('click')      // removeTierGift
+
+    await byLabel('settings.saveSettings').trigger('click')
+    await flushPromises()
+
+    expect(mockUpdateVipPerks).toHaveBeenCalledTimes(1)
+    // Blank tiers are stripped before save.
+    const saved = mockUpdateVipPerks.mock.calls[0][0]
+    expect(saved.tiers.every((t: string) => t.length > 0)).toBe(true)
+    // A reload follows a successful save.
+    expect(mockGetVipPerks).toHaveBeenCalledTimes(2)
+  })
+})