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/frontend/storefront/page-templates.md

@@ -1,8 +1,8 @@
-# Shop Frontend - Alpine.js/Jinja2 Page Template Guide
+# Storefront Frontend - Alpine.js/Jinja2 Page Template Guide
 
 ## 📋 Overview
 
-This guide provides complete templates for creating new customer-facing shop pages using the established Alpine.js + Jinja2 + Multi-Theme architecture. Follow these patterns to ensure consistency across all store shops while maintaining unique branding.
+This guide provides complete templates for creating new customer-facing storefront pages using the established Alpine.js + Jinja2 + Multi-Theme architecture. Follow these patterns to ensure consistency across all store storefronts while maintaining unique branding.
 
 ---
 
@@ -10,9 +10,9 @@ This guide provides complete templates for creating new customer-facing shop pag
 
 Three fully-implemented authentication pages are available for reference:
 
-- **Login** (`app/templates/shop/account/login.html`) - Customer sign-in with email/password
-- **Register** (`app/templates/shop/account/register.html`) - New customer account creation
-- **Forgot Password** (`app/templates/shop/account/forgot-password.html`) - Password reset flow
+- **Login** (`app/templates/storefront/account/login.html`) - Customer sign-in with email/password
+- **Register** (`app/templates/storefront/account/register.html`) - New customer account creation
+- **Forgot Password** (`app/templates/storefront/account/forgot-password.html`) - Password reset flow
 
 All authentication pages feature:
 - ✅ Tailwind CSS styling
@@ -24,7 +24,7 @@ All authentication pages feature:
 - ✅ Loading states
 - ✅ Error handling
 
-See the [Shop Architecture Documentation](./architecture.md) (Authentication Pages section) for complete details.
+See the [Storefront Architecture Documentation](./architecture.md) (Authentication Pages section) for complete details.
 
 ---
 
@@ -33,16 +33,16 @@ See the [Shop Architecture Documentation](./architecture.md) (Authentication Pag
 ### File Structure for New Page
 ```
 app/
-├── templates/shop/
+├── templates/storefront/
 │   └── [page-name].html          # Jinja2 template
-├── static/shop/js/
+├── static/storefront/js/
 │   └── [page-name].js            # Alpine.js component
-└── api/v1/shop/
+└── api/v1/storefront/
     └── pages.py                  # Route registration
 ```
 
 ### Checklist for New Page
-- [ ] Create Jinja2 template extending shop/base.html
+- [ ] Create Jinja2 template extending storefront/base.html
 - [ ] Create Alpine.js JavaScript component
 - [ ] Register route in pages.py
 - [ ] Test with multiple store themes
@@ -58,11 +58,11 @@ app/
 
 ### 1. Jinja2 Template
 
-**File:** `app/templates/shop/[page-name].html`
+**File:** `app/templates/storefront/[page-name].html`
 
 ```jinja2
-{# app/templates/shop/[page-name].html #}
-{% extends "shop/base.html" %}
+{# app/templates/storefront/[page-name].html #}
+{% extends "storefront/base.html" %}
 
 {# Page title for browser tab - includes store name #}
 {% block title %}[Page Name] - {{ store.name }}{% endblock %}
@@ -174,7 +174,7 @@ app/
 
                     <!-- Item Image -->
                     <div class="aspect-w-1 aspect-h-1 w-full overflow-hidden rounded-t-lg bg-gray-100 dark:bg-gray-700">
-                        <img :src="item.image || '/static/shop/img/placeholder-product.png'"
+                        <img :src="item.image || '/static/storefront/img/placeholder-product.png'"
                              :alt="item.name"
                              class="w-full h-full object-cover object-center hover:scale-105 transition-transform"
                              loading="lazy">
@@ -247,7 +247,7 @@ app/
 
 {# Page-specific JavaScript #}
 {% block extra_scripts %}
-<script src="{{ url_for('static', path='shop/js/[page-name].js') }}"></script>
+<script src="{{ url_for('static', path='storefront/js/[page-name].js') }}"></script>
 {% endblock %}
 ```
 
@@ -255,10 +255,10 @@ app/
 
 ### 2. Alpine.js Component
 
-**File:** `app/static/shop/js/[page-name].js`
+**File:** `app/static/storefront/js/[page-name].js`
 
 ```javascript
-// static/shop/js/[page-name].js
+// static/storefront/js/[page-name].js
 /**
  * [Page Name] Component
  * Handles [describe functionality]
@@ -333,7 +333,7 @@ function shop[PageName]() {
                 });
 
                 const response = await fetch(
-                    `/api/v1/shop/${this.storeCode}/items?${params}`
+                    `/api/v1/storefront/${this.storeCode}/items?${params}`
                 );
 
                 if (!response.ok) {
@@ -444,14 +444,14 @@ function shop[PageName]() {
         addToCart(item, quantity = 1) {
             pageLog.info('Adding to cart:', item.name);
 
-            // Get cart from shop layout
+            // Get cart from storefront layout
             const shopLayout = Alpine.store('shop') || window.storefrontLayoutData();
 
             if (shopLayout && typeof shopLayout.addToCart === 'function') {
                 shopLayout.addToCart(item, quantity);
                 this.showToast(`${item.name} added to cart`, 'success');
             } else {
-                pageLog.error('Shop layout not available');
+                pageLog.error('Storefront layout not available');
             }
         },
 
@@ -513,7 +513,7 @@ pageLog.info('[PageName] module loaded');
 
 ### 3. Route Registration
 
-**File:** `app/api/v1/shop/pages.py`
+**File:** `app/api/v1/storefront/pages.py`
 
 ```python
 from fastapi import APIRouter, Request, Depends
@@ -536,7 +536,7 @@ async def [page_name]_page(
     theme = request.state.theme
 
     return templates.TemplateResponse(
-        "shop/[page-name].html",
+        "storefront/[page-name].html",
         {
             "request": request,
             "store": store,
@@ -562,7 +562,7 @@ async loadProducts() {
     this.loading = true;
     try {
         const response = await fetch(
-            `/api/v1/shop/${this.storeCode}/products?category=${this.category}`
+            `/api/v1/storefront/${this.storeCode}/products?category=${this.category}`
         );
         const data = await response.json();
         this.products = data.products || [];
@@ -578,7 +578,7 @@ async loadProducts() {
 ```html
 <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-6">
     <template x-for="product in products" :key="product.id">
-        {% include 'shop/partials/product-card.html' %}
+        {% include 'storefront/partials/product-card.html' %}
     </template>
 </div>
 ```
@@ -598,7 +598,7 @@ async init() {
 
 async loadProduct(id) {
     const product = await fetch(
-        `/api/v1/shop/${this.storeCode}/products/${id}`
+        `/api/v1/storefront/${this.storeCode}/products/${id}`
     ).then(r => r.json());
 
     this.product = product;
@@ -713,7 +713,7 @@ async performSearch() {
     this.loading = true;
     try {
         const response = await fetch(
-            `/api/v1/shop/${this.storeCode}/search`,
+            `/api/v1/storefront/${this.storeCode}/search`,
             {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
@@ -750,10 +750,10 @@ Always use CSS variables for store colors:
 
 ### 2. Cart Integration
 
-Always use the shop layout's cart methods:
+Always use the storefront layout's cart methods:
 
 ```javascript
-// ✅ GOOD: Uses shop layout
+// ✅ GOOD: Uses storefront layout
 const shopLayout = window.storefrontLayoutData();
 shopLayout.addToCart(product, quantity);
 
@@ -881,7 +881,7 @@ Add proper ARIA labels and keyboard navigation:
 
 ### Reusable Partials
 
-Create reusable components in `templates/shop/partials/`:
+Create reusable components in `templates/storefront/partials/`:
 
 **product-card.html:**
 ```html
@@ -945,12 +945,12 @@ Create reusable components in `templates/shop/partials/`:
 
 ```bash
 # Create new page files
-touch app/templates/shop/new-page.html
-touch app/static/shop/js/new-page.js
+touch app/templates/storefront/new-page.html
+touch app/static/storefront/js/new-page.js
 
 # Copy templates
-cp template.html app/templates/shop/new-page.html
-cp template.js app/static/shop/js/new-page.js
+cp template.html app/templates/storefront/new-page.html
+cp template.js app/static/storefront/js/new-page.js
 
 # Update placeholders:
 # - Replace [page-name] with actual name
@@ -969,7 +969,7 @@ cp template.js app/static/shop/js/new-page.js
 - **Logo**: Available in both light and dark versions
 - **Custom CSS**: Store-specific styles automatically injected
 
-### Shop Layout Functions
+### Storefront Layout Functions
 - `addToCart(product, quantity)`: Add item to cart
 - `showToast(message, type)`: Show notification
 - `formatPrice(amount)`: Format as currency
@@ -991,4 +991,4 @@ await apiClient.post('/endpoint', { data });
 
 ---
 
-This template provides a complete, theme-aware pattern for building shop pages with consistent structure, store branding, cart integration, and excellent user experience across all devices.
+This template provides a complete, theme-aware pattern for building storefront pages with consistent structure, store branding, cart integration, and excellent user experience across all devices.