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/middleware.md

@@ -8,7 +8,7 @@ The application uses a custom middleware stack that processes **every request**
 - REST API calls (`/api/*`)
 - Admin interface pages (`/admin/*`)
 - Store dashboard pages (`/store/*`)
-- Shop pages (`/shop/*` or custom domains)
+- Storefront pages (`/storefront/*` or custom domains)
 
 This middleware layer is **system-wide** and enables the multi-tenant architecture to function seamlessly.
 
@@ -89,7 +89,7 @@ INFO Response: 200 for GET /admin/dashboard (0.143s)
 
 ### 2. Store Context Middleware
 
-**Purpose**: Detect which store's shop the request is for (multi-tenant core)
+**Purpose**: Detect which store's storefront the request is for (multi-tenant core)
 
 **What it does**:
 - Detects store from:
@@ -103,7 +103,7 @@ INFO Response: 200 for GET /admin/dashboard (0.143s)
 
 **Example**:
 ```
-Request: https://orion.platform.com/shop/products
+Request: https://orion.platform.com/storefront/products
 ↓
 Middleware detects: store_code = "orion"
 ↓
@@ -111,14 +111,14 @@ Queries database: SELECT * FROM stores WHERE code = 'orion'
 ↓
 Injects: request.state.store = <Store object>
         request.state.store_id = 1
-        request.state.clean_path = "/shop/products"
+        request.state.clean_path = "/storefront/products"
 ```
 
 **Why it's critical**: Without this, the system wouldn't know which store's data to show
 
 **See**: [Multi-Tenant System](multi-tenant.md) for routing modes
 
-**Note on Path-Based Routing:** Previous implementations used a `PathRewriteMiddleware` to rewrite paths at runtime. This has been replaced with **double router mounting** in `main.py`, where shop routes are registered twice with different prefixes (`/shop` and `/stores/{store_code}/shop`). This approach is simpler and uses FastAPI's native routing capabilities.
+**Note on Path-Based Routing:** Previous implementations used a `PathRewriteMiddleware` to rewrite paths at runtime. This has been replaced with **double router mounting** in `main.py`, where storefront routes are registered twice with different prefixes (`/storefront` and `/stores/{store_code}/storefront`). This approach is simpler and uses FastAPI's native routing capabilities.
 
 ### 3. Frontend Type Detection Middleware
 
@@ -139,7 +139,7 @@ Injects: request.state.store = <Store object>
 2. Path-based detection:
    - /admin/* or /api/v1/admin/*            → ADMIN
    - /store/* or /api/v1/store/*          → STORE
-   - /storefront/*, /shop/*, /stores/*     → STOREFRONT
+   - /storefront/*, /stores/*               → STOREFRONT
    - /api/v1/platform/*                     → PLATFORM
 3. Store subdomain (orion.omsflow.lu)       → STOREFRONT
 4. Store context set by middleware         → STOREFRONT
@@ -171,7 +171,7 @@ Injects: request.state.store = <Store object>
 }
 ```
 
-**Why it's needed**: Each store shop can have custom branding
+**Why it's needed**: Each store storefront can have custom branding
 
 ## Naming Conventions
 
@@ -311,7 +311,7 @@ graph TD
 
 **Breaking this order will break the application!**
 
-**Note:** Path-based routing (e.g., `/stores/{code}/shop/*`) is handled by double router mounting in `main.py`, not by middleware. Platform path-based routing (e.g., `/platforms/oms/`) IS handled by PlatformContextMiddleware which rewrites the path.
+**Note:** Path-based routing (e.g., `/stores/{code}/storefront/*`) is handled by double router mounting in `main.py`, not by middleware. Platform path-based routing (e.g., `/platforms/oms/`) IS handled by PlatformContextMiddleware which rewrites the path.
 
 ## Request State Variables
 
@@ -332,7 +332,7 @@ Middleware components inject these variables into `request.state`:
 ```python
 from fastapi import Request
 
-@app.get("/shop/products")
+@app.get("/storefront/products")
 async def get_products(request: Request):
     # Access store
     store = request.state.store
@@ -374,26 +374,26 @@ async def get_products(request: Request):
 
 ## Request Flow Example
 
-### Example: Shop Product Page Request
+### Example: Storefront Product Page Request
 
-**URL**: `https://orion.myplatform.com/shop/products`
+**URL**: `https://orion.myplatform.com/storefront/products`
 
 **Middleware Processing**:
 
 ```
 1. LoggingMiddleware
    ↓ Starts timer
-   ↓ Logs: "Request: GET /shop/products from 192.168.1.100"
+   ↓ Logs: "Request: GET /storefront/products from 192.168.1.100"
 
 2. StoreContextMiddleware
    ↓ Detects subdomain: "orion"
    ↓ Queries DB: store = get_store_by_code("orion")
    ↓ Sets: request.state.store = <Store: Orion>
    ↓ Sets: request.state.store_id = 1
-   ↓ Sets: request.state.clean_path = "/shop/products"
+   ↓ Sets: request.state.clean_path = "/storefront/products"
 
 3. FrontendTypeMiddleware
-   ↓ Uses FrontendDetector with path: "/shop/products"
+   ↓ Uses FrontendDetector with path: "/storefront/products"
    ↓ Has store context: Yes
    ↓ Detects storefront frontend
    ↓ Sets: request.state.frontend_type = FrontendType.STOREFRONT
@@ -403,7 +403,7 @@ async def get_products(request: Request):
    ↓ Sets: request.state.theme = {...theme config...}
 
 5. FastAPI Router
-   ↓ Matches route: @app.get("/shop/products")
+   ↓ Matches route: @app.get("/storefront/products")
    ↓ Calls handler function
 
 6. Route Handler
@@ -415,7 +415,7 @@ async def get_products(request: Request):
    ↓ Returns HTML with store theme
 
 9. LoggingMiddleware (response phase)
-   ↓ Logs: "Response: 200 for GET /shop/products (0.143s)"
+   ↓ Logs: "Response: 200 for GET /storefront/products (0.143s)"
    ↓ Adds header: X-Process-Time: 0.143
 ```
 
@@ -510,9 +510,9 @@ def test_store_detection_subdomain():
 Test the full middleware stack:
 
 ```python
-def test_shop_request_flow(client):
+def test_storefront_request_flow(client):
     response = client.get(
-        "/shop/products",
+        "/storefront/products",
         headers={"Host": "orion.platform.com"}
     )