diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ed7b267
--- /dev/null
+++ b/README.md
@@ -0,0 +1,171 @@
+# 🧨 Ballistic Admin UI  
+### Internal Tools for the Builder Ecosystem
+
+The Ballistic Admin UI is the control board behind the Builder.  
+It’s where feeds get shaped, categories get normalized, and the catalog stays sharp.
+
+This is an internal tool built for speed, clarity, and capability.
+
+---
+
+# 🚀 What This Admin UI Does
+
+## Merchant Feeds  
+Path: `/gunbuilder/admin/merchants`
+
+A clean dashboard for all merchants feeding the system.
+
+- View and edit feed URLs  
+- Monitor activity and sync timestamps  
+- Trigger:
+  - Full Imports — pull and process a complete catalog  
+  - Offers-Only Syncs — refresh price and stock without re-ingesting products
+
+Purpose: keep the catalog alive, current, and trustworthy.
+
+---
+
+## Category Mapping  
+Path: `/gunbuilder/admin/category-mapping`
+
+This is where raw merchant chaos gets cleaned up.
+
+- See every unique category discovered during import  
+- Filter by merchant or unmapped categories  
+- Assign internal standards:
+  - Part Role (LOWER_RECEIVER, BARREL, etc.)
+  - Configuration (STRIPPED, COMPLETE, KIT)
+
+Once mapped, future imports classify parts automatically.
+
+---
+
+## Builder Integration
+
+The admin UI powers the consumer-facing Builder at `/gunbuilder`.
+
+Today:
+- Load compatible parts  
+- Assemble full builds  
+- Pull lowest prices across merchants  
+
+Tomorrow:
+- Full compatibility engine  
+- Price history  
+- Build exports / public build pages  
+- Merchant health monitoring  
+- Deal surfacing and anomaly detection  
+
+---
+
+# 🧱 Tech Stack
+
+- Next.js (App Router)  
+- TypeScript  
+- TailwindCSS  
+- Fetch API client  
+- Spring Boot backend
+
+---
+
+# 🔧 Local Development
+
+## Install Dependencies
+npm install  
+yarn install  
+pnpm install  
+
+## Environment Variables
+
+Create `.env.local`:
+
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8080  
+NEXT_PUBLIC_ADMIN_BASE_PATH=/gunbuilder/admin  
+
+## Start Dev Server
+npm run dev  
+
+Then visit:  
+http://localhost:3000/gunbuilder/admin
+
+---
+
+# 🌐 Backend Requirements (CORS)
+
+Your Spring Boot backend must allow:
+
+Origin: http://localhost:3000
+
+If CORS fails, the admin cannot communicate with the API.
+
+---
+
+# 🧭 Project Structure
+
+app/  
+  gunbuilder/  
+    admin/  
+      merchants/  
+      category-mapping/  
+components/  
+  admin/  
+lib/  
+  api/  
+
+---
+
+# 📘 Admin API
+
+Full API reference lives in:  
+docs/BALLISTIC_ADMIN_API.md
+
+Covers:
+- Merchant endpoints  
+- Import triggers  
+- Offers-only sync  
+- Category mapping  
+
+---
+
+# 🧪 Working With Imports
+
+1. Open Merchant Admin  
+2. Update feed URLs  
+3. Run Full Import  
+4. Go to Category Mapping  
+5. Filter → Only Unmapped  
+6. Map the new categories  
+7. Re-run import to verify  
+
+---
+
+# 🔒 Security
+
+Local: no auth, unrestricted.  
+Production: lock everything down.
+
+Admin tools should never be publicly exposed.
+
+---
+
+# 🛣 Roadmap
+
+- Product browser  
+- Offer browser  
+- Merchant health checks  
+- Compatibility intelligence  
+- Price tracking  
+- Build sharing  
+- Category heuristics  
+- Deal surfacing  
+
+---
+
+# 🤝 Contributing
+
+- Use feature branches  
+- Keep backend calls in `lib/api`  
+- Update docs when adding endpoints  
+- Test everything with the live backend  
+
+---
\ No newline at end of file