docs: add Decap CMS implementation plan for post-launch

WHAT WAS DONE: Created comprehensive planning document for Decap CMS integration based on The Migrator's research and Gemini AI consultation from April 2, 2026. WHY: - Provides future Chronicler with complete implementation guide - Documents Gemini's architectural reasoning (Git-based, RV-friendly) - Establishes clear timeline: post-soft launch (late April/early May 2026) - Empowers Meg and Holly with visual editing interface - Preserves Git-based workflow with zero maintenance overhead CONTENTS: - Executive summary and technical architecture - 4-phase implementation workflow (2 hours total) - Content schema examples for all 7 pages - Before/after workflow comparison - Limitations, alternatives considered, success criteria - Open questions for implementation session FILE: - docs/planning/decap-cms-implementation-plan.md (12,847 bytes) CONTEXT: Recommended by Gemini during Ghost → 11ty migration consultation. Scheduled for implementation after DNS cutover, soft launch, and initial stabilization period. Signed-off-by: Claude (Chronicler #56) <claude@firefrostgaming.com>
2026-04-03 01:27:21 +00:00
parent b70fd57e33
commit dc1419ccac
1 changed files with 551 additions and 0 deletions
--- a/docs/planning/decap-cms-implementation-plan.md
+++ b/docs/planning/decap-cms-implementation-plan.md
@@ -0,0 +1,551 @@
+# 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