feat: add comprehensive tier-based feature management system

Implement database-driven feature gating with contextual upgrade prompts:

- Add Feature model with 30 features across 8 categories
- Create FeatureService with caching for tier-based feature checking
- Add @require_feature decorator and RequireFeature dependency for backend enforcement
- Create vendor features API (6 endpoints) and admin features API
- Add Alpine.js feature store and upgrade prompts store for frontend
- Create Jinja macros: feature_gate, feature_locked, limit_warning, usage_bar
- Add usage API for tracking orders/products/team limits with upgrade info
- Fix Stripe webhook to create VendorAddOn records on addon purchase
- Integrate upgrade prompts into vendor dashboard with tier badge and usage bars

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/templates/admin/features.html

@@ -0,0 +1,370 @@
+{% extends "admin/base.html" %}
+
+{% block title %}Feature Management{% endblock %}
+
+{% block alpine_data %}featuresPage(){% endblock %}
+
+{% block content %}
+<div class="py-6">
+    <!-- Header -->
+    <div class="mb-8">
+        <h2 class="text-2xl font-semibold text-gray-700 dark:text-gray-200">
+            Feature Management
+        </h2>
+        <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+            Configure which features are available to each subscription tier.
+        </p>
+    </div>
+
+    <!-- Loading State -->
+    <div x-show="loading" class="flex justify-center py-12">
+        <svg class="animate-spin h-8 w-8 text-purple-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+        </svg>
+    </div>
+
+    <!-- Tier Tabs -->
+    <div x-show="!loading" x-cloak>
+        <!-- Tab Navigation -->
+        <div class="border-b border-gray-200 dark:border-gray-700 mb-6">
+            <nav class="-mb-px flex space-x-8">
+                <template x-for="tier in tiers" :key="tier.code">
+                    <button
+                        @click="selectedTier = tier.code"
+                        :class="{
+                            'border-purple-500 text-purple-600 dark:text-purple-400': selectedTier === tier.code,
+                            'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 dark:text-gray-400 dark:hover:text-gray-300': selectedTier !== tier.code
+                        }"
+                        class="whitespace-nowrap py-4 px-1 border-b-2 font-medium text-sm transition-colors">
+                        <span x-text="tier.name"></span>
+                        <span class="ml-2 px-2 py-0.5 text-xs rounded-full"
+                              :class="selectedTier === tier.code ? 'bg-purple-100 text-purple-600 dark:bg-purple-900 dark:text-purple-300' : 'bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-400'"
+                              x-text="tier.feature_count"></span>
+                    </button>
+                </template>
+            </nav>
+        </div>
+
+        <!-- Features Grid -->
+        <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+            <!-- Available Features (for selected tier) -->
+            <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+                <div class="flex items-center justify-between mb-4">
+                    <h3 class="text-lg font-medium text-gray-900 dark:text-white">
+                        Included Features
+                    </h3>
+                    <span class="text-sm text-gray-500 dark:text-gray-400"
+                          x-text="`${getSelectedTierFeatures().length} features`"></span>
+                </div>
+
+                <div class="space-y-2 max-h-96 overflow-y-auto">
+                    <template x-for="featureCode in getSelectedTierFeatures()" :key="featureCode">
+                        <div class="flex items-center justify-between p-3 bg-green-50 dark:bg-green-900/20 rounded-lg">
+                            <div class="flex items-center">
+                                <svg class="w-5 h-5 text-green-500 mr-3" fill="currentColor" viewBox="0 0 20 20">
+                                    <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd"/>
+                                </svg>
+                                <div>
+                                    <p class="text-sm font-medium text-gray-900 dark:text-white"
+                                       x-text="getFeatureName(featureCode)"></p>
+                                    <p class="text-xs text-gray-500 dark:text-gray-400"
+                                       x-text="getFeatureCategory(featureCode)"></p>
+                                </div>
+                            </div>
+                            <button
+                                @click="removeFeatureFromTier(featureCode)"
+                                class="text-red-500 hover:text-red-700 p-1">
+                                <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/>
+                                </svg>
+                            </button>
+                        </div>
+                    </template>
+
+                    <div x-show="getSelectedTierFeatures().length === 0"
+                         class="text-center py-8 text-gray-500 dark:text-gray-400">
+                        No features assigned to this tier
+                    </div>
+                </div>
+            </div>
+
+            <!-- All Features (to add) -->
+            <div class="bg-white dark:bg-gray-800 rounded-lg shadow p-6">
+                <div class="flex items-center justify-between mb-4">
+                    <h3 class="text-lg font-medium text-gray-900 dark:text-white">
+                        Available to Add
+                    </h3>
+                    <select
+                        x-model="categoryFilter"
+                        class="text-sm border-gray-300 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-300 rounded-md">
+                        <option value="">All Categories</option>
+                        <template x-for="cat in categories" :key="cat">
+                            <option :value="cat" x-text="cat.charAt(0).toUpperCase() + cat.slice(1)"></option>
+                        </template>
+                    </select>
+                </div>
+
+                <div class="space-y-2 max-h-96 overflow-y-auto">
+                    <template x-for="feature in getAvailableFeatures()" :key="feature.code">
+                        <div class="flex items-center justify-between p-3 bg-gray-50 dark:bg-gray-700 rounded-lg">
+                            <div class="flex items-center">
+                                <svg class="w-5 h-5 text-gray-400 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                                          d="M12 6v6m0 0v6m0-6h6m-6 0H6"/>
+                                </svg>
+                                <div>
+                                    <p class="text-sm font-medium text-gray-900 dark:text-white"
+                                       x-text="feature.name"></p>
+                                    <p class="text-xs text-gray-500 dark:text-gray-400"
+                                       x-text="feature.category"></p>
+                                </div>
+                            </div>
+                            <button
+                                @click="addFeatureToTier(feature.code)"
+                                class="text-green-500 hover:text-green-700 p-1">
+                                <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6v6m0 0v6m0-6h6m-6 0H6"/>
+                                </svg>
+                            </button>
+                        </div>
+                    </template>
+
+                    <div x-show="getAvailableFeatures().length === 0"
+                         class="text-center py-8 text-gray-500 dark:text-gray-400">
+                        All features are assigned to this tier
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Save Button -->
+        <div class="mt-6 flex justify-end">
+            <button
+                @click="saveTierFeatures"
+                :disabled="saving || !hasChanges"
+                :class="{
+                    'opacity-50 cursor-not-allowed': saving || !hasChanges,
+                    'hover:bg-purple-700': !saving && hasChanges
+                }"
+                class="inline-flex items-center px-4 py-2 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-purple-600 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500">
+                <svg x-show="saving" class="animate-spin -ml-1 mr-2 h-4 w-4 text-white" fill="none" viewBox="0 0 24 24">
+                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                </svg>
+                <span x-text="saving ? 'Saving...' : 'Save Changes'"></span>
+            </button>
+        </div>
+
+        <!-- All Features Table -->
+        <div class="mt-8 bg-white dark:bg-gray-800 rounded-lg shadow">
+            <div class="px-6 py-4 border-b border-gray-200 dark:border-gray-700">
+                <h3 class="text-lg font-medium text-gray-900 dark:text-white">
+                    All Features
+                </h3>
+                <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+                    Complete list of all platform features with their minimum tier requirement.
+                </p>
+            </div>
+            <div class="overflow-x-auto">
+                <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+                    <thead class="bg-gray-50 dark:bg-gray-700">
+                        <tr>
+                            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-300 uppercase tracking-wider">
+                                Feature
+                            </th>
+                            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-300 uppercase tracking-wider">
+                                Category
+                            </th>
+                            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-300 uppercase tracking-wider">
+                                Minimum Tier
+                            </th>
+                            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-300 uppercase tracking-wider">
+                                Status
+                            </th>
+                        </tr>
+                    </thead>
+                    <tbody class="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
+                        <template x-for="feature in allFeatures" :key="feature.code">
+                            <tr>
+                                <td class="px-6 py-4 whitespace-nowrap">
+                                    <div class="text-sm font-medium text-gray-900 dark:text-white" x-text="feature.name"></div>
+                                    <div class="text-xs text-gray-500 dark:text-gray-400" x-text="feature.code"></div>
+                                </td>
+                                <td class="px-6 py-4 whitespace-nowrap">
+                                    <span class="px-2 py-1 text-xs rounded-full bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300"
+                                          x-text="feature.category"></span>
+                                </td>
+                                <td class="px-6 py-4 whitespace-nowrap">
+                                    <span class="px-2 py-1 text-xs rounded-full"
+                                          :class="{
+                                              'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300': feature.minimum_tier_code === 'essential',
+                                              'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300': feature.minimum_tier_code === 'professional',
+                                              'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-300': feature.minimum_tier_code === 'business',
+                                              'bg-orange-100 text-orange-800 dark:bg-orange-900 dark:text-orange-300': feature.minimum_tier_code === 'enterprise',
+                                              'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-300': !feature.minimum_tier_code
+                                          }"
+                                          x-text="feature.minimum_tier_name || 'N/A'"></span>
+                                </td>
+                                <td class="px-6 py-4 whitespace-nowrap">
+                                    <span x-show="feature.is_active"
+                                          class="px-2 py-1 text-xs rounded-full bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300">
+                                        Active
+                                    </span>
+                                    <span x-show="!feature.is_active"
+                                          class="px-2 py-1 text-xs rounded-full bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300">
+                                        Inactive
+                                    </span>
+                                </td>
+                            </tr>
+                        </template>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+function featuresPage() {
+    return {
+        ...data(),
+
+        // State
+        loading: true,
+        saving: false,
+        tiers: [],
+        allFeatures: [],
+        categories: [],
+        selectedTier: 'essential',
+        categoryFilter: '',
+        originalTierFeatures: {},  // To track changes
+        currentTierFeatures: {},   // Current state
+
+        // Computed
+        get hasChanges() {
+            const original = this.originalTierFeatures[this.selectedTier] || [];
+            const current = this.currentTierFeatures[this.selectedTier] || [];
+            return JSON.stringify(original.sort()) !== JSON.stringify(current.sort());
+        },
+
+        // Lifecycle
+        async init() {
+            // Call parent init
+            const path = window.location.pathname;
+            const segments = path.split('/').filter(Boolean);
+            this.currentPage = segments[segments.length - 1] || 'features';
+
+            await this.loadData();
+        },
+
+        // Methods
+        async loadData() {
+            try {
+                this.loading = true;
+
+                // Load tiers and features in parallel
+                const [tiersResponse, featuresResponse, categoriesResponse] = await Promise.all([
+                    apiClient.get('/admin/features/tiers'),
+                    apiClient.get('/admin/features'),
+                    apiClient.get('/admin/features/categories'),
+                ]);
+
+                this.tiers = tiersResponse.tiers;
+                this.allFeatures = featuresResponse.features;
+                this.categories = categoriesResponse.categories;
+
+                // Initialize tier features tracking
+                for (const tier of this.tiers) {
+                    this.originalTierFeatures[tier.code] = [...tier.features];
+                    this.currentTierFeatures[tier.code] = [...tier.features];
+                }
+
+            } catch (error) {
+                console.error('Failed to load features:', error);
+                this.showNotification('Failed to load features', 'error');
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        getSelectedTierFeatures() {
+            return this.currentTierFeatures[this.selectedTier] || [];
+        },
+
+        getAvailableFeatures() {
+            const tierFeatures = this.getSelectedTierFeatures();
+            return this.allFeatures.filter(f => {
+                const notIncluded = !tierFeatures.includes(f.code);
+                const matchesCategory = !this.categoryFilter || f.category === this.categoryFilter;
+                return notIncluded && matchesCategory && f.is_active;
+            });
+        },
+
+        getFeatureName(code) {
+            const feature = this.allFeatures.find(f => f.code === code);
+            return feature?.name || code;
+        },
+
+        getFeatureCategory(code) {
+            const feature = this.allFeatures.find(f => f.code === code);
+            return feature?.category || 'unknown';
+        },
+
+        addFeatureToTier(featureCode) {
+            if (!this.currentTierFeatures[this.selectedTier].includes(featureCode)) {
+                this.currentTierFeatures[this.selectedTier].push(featureCode);
+            }
+        },
+
+        removeFeatureFromTier(featureCode) {
+            const index = this.currentTierFeatures[this.selectedTier].indexOf(featureCode);
+            if (index > -1) {
+                this.currentTierFeatures[this.selectedTier].splice(index, 1);
+            }
+        },
+
+        async saveTierFeatures() {
+            if (!this.hasChanges) return;
+
+            try {
+                this.saving = true;
+
+                await apiClient.put(`/admin/features/tiers/${this.selectedTier}/features`, {
+                    feature_codes: this.currentTierFeatures[this.selectedTier]
+                });
+
+                // Update original to match current
+                this.originalTierFeatures[this.selectedTier] = [...this.currentTierFeatures[this.selectedTier]];
+
+                // Update tier in tiers array
+                const tier = this.tiers.find(t => t.code === this.selectedTier);
+                if (tier) {
+                    tier.features = [...this.currentTierFeatures[this.selectedTier]];
+                    tier.feature_count = tier.features.length;
+                }
+
+                this.showNotification('Features saved successfully', 'success');
+
+            } catch (error) {
+                console.error('Failed to save features:', error);
+                this.showNotification('Failed to save features', 'error');
+            } finally {
+                this.saving = false;
+            }
+        },
+
+        showNotification(message, type = 'info') {
+            // Simple alert for now - could be improved with toast notifications
+            if (type === 'error') {
+                alert('Error: ' + message);
+            } else {
+                console.log(message);
+            }
+        }
+    };
+}
+</script>
+{% endblock %}

app/templates/shared/macros/feature_gate.html

@@ -0,0 +1,335 @@
+{# =============================================================================
+   Feature Gate Macros
+
+   Provides macros for tier-based feature gating in templates.
+   Uses Alpine.js $store.features for dynamic checking.
+
+   Usage:
+   {% from "shared/macros/feature_gate.html" import feature_gate, feature_locked, upgrade_banner %}
+
+   {# Show content only if feature is available #}
+   {% call feature_gate("analytics_dashboard") %}
+       <div>Analytics content here</div>
+   {% endcall %}
+
+   {# Show locked state with upgrade prompt #}
+   {{ feature_locked("analytics_dashboard", "Analytics Dashboard", "View advanced analytics") }}
+
+   {# Show upgrade banner #}
+   {{ upgrade_banner("analytics_dashboard") }}
+   ============================================================================= #}
+
+
+{# =============================================================================
+   Feature Gate Container
+   Shows content only if feature is available
+
+   Parameters:
+   - feature_code: The feature code to check
+   - fallback: Optional fallback content when feature is not available
+   ============================================================================= #}
+{% macro feature_gate(feature_code, show_fallback=true) %}
+<div x-data x-show="$store.features.has('{{ feature_code }}')" x-cloak>
+    {{ caller() }}
+</div>
+{% if show_fallback %}
+<div x-data x-show="$store.features.loaded && !$store.features.has('{{ feature_code }}')" x-cloak>
+    {{ feature_locked(feature_code) }}
+</div>
+{% endif %}
+{% endmacro %}
+
+
+{# =============================================================================
+   Feature Locked Card
+   Shows a card explaining the feature is locked with upgrade prompt
+
+   Parameters:
+   - feature_code: The feature code
+   - title: Optional title override
+   - description: Optional description override
+   - show_upgrade_button: Whether to show upgrade button (default true)
+   ============================================================================= #}
+{% macro feature_locked(feature_code, title=none, description=none, show_upgrade_button=true) %}
+<div class="bg-gray-50 dark:bg-gray-800 rounded-lg border-2 border-dashed border-gray-300 dark:border-gray-600 p-6 text-center"
+     x-data="{ feature: null }"
+     x-init="
+         await $store.features.loadFullFeatures();
+         feature = $store.features.getFeature('{{ feature_code }}');
+     ">
+    {# Lock icon #}
+    <div class="mx-auto w-12 h-12 rounded-full bg-gray-200 dark:bg-gray-700 flex items-center justify-center mb-4">
+        <svg class="w-6 h-6 text-gray-400 dark:text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                  d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"/>
+        </svg>
+    </div>
+
+    {# Title #}
+    <h3 class="text-lg font-medium text-gray-900 dark:text-white mb-2">
+        {% if title %}
+            {{ title }}
+        {% else %}
+            <span x-text="feature?.name || 'Premium Feature'">Premium Feature</span>
+        {% endif %}
+    </h3>
+
+    {# Description #}
+    <p class="text-sm text-gray-500 dark:text-gray-400 mb-4">
+        {% if description %}
+            {{ description }}
+        {% else %}
+            <span x-text="feature?.description || 'This feature requires a plan upgrade.'">
+                This feature requires a plan upgrade.
+            </span>
+        {% endif %}
+    </p>
+
+    {# Tier badge #}
+    <p class="text-sm text-gray-600 dark:text-gray-300 mb-4">
+        Available on
+        <span class="font-semibold text-purple-600 dark:text-purple-400"
+              x-text="feature?.minimum_tier_name || 'higher tier'">higher tier</span>
+        plan
+    </p>
+
+    {% if show_upgrade_button %}
+    {# Upgrade button #}
+    <a :href="`/vendor/${$store.features.getVendorCode()}/billing`"
+       class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md
+              text-white bg-purple-600 hover:bg-purple-700 focus:outline-none focus:ring-2
+              focus:ring-offset-2 focus:ring-purple-500 transition-colors">
+        <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                  d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6"/>
+        </svg>
+        Upgrade Plan
+    </a>
+    {% endif %}
+</div>
+{% endmacro %}
+
+
+{# =============================================================================
+   Upgrade Banner
+   Inline banner for upgrade prompts
+
+   Parameters:
+   - feature_code: The feature code
+   - message: Optional custom message
+   ============================================================================= #}
+{% macro upgrade_banner(feature_code, message=none) %}
+<div x-data="{ feature: null }"
+     x-init="
+         await $store.features.loadFullFeatures();
+         feature = $store.features.getFeature('{{ feature_code }}');
+     "
+     x-show="$store.features.loaded && !$store.features.has('{{ feature_code }}')"
+     x-cloak
+     class="bg-gradient-to-r from-purple-500 to-indigo-600 rounded-lg p-4 mb-4">
+    <div class="flex items-center justify-between">
+        <div class="flex items-center">
+            <svg class="w-5 h-5 text-white mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                      d="M13 10V3L4 14h7v7l9-11h-7z"/>
+            </svg>
+            <p class="text-white text-sm">
+                {% if message %}
+                    {{ message }}
+                {% else %}
+                    <span x-text="'Upgrade to ' + (feature?.minimum_tier_name || 'a higher plan') + ' to unlock ' + (feature?.name || 'this feature')">
+                        Upgrade to unlock this feature
+                    </span>
+                {% endif %}
+            </p>
+        </div>
+        <a :href="`/vendor/${$store.features.getVendorCode()}/billing`"
+           class="inline-flex items-center px-3 py-1.5 border border-white text-xs font-medium rounded
+                  text-white hover:bg-white hover:text-purple-600 transition-colors">
+            Upgrade
+        </a>
+    </div>
+</div>
+{% endmacro %}
+
+
+{# =============================================================================
+   Feature Badge
+   Small badge to show feature tier requirement
+
+   Parameters:
+   - feature_code: The feature code
+   ============================================================================= #}
+{% macro feature_badge(feature_code) %}
+<span x-data="{ feature: null }"
+      x-init="
+          await $store.features.loadFullFeatures();
+          feature = $store.features.getFeature('{{ feature_code }}');
+      "
+      x-show="!$store.features.has('{{ feature_code }}')"
+      x-cloak
+      class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200">
+    <svg class="w-3 h-3 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+              d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"/>
+    </svg>
+    <span x-text="feature?.minimum_tier_name || 'Pro'">Pro</span>
+</span>
+{% endmacro %}
+
+
+{# =============================================================================
+   Sidebar Item with Feature Gate
+   Sidebar navigation item that shows lock if feature not available
+
+   Parameters:
+   - feature_code: The feature code
+   - href: Link URL
+   - icon: Icon name
+   - label: Display label
+   - current_page: Current page for active state
+   ============================================================================= #}
+{% macro sidebar_item_gated(feature_code, href, icon, label, current_page='') %}
+<template x-if="$store.features.has('{{ feature_code }}')">
+    <a href="{{ href }}"
+       class="flex items-center px-4 py-2 text-sm font-medium rounded-lg transition-colors
+              {{ 'bg-gray-100 dark:bg-gray-800 text-gray-900 dark:text-white' if current_page == label|lower else 'text-gray-600 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-800 hover:text-gray-900 dark:hover:text-white' }}">
+        <span class="w-5 h-5 mr-3" x-html="window.icons?.['{{ icon }}'] || ''"></span>
+        {{ label }}
+    </a>
+</template>
+<template x-if="!$store.features.has('{{ feature_code }}')">
+    <div class="flex items-center px-4 py-2 text-sm font-medium rounded-lg text-gray-400 dark:text-gray-500 cursor-not-allowed"
+         title="Requires plan upgrade">
+        <span class="w-5 h-5 mr-3" x-html="window.icons?.['{{ icon }}'] || ''"></span>
+        {{ label }}
+        <svg class="w-4 h-4 ml-auto" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                  d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"/>
+        </svg>
+    </div>
+</template>
+{% endmacro %}
+
+
+{# =============================================================================
+   UPGRADE PROMPT MACROS
+   ============================================================================= #}
+
+
+{# =============================================================================
+   Usage Limit Warning
+   Shows warning banner when approaching or at a limit
+
+   Parameters:
+   - metric_name: One of "orders", "products", "team_members"
+   ============================================================================= #}
+{% macro limit_warning(metric_name) %}
+<div x-data
+     x-init="$store.upgrade.loadUsage()"
+     x-show="$store.upgrade.shouldShowLimitWarning('{{ metric_name }}')"
+     x-cloak
+     x-html="$store.upgrade.getLimitWarningHTML('{{ metric_name }}')">
+</div>
+{% endmacro %}
+
+
+{# =============================================================================
+   Usage Progress Bar
+   Shows compact progress bar for a limit
+
+   Parameters:
+   - metric_name: One of "orders", "products", "team_members"
+   - label: Display label
+   ============================================================================= #}
+{% macro usage_bar(metric_name, label) %}
+<div x-data x-init="$store.upgrade.loadUsage()">
+    <div class="flex items-center justify-between mb-1">
+        <span class="text-sm font-medium text-gray-700 dark:text-gray-300">{{ label }}</span>
+        <span class="text-sm text-gray-500 dark:text-gray-400"
+              x-text="$store.upgrade.getUsageString('{{ metric_name }}')"></span>
+    </div>
+    <div x-html="$store.upgrade.getUsageBarHTML('{{ metric_name }}')"></div>
+</div>
+{% endmacro %}
+
+
+{# =============================================================================
+   Upgrade Card
+   Shows upgrade recommendation card (for dashboard)
+   Only shows if there are upgrade recommendations
+
+   Parameters:
+   - class: Additional CSS classes
+   ============================================================================= #}
+{% macro upgrade_card(class='') %}
+<div x-data
+     x-init="$store.upgrade.loadUsage()"
+     x-show="$store.upgrade.hasUpgradeRecommendation"
+     x-cloak
+     class="{{ class }}"
+     x-html="$store.upgrade.getUpgradeCardHTML()">
+</div>
+{% endmacro %}
+
+
+{# =============================================================================
+   Limit Check Button
+   Button that checks limit before action
+
+   Parameters:
+   - limit_type: One of "orders", "products", "team_members"
+   - action: JavaScript to execute if limit allows
+   - label: Button label
+   - class: Additional CSS classes
+   ============================================================================= #}
+{% macro limit_check_button(limit_type, action, label, class='') %}
+<button
+    @click="$store.upgrade.checkLimitAndProceed('{{ limit_type }}', () => { {{ action }} })"
+    class="{{ class }}">
+    {{ label }}
+</button>
+{% endmacro %}
+
+
+{# =============================================================================
+   Tier Badge
+   Shows current tier as a badge
+
+   Parameters:
+   - class: Additional CSS classes
+   ============================================================================= #}
+{% macro tier_badge(class='') %}
+<span x-data
+      x-init="$store.upgrade.loadUsage()"
+      x-show="$store.upgrade.currentTier"
+      x-cloak
+      class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium {{ class }}"
+      :class="{
+          'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300': $store.upgrade.currentTier?.code === 'essential',
+          'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300': $store.upgrade.currentTier?.code === 'professional',
+          'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-300': $store.upgrade.currentTier?.code === 'business',
+          'bg-orange-100 text-orange-800 dark:bg-orange-900 dark:text-orange-300': $store.upgrade.currentTier?.code === 'enterprise'
+      }"
+      x-text="$store.upgrade.currentTier?.name">
+</span>
+{% endmacro %}
+
+
+{# =============================================================================
+   Quick Upgrade Link
+   Simple upgrade link that appears when limits are reached
+   ============================================================================= #}
+{% macro quick_upgrade_link() %}
+<a x-data
+   x-init="$store.upgrade.loadUsage()"
+   x-show="$store.upgrade.hasLimitsReached && $store.upgrade.nextTier"
+   x-cloak
+   :href="$store.upgrade.getBillingUrl()"
+   class="inline-flex items-center text-sm text-purple-600 dark:text-purple-400 hover:text-purple-800 dark:hover:text-purple-300">
+    <svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7h8m0 0v8m0-8l-8 8-4-4-6 6"/>
+    </svg>
+    <span>Upgrade to <span x-text="$store.upgrade.nextTier?.name"></span></span>
+</a>
+{% endmacro %}

app/templates/vendor/base.html

@@ -62,7 +62,13 @@
     <!-- 5. FIFTH: API Client (depends on Utils) -->
     <script src="{{ url_for('static', path='shared/js/api-client.js') }}"></script>
 
-    <!-- 6. SIXTH: Alpine.js v3 with CDN fallback (with defer) -->
+    <!-- 6. SIXTH: Feature Store (depends on API Client, registers with Alpine) -->
+    <script src="{{ url_for('static', path='shared/js/feature-store.js') }}"></script>
+
+    <!-- 7. SEVENTH: Upgrade Prompts (depends on API Client, registers with Alpine) -->
+    <script src="{{ url_for('static', path='shared/js/upgrade-prompts.js') }}"></script>
+
+    <!-- 8. EIGHTH: Alpine.js v3 with CDN fallback (with defer) -->
     <script>
     (function() {
         var script = document.createElement('script');
@@ -81,7 +87,7 @@
     })();
     </script>
 
-    <!-- 7. LAST: Page-specific scripts -->
+    <!-- 9. LAST: Page-specific scripts -->
     {% block extra_scripts %}{% endblock %}
 </body>
 </html>

app/templates/vendor/dashboard.html

@@ -1,16 +1,24 @@
 {# app/templates/vendor/dashboard.html #}
 {% extends "vendor/base.html" %}
+{% from "shared/macros/feature_gate.html" import limit_warning, usage_bar, upgrade_card, tier_badge %}
 
 {% block title %}Dashboard{% endblock %}
 
 {% block alpine_data %}vendorDashboard(){% endblock %}
 
 {% block content %}
+<!-- Limit Warnings -->
+{{ limit_warning("orders") }}
+{{ limit_warning("products") }}
+
 <!-- Page Header with Refresh Button -->
 <div class="flex items-center justify-between my-6">
-    <h2 class="text-2xl font-semibold text-gray-700 dark:text-gray-200">
-        Dashboard
-    </h2>
+    <div class="flex items-center gap-3">
+        <h2 class="text-2xl font-semibold text-gray-700 dark:text-gray-200">
+            Dashboard
+        </h2>
+        {{ tier_badge() }}
+    </div>
     <button
         @click="refresh()"
         :disabled="loading"
@@ -40,6 +48,9 @@
 <!-- Vendor Info Card -->
 {% include 'vendor/partials/vendor_info.html' %}
 
+<!-- Upgrade Recommendation Card (shows when approaching/at limits) -->
+{{ upgrade_card(class='mb-6') }}
+
 <!-- Stats Cards -->
 <div x-show="!loading" class="grid gap-6 mb-8 md:grid-cols-2 xl:grid-cols-4">
     <!-- Card: Total Products -->
@@ -103,6 +114,19 @@
     </div>
 </div>
 
+<!-- Usage Overview -->
+<div x-show="!loading" class="grid gap-6 mb-8 md:grid-cols-3">
+    <div class="p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
+        {{ usage_bar("orders", "Monthly Orders") }}
+    </div>
+    <div class="p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
+        {{ usage_bar("products", "Products") }}
+    </div>
+    <div class="p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
+        {{ usage_bar("team_members", "Team Members") }}
+    </div>
+</div>
+
 <!-- Recent Orders Table -->
 <div x-show="!loading && recentOrders.length > 0" class="w-full mb-8 overflow-hidden rounded-lg shadow-xs">
     <div class="w-full overflow-x-auto">