diff --git a/ai-context.md b/ai-context.md
index e69de29..b0833d4 100644
--- a/ai-context.md
+++ b/ai-context.md
@@ -0,0 +1,195 @@
+# 🤖 Battl Builder — AI Context & Guardrails
+
+> **Purpose:**  
+> This document provides persistent context for AI assistants working on the **Battl Builder** project.  
+> It defines the product vision, architecture, constraints, and expectations so AI outputs remain aligned, safe, and useful.
+
+---
+
+## 1. Project Overview
+
+**Battl Builder** is a PCPartPicker-style platform for firearms, starting with the **AR-15 ecosystem**.
+
+Users can:
+- Browse firearm parts by role (upper, lower, barrel, etc.)
+- Compare prices across multiple merchants
+- Assemble builds using a visual Builder UI
+- Share builds publicly
+
+Battl Builder:
+- **Does not sell products**
+- **Does not process payments**
+- Is **affiliate-driven** (AvantLink)
+- Focuses on **clarity, accuracy, and trust**
+
+Think: *“Build smarter rifles, not spreadsheets.”*
+
+---
+
+## 2. Product Philosophy
+
+### Core Principles
+- **Accuracy > Completeness**
+- **Idempotency > Speed**
+- **Explicit data > heuristics**
+- **Long-term maintainability > cleverness**
+
+### Non-Goals
+AI should NOT assume this project is:
+- An e-commerce checkout platform
+- A firearm marketplace
+- A forum-first community
+- A content or media brand (for now)
+
+Avoid suggestions that introduce:
+- Real-time inventory guarantees
+- Payment processing
+- Legal/compliance risk
+- Over-engineered abstractions
+
+---
+
+## 3. Current State (Beta)
+
+### What Exists
+- User authentication
+- Functional Builder UI
+- Dedicated part pages
+- Basic builds community
+- 2 merchants (AvantLink)
+- Production Spring Boot backend
+
+### What’s Intentionally Light
+- Compatibility logic (rule-based, evolving)
+- Social features
+- Price history & analytics
+- Public build discovery
+
+This is a **real beta**, not a mock project.
+
+---
+
+## 4. Backend Architecture
+
+### Tech Stack
+- **Java 17**
+- **Spring Boot 3.x**
+- **PostgreSQL**
+- **Hibernate / JPA**
+- **Maven**
+- **REST APIs**
+- **Docker (local + infra)**
+
+### Core Responsibilities
+- Merchant feed ingestion (CSV / TSV)
+- Product normalization & deduplication
+- Offer upserts (price, stock, URLs)
+- Category → Part Role mapping
+- Platform inference (AR-15 today)
+- Supplying clean data to the Builder UI
+
+---
+
+## 5. Import Pipeline (Critical Context)
+
+The import system is the **heart of the platform**.
+
+### Key Characteristics
+- Idempotent by design
+- Safe to re-run repeatedly
+- Handles dirty, malformed feeds
+- Never duplicates products or offers
+
+### Import Modes
+- **Full Import:** products + offers
+- **Offer-Only Sync:** price/stock refresh
+
+### Deduplication Rules
+- Products deduped by **Brand + MPN** (UPC fallback later)
+- Offers are **merchant-specific**
+- Offers track:
+    - `firstSeenAt`
+    - `lastSeenAt`
+
+⚠️ **Never introduce logic that breaks idempotency.**  
+⚠️ **Never assume merchant data is clean or complete.**
+
+---
+
+## 6. Frontend Expectations
+
+- Next.js / React
+- Backend owns business logic
+- Frontend consumes normalized APIs
+- No hardcoded compatibility rules
+- No duplication of backend logic
+
+The Builder UI assumes:
+- Part roles are authoritative
+- Compatibility is backend-driven
+- Data is already normalized
+
+---
+
+## 7. Infrastructure & Dev Environment
+
+- PostgreSQL (Docker or local)
+- Spring Boot runs on `:8080`
+- CI builds on push / PR
+- Local dev favors simplicity over cleverness
+
+---
+
+## 8. Constraints You Must Respect
+
+AI suggestions must account for:
+- Small team
+- Incremental delivery
+- Clear migration paths
+- Code readability 6–12 months out
+
+Avoid:
+- “Rewrite everything” answers
+- Premature abstractions
+- Magical inference engines
+- Hidden or implicit behavior
+
+---
+
+## 9. How AI Should Respond
+
+When assisting on this project:
+
+- **Feature requests** → propose phased, minimal solutions
+- **Refactors** → explain tradeoffs and migration steps
+- **Debugging** → reason from architecture first
+- **Design** → follow PCPartPicker mental models
+- **Scaling** → assume success, move incrementally
+
+If something is unclear:
+- Ask **one focused question**
+- Otherwise state assumptions and proceed
+
+---
+
+## 10. Mental Model Summary
+
+Battl Builder is:
+
+- A **builder, not a store**
+- A **data normalization engine disguised as a UI**
+- Opinionated where it matters
+- Flexible where it counts
+- Built for **credibility and longevity**
+
+AI assistance should help the project grow **cleanly, safely, and intelligently**.
+
+---
+
+### ✅ Recommended Usage
+Paste this file into:
+- Cursor / Copilot project context
+- ChatGPT system prompt
+- Claude project memory
+- `/docs/ai-context.md`
+- 
\ No newline at end of file