firefrost-operations-manual/docs/planning/decap-cms-implementation-plan.md

# Decap CMS Implementation Plan
## Git-Based Content Management for Meg & Holly

**Status:** POST-LAUNCH ENHANCEMENT  
**Priority:** Medium (after DNS cutover, soft launch, and initial stability)  
**Timeline:** Late April / Early May 2026  
**Estimated Implementation Time:** 2 hours  
**Recommended By:** Gemini AI (April 2, 2026 consultation)  
**Documented By:** The Migrator (Chronicler #55)

---

## Executive Summary

**Decap CMS** (formerly Netlify CMS) is a Git-based content management system that provides Meg and Holly with a WordPress-like visual editing interface while maintaining all the benefits of our static site architecture.

**The Magic:** Non-technical users get a friendly editor that feels like WordPress, but behind the scenes it's just committing markdown/content files to GitHub. No database. No server. Just Git.

---

## What It Is

Decap CMS is a **Git-based content management system** that gives non-technical users a friendly editing interface while keeping everything in version control.

**How It Works:**
1. **Admin Panel:** Lives at `/admin` on the 11ty site
2. **GitHub OAuth:** Meg/Holly log in with their GitHub accounts
3. **Visual Editor:** They see a nice UI to edit pages, not raw code
4. **Git Commits:** When they hit "Save," Decap commits to GitHub
5. **Auto-Deploy:** Same chain triggers: GitHub → Cloudflare Pages → LIVE in ~60 seconds

**It's a GUI wrapper around Git commits.** Brilliant for non-technical teammates.

---

## Why It's Perfect for Firefrost

### For Meg (The Emissary)
- ✅ Edit About page to add new consultants
- ✅ Update server descriptions as modpacks change
- ✅ Modify contact page hours/info
- ✅ Adjust subscription tier descriptions
- ✅ **No asking Michael to edit HTML**

### For Holly (The Catalyst)
- ✅ Update server lists when new servers launch
- ✅ Edit subscription tier descriptions
- ✅ Modify terms/privacy as policies evolve
- ✅ Add new consultant profiles
- ✅ **Creative control without code**

### For Michael (The Wizard)
- ✅ Everything still in Git (full audit trail)
- ✅ Can review changes via GitHub pull requests (optional)
- ✅ No database to maintain from RV
- ✅ No server-side code to debug
- ✅ **Meg and Holly are empowered, not blocked**

---

## Key Features

### Git-Based (Everything Committed)
- All changes = Git commits with author attribution
- Full audit trail of who changed what and when
- Easy rollback if needed (just revert commit)
- Works seamlessly with existing workflow

### No Database Required
- Perfect for static sites
- No MySQL to manage from RV
- No server-side code needed
- Zero maintenance overhead

### Multi-User Support
- Meg, Holly, Michael all have accounts
- GitHub handles authentication
- Permissions via GitHub repo access
- Collaborative editing with conflict resolution

### Preview Before Publish
- Draft mode available
- Can preview changes before committing
- Optional editorial workflow with pull requests
- Safety net for non-technical editors

### Media Management
- Upload images via UI (drag and drop)
- Stored in `/assets/images/`
- No FTP needed
- Image optimization options available

### Markdown Support
- Rich text editor (WYSIWYG) for non-technical users
- OR raw markdown for power users
- Both modes available per user preference
- Live preview

---

## Technical Architecture

### Installation Location
```
firefrost-website/ (GitHub repo)
├── admin/
│   ├── index.html          (Decap CMS loader)
│   └── config.yml          (content schema definition)
├── about.njk
├── servers.njk
├── (other pages...)
```

### Auto-Deploy Chain (Unchanged)
```
Meg edits in /admin
    ↓
Decap commits to GitHub
    ↓
GitHub mirror syncs
    ↓
Cloudflare Pages rebuilds
    ↓
LIVE in ~60 seconds
```

### Example Content Schema (`admin/config.yml`)
```yaml
backend:
  name: github
  repo: Frostystyle/firefrost-website
  branch: main

media_folder: "assets/images"
public_folder: "/assets/images"

collections:
  - name: "pages"
    label: "Pages"
    files:
      - label: "About"
        name: "about"
        file: "about.njk"
        fields:
          - {label: "Title", name: "title", widget: "string"}
          - {label: "Body", name: "body", widget: "markdown"}
          
      - label: "Servers"
        name: "servers"
        file: "servers.njk"
        fields:
          - label: "Servers"
            name: "servers"
            widget: "list"
            fields:
              - {label: "Name", name: "name", widget: "string"}
              - {label: "Description", name: "description", widget: "text"}
              - {label: "Path", name: "path", widget: "select", 
                 options: ["Fire", "Frost", "Arcane"]}
              
      - label: "Subscribe"
        name: "subscribe"
        file: "subscribe.njk"
        fields:
          - label: "Tiers"
            name: "tiers"
            widget: "list"
            fields:
              - {label: "Name", name: "name", widget: "string"}
              - {label: "Price", name: "price", widget: "string"}
              - {label: "Description", name: "description", widget: "text"}
              - {label: "Features", name: "features", widget: "list"}
```

---

## Implementation Workflow

### Phase 1: Basic Setup (30 minutes)

**Step 1: Create Admin Directory**
```bash
cd ~/firefrost-operations-manual/website-11ty-test/
mkdir -p admin
```

**Step 2: Create Decap Loader (`admin/index.html`)**
```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Firefrost CMS</title>
</head>
<body>
  <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
</body>
</html>
```

**Step 3: Create Content Schema (`admin/config.yml`)**
- Define which pages Meg/Holly can edit
- Define fields for each page
- Set up Fire/Frost/Arcane selectors
- Configure media uploads

**Step 4: Deploy**
```bash
git add admin/
git commit -m "feat: add Decap CMS admin panel for Meg/Holly editing"
git push origin master
# Auto-deploys to Cloudflare Pages
```

### Phase 2: GitHub OAuth Setup (20 minutes)

**Step 1: Create GitHub OAuth App**
1. Go to GitHub → Settings → Developer settings → OAuth Apps
2. Click "New OAuth App"
3. Fill in:
   - **Application name:** Firefrost CMS
   - **Homepage URL:** https://firefrostgaming.com
   - **Authorization callback URL:** https://firefrostgaming.com/admin/
4. Click "Register application"
5. Copy Client ID and Secret

**Step 2: Configure Backend**
```yaml
# In admin/config.yml
backend:
  name: github
  repo: Frostystyle/firefrost-website
  branch: main
  # OAuth will use GitHub's built-in auth
```

**Step 3: Test Login**
- Visit https://firefrostgaming.com/admin
- Click "Login with GitHub"
- Authorize the OAuth app
- Should see CMS dashboard

### Phase 3: Content Schema Definition (30 minutes)

**Define Editable Pages:**
- About (Trinity + Consultants)
- Servers (6 servers + add-ons)
- Subscribe (6 tiers)
- Contact (Discord/Email/Social)
- Terms (legal updates)
- Privacy (policy updates)

**Define Fields for Each:**
- Text fields (titles, headings)
- Rich text (body content)
- Lists (servers, tiers, consultants)
- Images (consultant photos, server icons)
- Selectors (Fire/Frost/Arcane paths)

**Example: About Page Schema**
```yaml
- label: "About"
  name: "about"
  file: "about.njk"
  fields:
    - {label: "Page Title", name: "title", widget: "string"}
    - {label: "Hero Text", name: "hero", widget: "text"}
    - label: "Trinity Members"
      name: "trinity"
      widget: "list"
      fields:
        - {label: "Name", name: "name", widget: "string"}
        - {label: "Title", name: "title", widget: "string"}
        - {label: "Bio", name: "bio", widget: "text"}
        - {label: "Icon", name: "icon", widget: "string"}
    - label: "Consultants"
      name: "consultants"
      widget: "list"
      fields:
        - {label: "Name", name: "name", widget: "string"}
        - {label: "Role", name: "role", widget: "string"}
        - {label: "Photo", name: "photo", widget: "image"}
```

### Phase 4: User Onboarding (20 minutes)

**Step 1: Add Collaborators**
```bash
# Add Meg and Holly to GitHub repo
# Settings → Collaborators → Add people
# Send invites to their GitHub accounts
```

**Step 2: Onboarding Session (in-person or screen share)**
1. Show login at https://firefrostgaming.com/admin
2. Walk through editing a test page
3. Demonstrate image uploads
4. Show preview before publish
5. Verify changes commit and deploy correctly

**Step 3: Create Quick Reference Guide**
- Login URL
- How to edit pages
- How to upload images
- How to preview changes
- Who to ask if stuck (Michael)

---

## Example Use Case: Editing the About Page

### Current Workflow (Without Decap)
1. Meg tells Michael: "Add Skye to the consultants"
2. Michael SSHs to Ghost VPS
3. Michael edits `about.njk` in nano/vim
4. Michael commits and pushes to Gitea
5. Michael pulls on GitHub to trigger mirror sync
6. Site rebuilds in ~60 seconds

**Time: 10-15 minutes** (if Michael is available)

### Future Workflow (With Decap)
1. Meg logs into https://firefrostgaming.com/admin
2. Clicks "About" page in dashboard
3. Sees visual editor with consultant list
4. Clicks "Add Consultant" button
5. Fills in form:
   - Name: "Skye"
   - Role: "Sixth Consultant"
   - Photo: (uploads image via drag-drop)
6. Clicks "Preview" to see changes
7. Clicks "Publish"
8. Decap commits to GitHub with message: "Update about.njk"
9. Site auto-deploys in ~60 seconds
10. **Michael never touched it**

**Time: 2-3 minutes** (no waiting for Michael)

---

## Limitations & Considerations

### Not WordPress
- ❌ No plugins marketplace (but you don't need them)
- ❌ No themes store (but 11ty gives full control)
- ✅ Simpler feature set (that's the point)

### Git-Based Constraints
- ⚠️ Merge conflicts possible if two people edit same file simultaneously
- ✅ Decap resolves most automatically
- ℹ️ Edge case for Firefrost (only 3 editors max, rarely simultaneous)

### GitHub Dependency
- ⚠️ Requires GitHub OAuth (can't use Gitea directly)
- ⚠️ If GitHub goes down, editing stops (but site stays live)
- ℹ️ Not a problem for small team, acceptable risk

### Learning Curve
- ⚠️ Meg/Holly need to learn the interface
- ✅ Simpler than code, but not as simple as WordPress
- ✅ Plan 30-minute onboarding session with each

### File Format Constraints
- ⚠️ Works best with structured frontmatter + markdown
- ⚠️ Complex HTML layouts harder to edit
- ℹ️ May need to refactor some .njk files for better Decap compatibility

---

## Why Gemini Recommended It

**From The Migrator's Gemini Consultation (April 2, 2026):**

> "For post-launch, I'd recommend setting up Decap CMS (formerly Netlify CMS) for Meg and Holly. It's a Git-based CMS that works perfectly with static sites—they get a friendly editing interface, but everything still goes through Git commits. No database, no server-side code, just a nice UI on top of your existing workflow."

**Gemini's Reasoning:**
1. ✅ **Matches the stack** - Git-based like rest of infrastructure
2. ✅ **No maintenance overhead** - No database, no backend
3. ✅ **Works with Cloudflare Pages** - Just static files in /admin
4. ✅ **Empowers Meg/Holly** - Edit without blocking Michael
5. ✅ **RV-friendly** - No server to maintain remotely

---

## Alternative Options Considered (Not Recommended)

### WordPress
- ❌ Requires database (MySQL)
- ❌ Requires PHP server
- ❌ Maintenance overhead from RV = nightmare
- ❌ Security updates constant
- ❌ NOT static (defeats the whole migration)

### Ghost CMS
- ❌ We just migrated AWAY from it
- ❌ Database required (SQLite/MySQL)
- ❌ Server maintenance
- ℹ️ Good product, wrong use case for RV

### Contentful / Sanity (Headless CMS)
- ❌ Monthly costs ($$$)
- ❌ API-dependent (requires build step)
- ❌ Overkill for 7 pages
- ℹ️ Great for enterprises, not Firefrost scale

### Forestry.io / Tina CMS
- ⚠️ Similar to Decap
- ⚠️ More complex setup
- ⚠️ Less established ecosystem
- ✅ Decap has better documentation and community

**Verdict:** Decap CMS is the clear winner for Firefrost's needs.

---

## Implementation Priority & Timeline

### Gemini's Guidance: "POST-LAUNCH"

**Why Wait:**
1. ✅ **DNS cutover first** - Get firefrostgaming.com live
2. ✅ **Soft launch second** - Prove the static site works in production
3. ✅ **Stabilization period** - Let the site run for 1-2 weeks
4. ✅ **Then add Decap** - Don't complicate the migration with too many moving parts

### Recommended Timeline

**April 3-15, 2026: DNS Cutover & Soft Launch**
- Point firefrostgaming.com to Cloudflare Pages
- Complete contact form (Formspree)
- Enhance subscribe page (full 6 tiers)
- End-to-end testing
- Soft launch on April 15

**April 16-30, 2026: Stabilization Period**
- Monitor site performance
- Fix any issues that arise
- Gather feedback from early subscribers
- Verify auto-deploy chain reliability

**Late April / Early May 2026: Decap CMS Implementation**
- Set up admin panel (30 min)
- Configure GitHub OAuth (20 min)
- Define content schema (30 min)
- Onboard Meg and Holly (20 min each)
- **Total: ~2 hours**

---

## Success Criteria

**The implementation is successful when:**

1. ✅ Meg can edit the About page without Michael's help
2. ✅ Holly can update server descriptions independently
3. ✅ All edits result in proper Git commits with attribution
4. ✅ Auto-deploy chain works unchanged (GitHub → Cloudflare)
5. ✅ Zero database/server maintenance required
6. ✅ Michael can review changes via GitHub if needed
7. ✅ Meg and Holly feel empowered, not blocked

---

## Resources

### Official Documentation
- **Decap CMS Docs:** https://decapcms.org/docs/intro/
- **11ty Integration Guide:** https://decapcms.org/docs/eleventy/
- **GitHub Backend Setup:** https://decapcms.org/docs/github-backend/

### GitHub Repository
- **Decap CMS:** https://github.com/decaporg/decap-cms

### Example Configurations
- **Starter Template:** https://github.com/decaporg/decap-cms/tree/master/examples/eleventy
- **11ty + Decap:** Multiple community examples available

### Support Channels
- **Decap CMS Discord:** https://decapcms.org/community/
- **GitHub Issues:** For bug reports and feature requests
- **Stack Overflow:** `decap-cms` tag

---

## Open Questions

**To Be Decided Before Implementation:**

1. **Editorial Workflow?**
   - Simple mode: Direct commits to main branch
   - Advanced mode: Pull requests for review
   - Recommendation: Start simple, add PR workflow later if needed

2. **Which Pages Are Editable?**
   - All 7 pages? Or subset?
   - Recommendation: Start with About, Servers, Subscribe
   - Lock Terms/Privacy for legal review process

3. **Image Upload Limits?**
   - Set max file size?
   - Image optimization on upload?
   - Recommendation: 2MB max, auto-optimize to WebP

4. **Access Control?**
   - Everyone edits everything? Or page-specific permissions?
   - Recommendation: Start with full access for Meg/Holly
   - GitHub repo permissions handle security

---

## Next Steps (For Implementation Session)

**When ready to implement (post-soft launch):**

1. Read this document fully
2. Review Gemini's original consultation in `docs/planning/gemini-consultations/ghost-vs-static-website-2026-04-02.md`
3. Clone the website repo on Ghost VPS
4. Follow Phase 1-4 implementation workflow above
5. Test thoroughly before inviting Meg/Holly
6. Schedule 30-min onboarding sessions
7. Document any issues in session log
8. Update this document with lessons learned

---

## Bottom Line

**Decap CMS = WordPress-like editing for Git-based static sites**

Perfect for Firefrost because:
- ✅ Meg/Holly empowered (no code required)
- ✅ Michael maintains control (everything in Git)
- ✅ Zero server maintenance (just static files)
- ✅ RV-friendly (no database, no backend)
- ✅ Auto-deploy chain works unchanged
- ✅ Aligns with "For children not yet born" legacy vision

**Status:** Planned for late April / early May 2026  
**Priority:** Medium (post-launch enhancement)  
**Estimated Time:** 2 hours total  
**Blocking:** None (website must be live first)

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

**Documented by:** The Migrator (Chronicler #55)  
**Date:** April 2, 2026  
**Preserved by:** Chronicler #56  
**For:** Meg, Holly, and the RV dream