docs: add consolidated dev URL reference and migrate /shop to /storefront

- Add Development URL Quick Reference section to url-routing overview
  with all login URLs, entry points, and full examples
- Replace /shop/ path segments with /storefront/ across 50 docs files
- Update file references: shop_pages.py → storefront_pages.py,
  templates/shop/ → templates/storefront/, api/v1/shop/ → api/v1/storefront/
- Preserve domain references (orion.shop) and /store/ staff dashboard paths
- Archive docs left unchanged (historical)

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

docs/architecture/api-consolidation-proposal.md

@@ -6,9 +6,9 @@
 
 ## Executive Summary
 
-The platform currently has **two parallel API structures** for shop/customer-facing endpoints:
+The platform currently has **two parallel API structures** for storefront/customer-facing endpoints:
 1. **Original:** `/api/v1/platform/stores/{store_id}/*`
-2. **New:** `/api/v1/shop/*`
+2. **New:** `/api/v1/storefront/*`
 
 This divergence creates confusion, maintenance overhead, and potential bugs. This document analyzes the situation and proposes a consolidation strategy.
 
@@ -47,26 +47,26 @@ POST /api/v1/platform/stores/auth/register        → Customer registration
 
 ---
 
-### 2. New Architecture (`/api/v1/shop/`)
+### 2. New Architecture (`/api/v1/storefront/`)
 
-**Location:** `app/api/v1/shop/`
+**Location:** `app/api/v1/storefront/`
 
 **Endpoints:**
 ```
-GET /api/v1/shop/content-pages/navigation        → CMS navigation pages
-GET /api/v1/shop/content-pages/{slug}            → CMS page content
+GET /api/v1/storefront/content-pages/navigation        → CMS navigation pages
+GET /api/v1/storefront/content-pages/{slug}            → CMS page content
 ```
 
 **Characteristics:**
 - ✅ **Store-agnostic URLs:** Clean paths without store_id
 - ✅ **Middleware-driven:** Relies on `StoreContextMiddleware` to inject store
-- ✅ **Simpler URLs:** `/api/v1/shop/products` vs `/api/v1/platform/stores/123/products`
+- ✅ **Simpler URLs:** `/api/v1/storefront/products` vs `/api/v1/platform/stores/123/products`
 - ❌ **Incomplete:** Only CMS endpoints implemented
 - ❌ **Divergent:** Not consistent with existing public API
 
 **Current Usage:**
 - CMS content pages only
-- Called from shop templates (e.g., `shop/products.html`, `shop/home.html`)
+- Called from storefront templates (e.g., `storefront/products.html`, `storefront/home.html`)
 
 ---
 
@@ -77,7 +77,7 @@ GET /api/v1/shop/content-pages/{slug}            → CMS page content
 ```javascript
 // ❌ INCONSISTENT - Two different patterns for same context
 // CMS pages use new pattern
-fetch('/api/v1/shop/content-pages/about')
+fetch('/api/v1/storefront/content-pages/about')
 
 // Products use old pattern
 fetch('/api/v1/platform/stores/123/products')
@@ -86,7 +86,7 @@ fetch('/api/v1/platform/stores/123/products')
 ### Confusion
 
 Developers must remember:
-- "Is this endpoint under `/shop` or `/public/stores`?"
+- "Is this endpoint under `/storefront` or `/public/stores`?"
 - "Do I need to pass store_id or is it from middleware?"
 - "Which authentication endpoints do I use?"
 
@@ -102,7 +102,7 @@ Developers must remember:
 **Current Issue:** CMS pages not loading at `/stores/orion/about`
 
 **Root Cause:**
-- CMS API exists at `/api/v1/shop/content-pages/{slug}`
+- CMS API exists at `/api/v1/storefront/content-pages/{slug}`
 - No corresponding HTML route handler in `store_pages.py`
 - JavaScript might be calling wrong endpoint
 
@@ -110,13 +110,13 @@ Developers must remember:
 
 ## Options Analysis
 
-### Option 1: Move Everything to `/api/v1/shop/*` (Middleware-Driven)
+### Option 1: Move Everything to `/api/v1/storefront/*` (Middleware-Driven)
 
-**Approach:** Consolidate all customer-facing endpoints under `/api/v1/shop/*`
+**Approach:** Consolidate all customer-facing endpoints under `/api/v1/storefront/*`
 
 **Proposed Structure:**
 ```
-/api/v1/shop/
+/api/v1/storefront/
   ├── auth/
   │   ├── POST /login             → Customer login
   │   ├── POST /register          → Customer registration
@@ -143,7 +143,7 @@ Developers must remember:
 **Implementation:**
 - Store extracted by `StoreContextMiddleware` from request
 - All endpoints use `request.state.store` instead of path parameter
-- URLs are cleaner: `/api/v1/shop/products` instead of `/api/v1/platform/stores/123/products`
+- URLs are cleaner: `/api/v1/storefront/products` instead of `/api/v1/platform/stores/123/products`
 
 **Pros:**
 - ✅ Clean, consistent API structure
@@ -162,17 +162,17 @@ Developers must remember:
 
 ---
 
-### Option 2: Keep `/api/v1/platform/stores/*` and Deprecate `/api/v1/shop/*`
+### Option 2: Keep `/api/v1/platform/stores/*` and Deprecate `/api/v1/storefront/*`
 
 **Approach:** Move CMS endpoints to `/api/v1/platform/stores/{store_id}/content-pages/*`
 
 **Proposed Changes:**
 ```
 # Move CMS endpoints
-FROM: /api/v1/shop/content-pages/navigation
+FROM: /api/v1/storefront/content-pages/navigation
 TO:   /api/v1/platform/stores/{store_id}/content-pages/navigation
 
-FROM: /api/v1/shop/content-pages/{slug}
+FROM: /api/v1/storefront/content-pages/{slug}
 TO:   /api/v1/platform/stores/{store_id}/content-pages/{slug}
 ```
 
@@ -228,7 +228,7 @@ async def get_products_legacy(store_id: int, db: Session = Depends(get_db)):
 
 ## Recommendation
 
-### **OPTION 1: Consolidate to `/api/v1/shop/*` (Middleware-Driven)**
+### **OPTION 1: Consolidate to `/api/v1/storefront/*` (Middleware-Driven)**
 
 **Rationale:**
 
@@ -237,7 +237,7 @@ async def get_products_legacy(store_id: int, db: Session = Depends(get_db)):
 2. **User Experience**: Cleaner URLs are easier for frontend developers:
    ```javascript
    // ✅ GOOD
-   fetch('/api/v1/shop/products')
+   fetch('/api/v1/storefront/products')
 
    // ❌ BAD
    fetch('/api/v1/platform/stores/123/products')
@@ -245,7 +245,7 @@ async def get_products_legacy(store_id: int, db: Session = Depends(get_db)):
 
 3. **Multi-Tenant Best Practice**: Store context should be implicit (from domain/path), not explicit in every API call.
 
-4. **Consistency**: All shop endpoints follow same pattern - no mixing `/shop` and `/public/stores`.
+4. **Consistency**: All storefront endpoints follow same pattern - no mixing `/storefront` and `/public/stores`.
 
 5. **Future-Proof**: Easier to add new shop features without worrying about store_id paths.
 
@@ -258,7 +258,7 @@ async def get_products_legacy(store_id: int, db: Session = Depends(get_db)):
 **Day 1-2: Move Products**
 ```bash
 # Copy and adapt
-app/api/v1/platform/stores/products.py  →  app/api/v1/shop/products.py
+app/api/v1/platform/stores/products.py  →  app/api/v1/storefront/products.py
 
 # Changes:
 - Remove store_id path parameter
@@ -268,24 +268,24 @@ app/api/v1/platform/stores/products.py  →  app/api/v1/shop/products.py
 
 **Day 3: Move Cart**
 ```bash
-app/api/v1/platform/stores/cart.py  →  app/api/v1/shop/cart.py
+app/api/v1/platform/stores/cart.py  →  app/api/v1/storefront/cart.py
 ```
 
 **Day 4: Move Orders**
 ```bash
-app/api/v1/platform/stores/orders.py  →  app/api/v1/shop/orders.py
+app/api/v1/platform/stores/orders.py  →  app/api/v1/storefront/orders.py
 ```
 
 **Day 5: Move Auth**
 ```bash
-app/api/v1/platform/stores/auth.py  →  app/api/v1/shop/auth.py
+app/api/v1/platform/stores/auth.py  →  app/api/v1/storefront/auth.py
 ```
 
 ### Phase 2: Update Frontend (Week 1)
 
 **Templates:**
 - Update all `fetch()` calls in shop templates
-- Change from `/api/v1/platform/stores/${storeId}/...` to `/api/v1/shop/...`
+- Change from `/api/v1/platform/stores/${storeId}/...` to `/api/v1/storefront/...`
 
 **JavaScript:**
 - Update any shop-related API client code
@@ -335,10 +335,10 @@ const storeId = 123;
 fetch(`/api/v1/platform/stores/${storeId}/products`)
 ```
 
-### After (Proposed - `/api/v1/shop`)
+### After (Proposed - `/api/v1/storefront`)
 
 ```python
-# app/api/v1/shop/products.py
+# app/api/v1/storefront/products.py
 @router.get("/products")
 def get_product_catalog(
     request: Request,
@@ -350,7 +350,7 @@ def get_product_catalog(
 
 ```javascript
 // Frontend
-fetch('/api/v1/shop/products')  // Store context automatic
+fetch('/api/v1/storefront/products')  // Store context automatic
 ```
 
 ---
@@ -382,7 +382,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
 ### Quick Fix: Just Move CMS to Public API
 
 ```python
-# Move: app/api/v1/shop/content_pages.py
+# Move: app/api/v1/storefront/content_pages.py
 # To:   app/api/v1/platform/stores/content_pages.py
 
 # Update routes:
@@ -401,7 +401,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
 **Question for Team:**
 
 Should we:
-1. ✅ **Consolidate to `/api/v1/shop/*`** (Recommended)
+1. ✅ **Consolidate to `/api/v1/storefront/*`** (Recommended)
 2. ❌ **Keep `/api/v1/platform/stores/*`** and move CMS there
 3. ❌ **Hybrid approach** with both patterns
 4. ❌ **Quick fix only** - move CMS, address later
@@ -422,15 +422,15 @@ Should we:
 - 🚧 `search.py` - Stub
 - 🚧 `shop.py` - Stub
 
-### `/api/v1/shop/*`
+### `/api/v1/storefront/*`
 - ✅ `content_pages.py` - CMS pages
 
 ### To Be Created (if Option 1 chosen)
-- 📝 `shop/products.py`
-- 📝 `shop/cart.py`
-- 📝 `shop/orders.py`
-- 📝 `shop/auth.py`
-- 📝 `shop/stores.py` (marketplace listing)
+- 📝 `storefront/products.py`
+- 📝 `storefront/cart.py`
+- 📝 `storefront/orders.py`
+- 📝 `storefront/auth.py`
+- 📝 `storefront/stores.py` (marketplace listing)
 
 ---