# STLW Website - Admin Manual

## Quick Reference Guide

### 1. AGE GATE (index.html)
**Location:** Root page - visitors enter here

- **Submit DOB:** Click "Continue" button OR press **Enter** on keyboard
- **Failed verification:** Redirects to Calgary Zoo (your humor surprise!)

---

### 2. INTRO VIDEO
**Location:** Plays automatically after age gate passes

- **Autoplay:** Video starts muted for browser compatibility
- **Sound:** Unmutes automatically after 1 second
- **Transition:** When video ends → automatically redirects to courtyard

---

### 3. COURTYARD (courtyarddoors.html)
**Location:** `/Courtyard/courtyarddoors.html`

#### Admin Features:
- **High Contrast Doors:** Press **Ctrl+Shift+D** to reveal admin button
- **Admin button:** Shows/hides colored door overlays
  - Useful for testing or when you want a clean view

#### Door 1 Setup:
- Currently linked to: `../Dungeons/dungeon001/dungeon.html`
- Rest of doors (2-56) should link to their `dungeon.html` pages

---

### 4. DUNGEON TEMPLATE (dungeon.html)
**Location:** `/Dungeons/dungeon001/dungeon.html`
**This is your TEMPLATE** - replicate structure for dungeons 002-056

#### How shields are generated:
- Shields are auto-generated from `Completed Pages/products-clean.json`
- A product appears in a dungeon when its `door_id` matches that dungeon
  - Example: `"door_id": "door005"` puts the product in dungeon 5
  - `door_id` can be a string or an array that includes `"door005"`

#### Visual Elements:
- **Shields:** Golden, glowing shields generated by code
- **Hover:** Image + title + price fade in
- **Click:** Shield opens the product page

#### Styling Files:
- `dungeon.css` - Background and layout styling
- `assets/js/generate-shields.js` - Shield rendering and hover UI

---

## WORKFLOW: Creating a New Dungeon

1. **Copy dungeon001 folder** → rename to `dungeon002`
2. **Set the background** in `dungeon.css` for the new dungeon
3. **Assign products** by editing `Completed Pages/products-clean.json`:
  - Add or update `door_id` to match the dungeon (e.g., `"door002"`)
4. **Add to courtyard:** In `courtyarddoors.html`, update door 2:
  ```html
  <a href="../Dungeons/dungeon002/dungeon.html" class="door door-2"></a>
  ```
5. Repeat for dungeons 003-056

---

## FILES REFERENCE

**Root Pages:**
- `index.html` - Age gate + intro video

**Courtyard:**
- `Courtyard/courtyarddoors.html` - Door selection screen
- `Courtyard/courtyard.css` - Door styling
- `Courtyard/courtyard.js` - Door logic + admin mode

**Dungeons (Template: dungeon001):**
- `Dungeons/dungeon001/dungeon.html` - Main dungeon page
- `Dungeons/dungeon001/dungeon.css` - Background and layout styling
- `assets/js/generate-shields.js` - Shield generation and hover UI
- `Dungeons/dungeon001/bg007.jpg` - Backdrop image

**Products:**
- `Completed Pages/products-clean.json` - Product database
- `Completed Pages/catalog.html` - Product catalog page
- `Completed Pages/product-page.html` - Individual product view
- `Completed Pages/cart.html` - Shopping cart
- `Completed Pages/checkout.html` - Stripe checkout
- `Completed Pages/checkout-success.html` - Checkout success
- `Completed Pages/checkout-cancel.html` - Checkout cancel
- `Completed Pages/wholesale-admin.html` - Wholesale/discount admin
- `Completed Pages/customers-admin.html` - Customer discount list

**Assets:**
- `assets/video/intro001.mp4` - Intro video
- `assets/js/agegate.js` - Age gate logic
- `assets/js/script.js` - Additional scripts
- `assets/css/style.css` - Main styling
- `assets/js/cart.js` - Cart logic
- `assets/css/cart.css` - Cart styling

**Stripe Server:**
- `squareup-server/server.js` - Square backend (embedded checkout)
- `squareup-server/.env` - Square secrets (local only)
- `squareup-server/data/customers.json` - Customer database

---

## KEYBOARD SHORTCUTS

| Action | Keys | Where |
|--------|------|-------|
| Submit age | **Enter** | Age gate |
| Reveal admin controls | **Ctrl+Shift+D** | Courtyard |
| Reveal admin controls | **Ctrl+Shift+D** | Dungeons |
| High Contrast Doors | Click button | Courtyard (admin only) |
| Toggle shields | Click button | Dungeons (admin only) |

---

## COMMON TASKS

### Change Dungeon Title
The title is now product-driven; use the product title in `products-clean.json`.

### Change Dungeon Background
In `dungeon.css`, update the `background-image` for `.dungeon-room`.

### Hide a Shield
Remove the product’s `door_id` (or remove the matching dungeon entry) in `products-clean.json`.

### Show a Shield
Add the dungeon’s `door_id` to the product in `products-clean.json`.

### Change Shield Product Link
Shield links are automatic. The product page is determined by each product’s `id` in `products-clean.json`.

### Adjust Footer Link Size
In `assets/css/style.css` (currently 40px):
```css
.stl-footer-nav a {
  font-size: 40px;  // Change this number
}
```

### Upload Categories CSV
In `Completed Pages/admin-editor.html`:
1. Use the CSV uploader (headers: `id,categories`)
2. Click **Preview CSV** then **Apply Categories**
3. Click **Save to File** (or enable Auto-save)

### Manage Customer Discounts
In `Completed Pages/customers-admin.html`:
1. Enter **ADMIN_TOKEN**
2. Load customers and set **Wholesale** or **Discount %**
3. Click **Save Updates**

---

## NOTES

- **Shields are clickable** - Each shield links to its product page
- **Medieval shields** - Styled with leather texture, hover effects, golden glow
- **Auto-generation** - Shield count changes based on products assigned to the dungeon
- **Responsive grid** - Shields adapt to screen size (4 columns on desktop, fewer on mobile)

---

## TROUBLESHOOTING

**Video not playing?**
- Clear browser cache (Ctrl+Shift+Delete)
- Check `assets/video/intro001.mp4` exists
- Try hard refresh (Ctrl+F5)

**Shields not showing?**
- Ensure products have the correct `door_id` for that dungeon (e.g., `door005`)
- Verify `assets/js/generate-shields.js` is linked in the dungeon page
- Check browser console (F12) for JSON load errors

**Door links not working?**
- Verify path in href (check folder case: `Dungeons` not `dungeons`)
- Test in different browser

**Admin toggle not appearing?**
- Press **Ctrl+Shift+D** to reveal
- Check JavaScript console for errors

---

## PRODUCT PRICE COMPARISON FEATURE

### Overview
Optional competitive pricing display on product pages. Only appears when price comparison data is added to a product.

### How It Works
When viewing a product page, if price comparison data exists, a "📊 Price Comparison" section appears below the product description showing:
- STLW price (highlighted in green)
- Competitor prices with currency (USD/CAD)
- Product comparison notes
- Links to competitor products
- Verification dates
- "Why Choose STLW?" advantages section

### Adding Price Comparison Data

**In products-clean.json**, add this field to any product:

```json
{
  "id": "leather-harness",
  "title": "Master Harness",
  "price": "49.99",
  "priceComparison": {
    "competitors": [
      {
        "name": "Mr. S Leather",
        "price": "69.99",
        "currency": "USD",
        "url": "https://www.mr-s-leather.com/product-page",
        "notes": "Standard sizes only",
        "verified": "2026-01"
      },
      {
        "name": "Northbound Leather",
        "price": "64.95",
        "currency": "CAD",
        "url": "https://www.northbound.ca/product",
        "notes": "Standard sizes, machine-stitched",
        "verified": "2026-01"
      }
    ],
    "advantages": [
      "Custom-sized to your measurements",
      "Hand-stitched with bonded nylon thread",
      "Made in Canada with top-grain leather"
    ]
  }
}
```

### Field Definitions

**priceComparison** (object, optional)
- If this field doesn't exist, no comparison section shows

**competitors** (array, required if priceComparison exists)
- List of competitor products to compare

**Each competitor object:**
- `name` (string, required): Company name
- `price` (string, required): Their price (numbers only)
- `currency` (string, optional): "USD" or "CAD" (defaults to USD)
- `url` (string, optional): Link to their product page
- `notes` (string, optional): Size info, quality notes, etc.
- `verified` (string, optional): Date you checked (format: "2026-01")

**advantages** (array, optional)
- List of reasons why STLW is better
- Shows in green "Why Choose STLW?" box
- Focus on unique value: custom sizing, hand-made, quality

### Best Practices

**DO:**
- Update verification dates quarterly
- Note currency differences clearly
- Link to specific product pages (not just homepage)
- Be honest about competitor quality
- Highlight YOUR unique value (customization, hand-made)
- Use only for products where you're competitive

**DON'T:**
- Make up prices - verify everything
- Compare different product types
- Badmouth competitors
- Let data get stale (update regularly)
- Show comparison if you're significantly more expensive (unless you explain why)

### Example: When to Use

✅ **Good candidates:**
- Similar products where you offer better value
- Products where your custom sizing is an advantage
- Items where hand-made quality justifies price
- Products priced competitively

❌ **Skip comparison for:**
- Unique products with no direct competition
- Products where you're much more expensive (without clear value story)
- Items still in development/pricing

### Maintenance Schedule
- **Monthly:** Spot-check 5-10 random comparisons
- **Quarterly:** Full review of all comparison data
- **When:** Competitor has sale/price change, update immediately
- **Archive:** Remove comparisons older than 6 months

---

**Last Updated:** January 25, 2026