diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..dcb2144
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,64 @@
+# Nexus Autoparts — Environment Variables
+# Copy this file to .env and fill in your values.
+# NEVER commit .env to git.
+
+# ═══════════════════════════════════════════════════════════════════════════
+# DATABASE (REQUIRED)
+# ═══════════════════════════════════════════════════════════════════════════
+DATABASE_URL=postgresql://nexus:YOUR_DB_PASSWORD@localhost/nexus_autoparts
+MASTER_DB_URL=postgresql://nexus:YOUR_DB_PASSWORD@localhost/nexus_autoparts
+TENANT_DB_URL_TEMPLATE=postgresql://nexus:YOUR_DB_PASSWORD@localhost/{db_name}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# SECURITY (REQUIRED)
+# ═══════════════════════════════════════════════════════════════════════════
+# Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
+JWT_SECRET=change-me-to-a-random-64-char-hex-string
+POS_JWT_SECRET=change-me-to-a-different-random-64-char-hex-string
+
+# ═══════════════════════════════════════════════════════════════════════════
+# AI / OpenRouter (OPTIONAL — enables chatbot)
+# ═══════════════════════════════════════════════════════════════════════════
+OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key
+
+# ═══════════════════════════════════════════════════════════════════════════
+# WHATSAPP BRIDGE (OPTIONAL — enables WhatsApp integration)
+# ═══════════════════════════════════════════════════════════════════════════
+WHATSAPP_BRIDGE_URL=http://localhost:21465
+WHATSAPP_BRIDGE_KEY=your-whatsapp-bridge-secret
+
+# ═══════════════════════════════════════════════════════════════════════════
+# SMTP (OPTIONAL — enables email quotations)
+# ═══════════════════════════════════════════════════════════════════════════
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+SMTP_FROM=noreply@yourdomain.com
+
+# ═══════════════════════════════════════════════════════════════════════════
+# REDIS CACHE (OPTIONAL — enables sub-millisecond stock lookups)
+# ═══════════════════════════════════════════════════════════════════════════
+REDIS_URL=redis://localhost:6379/0
+REDIS_ENABLED=true
+REDIS_STOCK_TTL=300
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MEILISEARCH (OPTIONAL — enables sub-100ms catalog search)
+# ═══════════════════════════════════════════════════════════════════════════
+MEILI_URL=http://localhost:7700
+MEILI_API_KEY=nexus-master-key-change-me
+
+# ═══════════════════════════════════════════════════════════════════════════
+# METABASE KPIs (OPTIONAL — Business Intelligence dashboards)
+# ═══════════════════════════════════════════════════════════════════════════
+METABASE_URL=http://localhost:3000
+METABASE_ADMIN_EMAIL=admin@nexus.local
+METABASE_ADMIN_PASS=change-me-to-a-strong-password
+METABASE_DB_PASS=metabase_secret
+
+# ═══════════════════════════════════════════════════════════════════════════
+# CURRENCY
+# ═══════════════════════════════════════════════════════════════════════════
+DEFAULT_CURRENCY=MXN
+EXCHANGE_RATE_USD_MXN=17.5
diff --git a/pos/seed/initial_catalog.sql b/pos/seed/initial_catalog.sql
new file mode 100644
index 0000000..a6632c7
--- /dev/null
+++ b/pos/seed/initial_catalog.sql
@@ -0,0 +1,187 @@
+-- Initial catalog seed for Nexus Autoparts (no TecDoc required)
+-- Provides basic vehicle brands, models, years, and part categories
+-- so the system is usable immediately after installation.
+
+-- =====================================================
+-- PART CATEGORIES (RockAuto-style taxonomy)
+-- =====================================================
+
+INSERT INTO part_categories (name, name_es, slug, icon_name, display_order) VALUES
+('Body & Lamp Assembly', 'Carrocería y Iluminación', 'body-lamp', 'fa-car', 1),
+('Brake & Wheel Hub', 'Frenos y Rines', 'brake-wheel', 'fa-circle-stop', 2),
+('Cooling System', 'Sistema de Enfriamiento', 'cooling', 'fa-snowflake', 3),
+('Drivetrain', 'Tren Motriz', 'drivetrain', 'fa-gears', 4),
+('Electrical & Lighting', 'Eléctrico e Iluminación', 'electrical', 'fa-bolt', 5),
+('Engine', 'Motor', 'engine', 'fa-engine', 6),
+('Exhaust', 'Escape', 'exhaust', 'fa-smog', 7),
+('Fuel & Air', 'Combustible y Aire', 'fuel-air', 'fa-gas-pump', 8),
+('Heat & AC', 'Calefacción y Aire Acondicionado', 'heat-ac', 'fa-temperature-half', 9),
+('Steering', 'Dirección', 'steering', 'fa-steering-wheel', 10),
+('Suspension', 'Suspensión', 'suspension', 'fa-shock', 11),
+('Transmission', 'Transmisión', 'transmission', 'fa-gears', 12)
+ON CONFLICT DO NOTHING;
+
+-- =====================================================
+-- PART GROUPS (common groups per category)
+-- =====================================================
+
+INSERT INTO part_groups (category_id, name, name_es, slug, display_order) VALUES
+-- Body & Lamp (1)
+(1, 'Bumpers & Components', 'Defensas y Componentes', 'bumpers', 1),
+(1, 'Fenders', 'Salpicaderas', 'fenders', 2),
+(1, 'Headlights & Taillights', 'Faros y Calaveras', 'lights', 3),
+(1, 'Mirrors', 'Espejos', 'mirrors', 4),
+(1, 'Hood & Trunk', 'Cofre y Cajuela', 'hood-trunk', 5),
+-- Brake & Wheel (2)
+(2, 'Brake Pads', 'Balatas', 'brake-pads', 1),
+(2, 'Brake Rotors', 'Discos de Freno', 'brake-rotors', 2),
+(2, 'Brake Calipers', 'Caliper de Freno', 'calipers', 3),
+(2, 'Brake Drums', 'Tambores de Freno', 'brake-drums', 4),
+(2, 'Wheel Bearings', 'Baleros de Rueda', 'wheel-bearings', 5),
+(2, 'Wheel Hubs', 'Mazas de Rueda', 'wheel-hubs', 6),
+-- Cooling (3)
+(3, 'Radiators', 'Radiadores', 'radiators', 1),
+(3, 'Water Pumps', 'Bombas de Agua', 'water-pumps', 2),
+(3, 'Thermostats', 'Termostatos', 'thermostats', 3),
+(3, 'Cooling Fans', 'Ventiladores', 'cooling-fans', 4),
+(3, 'Hoses & Clamps', 'Mangueras y Abrazaderas', 'hoses', 5),
+-- Drivetrain (4)
+(4, 'Axles & Axle Shafts', 'Ejes y Flechas', 'axles', 1),
+(4, 'Differentials', 'Diferenciales', 'differentials', 2),
+(4, 'Drive Shafts', 'Flechas Cardán', 'drive-shafts', 3),
+(4, 'CV Joints & Boots', 'Juntas Homocinéticas', 'cv-joints', 4),
+-- Electrical (5)
+(5, 'Alternators', 'Alternadores', 'alternators', 1),
+(5, 'Starters', 'Marchas', 'starters', 2),
+(5, 'Batteries', 'Baterías', 'batteries', 3),
+(5, 'Sensors', 'Sensores', 'sensors', 4),
+(5, 'Switches & Relays', 'Interruptores y Relevadores', 'switches', 5),
+-- Engine (6)
+(6, 'Oil Filters', 'Filtros de Aceite', 'oil-filters', 1),
+(6, 'Air Filters', 'Filtros de Aire', 'air-filters', 2),
+(6, 'Fuel Filters', 'Filtros de Gasolina', 'fuel-filters', 3),
+(6, 'Spark Plugs', 'Bujías', 'spark-plugs', 4),
+(6, 'Timing Components', 'Componentes de Distribución', 'timing', 5),
+(6, 'Gaskets & Seals', 'Juntas y Sellos', 'gaskets', 6),
+(6, 'Pistons & Rings', 'Pistones y Anillos', 'pistons', 7),
+-- Exhaust (7)
+(7, 'Mufflers', 'Silenciadores', 'mufflers', 1),
+(7, 'Catalytic Converters', 'Convertidores Catalíticos', 'catalytic', 2),
+(7, 'Exhaust Manifolds', 'Múltiples de Escape', 'manifolds', 3),
+(7, 'O2 Sensors', 'Sensores de Oxígeno', 'o2-sensors', 4),
+-- Fuel & Air (8)
+(8, 'Fuel Pumps', 'Bombas de Gasolina', 'fuel-pumps', 1),
+(8, 'Fuel Injectors', 'Inyectores', 'injectors', 2),
+(8, 'Throttle Bodies', 'Cuerpos de Aceleración', 'throttle', 3),
+(8, 'Mass Air Flow Sensors', 'Sensores MAF', 'maf-sensors', 4),
+(8, 'Air Intake', 'Admisión de Aire', 'air-intake', 5),
+-- Heat & AC (9)
+(9, 'AC Compressors', 'Compresores de AC', 'ac-compressors', 1),
+(9, 'AC Condensers', 'Condensadores de AC', 'ac-condensers', 2),
+(9, 'Heater Cores', 'Radiadores de Calefacción', 'heater-cores', 3),
+(9, 'Blower Motors', 'Motores de Soplador', 'blower-motors', 4),
+-- Steering (10)
+(10, 'Power Steering Pumps', 'Bombas de Dirección', 'ps-pumps', 1),
+(10, 'Steering Racks', 'Cajas de Dirección', 'steering-racks', 2),
+(10, 'Tie Rods', 'Terminales de Dirección', 'tie-rods', 3),
+(10, 'Steering Columns', 'Columnas de Dirección', 'steering-columns', 4),
+-- Suspension (11)
+(11, 'Shocks & Struts', 'Amortiguadores y Puntales', 'shocks', 1),
+(11, 'Control Arms', 'Horquillas', 'control-arms', 2),
+(11, 'Ball Joints', 'Rótulas', 'ball-joints', 3),
+(11, 'Springs', 'Resortes', 'springs', 4),
+(11, 'Sway Bars', 'Barras Estabilizadoras', 'sway-bars', 5),
+(11, 'Bushings', 'Bujes', 'bushings', 6),
+-- Transmission (12)
+(12, 'Transmission Filters', 'Filtros de Transmisión', 'trans-filters', 1),
+(12, 'Clutch Kits', 'Kits de Clutch', 'clutch-kits', 2),
+(12, 'Transmission Mounts', 'Soportes de Transmisión', 'trans-mounts', 3),
+(12, 'Shift Cables', 'Chicotes de Velocidades', 'shift-cables', 4),
+(12, 'Torque Converters', 'Convertidores de Torque', 'torque-converters', 5)
+ON CONFLICT DO NOTHING;
+
+-- =====================================================
+-- VEHICLE BRANDS (common in Mexico)
+-- =====================================================
+
+INSERT INTO brands (name, country) VALUES
+('Toyota', 'Japan'),
+('Nissan', 'Japan'),
+('Honda', 'Japan'),
+('Mazda', 'Japan'),
+('Mitsubishi', 'Japan'),
+('Subaru', 'Japan'),
+('Suzuki', 'Japan'),
+('Ford', 'USA'),
+('Chevrolet', 'USA'),
+('Dodge', 'USA'),
+('Jeep', 'USA'),
+('Chrysler', 'USA'),
+('Volkswagen', 'Germany'),
+('BMW', 'Germany'),
+('Mercedes-Benz', 'Germany'),
+('Audi', 'Germany'),
+('Renault', 'France'),
+('Peugeot', 'France'),
+('Citroën', 'France'),
+('Kia', 'South Korea'),
+('Hyundai', 'South Korea'),
+('Seat', 'Spain'),
+('Fiat', 'Italy')
+ON CONFLICT DO NOTHING;
+
+-- =====================================================
+-- POPULAR MODELS (sample for top brands)
+-- =====================================================
+
+-- Note: brand_id is auto-assigned by SERIAL. We use subqueries to find them.
+-- This seed assumes brands were inserted in the order above.
+
+INSERT INTO models (brand_id, name, body_type, production_start_year, production_end_year) VALUES
+-- Toyota (id=1)
+((SELECT id FROM brands WHERE name='Toyota'), 'Corolla', 'sedan', 1966, NULL),
+((SELECT id FROM brands WHERE name='Toyota'), 'Camry', 'sedan', 1982, NULL),
+((SELECT id FROM brands WHERE name='Toyota'), 'RAV4', 'suv', 1994, NULL),
+((SELECT id FROM brands WHERE name='Toyota'), 'Hilux', 'truck', 1968, NULL),
+((SELECT id FROM brands WHERE name='Toyota'), 'Yaris', 'hatchback', 1999, NULL),
+((SELECT id FROM brands WHERE name='Toyota'), 'Avanza', 'van', 2003, NULL),
+-- Nissan (id=2)
+((SELECT id FROM brands WHERE name='Nissan'), 'Sentra', 'sedan', 1982, NULL),
+((SELECT id FROM brands WHERE name='Nissan'), 'Versa', 'sedan', 2006, NULL),
+((SELECT id FROM brands WHERE name='Nissan'), 'March', 'hatchback', 1982, NULL),
+((SELECT id FROM brands WHERE name='Nissan'), 'X-Trail', 'suv', 2000, NULL),
+((SELECT id FROM brands WHERE name='Nissan'), 'Frontier', 'truck', 1997, NULL),
+((SELECT id FROM brands WHERE name='Nissan'), 'NP300', 'truck', 2008, NULL),
+-- Honda (id=3)
+((SELECT id FROM brands WHERE name='Honda'), 'Civic', 'sedan', 1972, NULL),
+((SELECT id FROM brands WHERE name='Honda'), 'Accord', 'sedan', 1976, NULL),
+((SELECT id FROM brands WHERE name='Honda'), 'CR-V', 'suv', 1995, NULL),
+((SELECT id FROM brands WHERE name='Honda'), 'City', 'sedan', 1981, NULL),
+-- Ford (id=9)
+((SELECT id FROM brands WHERE name='Ford'), 'F-150', 'truck', 1975, NULL),
+((SELECT id FROM brands WHERE name='Ford'), 'Ranger', 'truck', 1982, NULL),
+((SELECT id FROM brands WHERE name='Ford'), 'Escape', 'suv', 2000, NULL),
+((SELECT id FROM brands WHERE name='Ford'), 'Focus', 'hatchback', 1998, NULL),
+-- Chevrolet (id=10)
+((SELECT id FROM brands WHERE name='Chevrolet'), 'Aveo', 'sedan', 2002, NULL),
+((SELECT id FROM brands WHERE name='Chevrolet'), 'Spark', 'hatchback', 1998, NULL),
+((SELECT id FROM brands WHERE name='Chevrolet'), 'Silverado', 'truck', 1998, NULL),
+((SELECT id FROM brands WHERE name='Chevrolet'), 'Trax', 'suv', 2013, NULL),
+-- Volkswagen (id=13)
+((SELECT id FROM brands WHERE name='Volkswagen'), 'Jetta', 'sedan', 1979, NULL),
+((SELECT id FROM brands WHERE name='Volkswagen'), 'Golf', 'hatchback', 1974, NULL),
+((SELECT id FROM brands WHERE name='Volkswagen'), 'Polo', 'hatchback', 1975, NULL),
+((SELECT id FROM brands WHERE name='Volkswagen'), 'Tiguan', 'suv', 2007, NULL),
+((SELECT id FROM brands WHERE name='Volkswagen'), 'Vento', 'sedan', 2010, NULL)
+ON CONFLICT DO NOTHING;
+
+-- =====================================================
+-- YEARS (2000-2026)
+-- =====================================================
+
+DO $$
+BEGIN
+    FOR yr IN 2000..2026 LOOP
+        INSERT INTO years (year) VALUES (yr) ON CONFLICT DO NOTHING;
+    END LOOP;
+END $$;