# ModpackChecker Flagship Product Completion Plan

**Document ID:** FFG-PLAN-001  
**Created:** April 6, 2026  
**Created By:** Chronicler #64  
**Project:** Task #26 — ModpackChecker Blueprint Extension  
**Status:** Pre-Launch Planning — Flagship Product Standard

---

## 🎯 MISSION STATEMENT

ModpackChecker is Firefrost Gaming's first commercial product launch. This is not just a tool — it's our reputation. First impressions on BuiltByBit determine whether we become known as "that dev who ships quality" or "that dev who overpromised."

**We choose quality.**

This document outlines the complete path from current state to launch-ready flagship product.

---

## 📊 CURRENT STATE (April 6, 2026)

### ✅ What's Built (Phases 1-4 Complete)
- API integrations: CurseForge, Modrinth, Technic, FTB
- Database schema: `modpack_versions` table
- Dashboard badge: UpdateBadge.tsx component
- Console widget: ModpackVersionCard.tsx component
- Admin panel: Configuration interface
- Cron job: Background version checking
- Rate limiting: 2 requests/minute per server
- 60-second TTL cache for dashboard

### ⚠️ What's Missing (Launch Blockers)
1. **Modrinth auto-detection** — Currently manual-only, needs `versionId` → `project_id` mapping
2. **"Ignore Version" feature** — Critical UX for handling version string mismatches
3. **Backoff logic** — Prevents infinite scanning of vanilla/custom servers
4. **Commercial documentation** — Setup guide, troubleshooting, FAQ
5. **BuiltByBit listing materials** — Product description, screenshots, compatibility matrix

### 🔧 What Works But Needs Polish
- Blueprint packaging (manual deployment steps required)
- Database migrations (need to add new columns)
- Console widget (needs "Ignore Version" button)

---

## 🏗️ FLAGSHIP COMPLETION ROADMAP

### **Phase 5: Modrinth Auto-Detection** (4-6 hours)
**Priority:** CRITICAL — Moves us from 60% to 85% market coverage

**Architecture (Validated by Gemini):**
1. Cron reads `modrinth.index.json` from server filesystem
2. Extract `versionId` from manifest
3. Call Modrinth API: `GET /v2/version/{versionId}`
4. Response contains `project_id` — save to database
5. Use `project_id` for future version checks

**Database Changes:**
```sql
ALTER TABLE modpack_versions 
  ADD COLUMN modrinth_version_id VARCHAR(50) NULL;
```

**Code Changes:**
- Update `CheckModpackUpdates.php` command
- Add `detectModrinth()` method to cron
- Inject `DaemonFileRepository` for file reads
- Parse `modrinth.index.json` structure
- Call Modrinth `/v2/version/{id}` endpoint

**Testing:**
- Test on Adrenaserver (known Modrinth pack)
- Verify `project_id` extraction
- Confirm version comparison works

**Deliverable:** Modrinth packs auto-detect without manual configuration

---

### **Phase 6: "Ignore Version" Feature** (2-3 hours)
**Priority:** CRITICAL — Eliminates 90% of false-positive support tickets

**Problem:**
- String comparison (`!==`) flags `v1.2.3-hotfix` vs `v1.2.4` as different
- User knows they're functionally equivalent
- Without ignore button → support ticket or refund

**Solution:**
Database column + UI button that lets users dismiss version alerts

**Database Changes:**
```sql
ALTER TABLE modpack_versions 
  ADD COLUMN user_ignored_version VARCHAR(50) NULL;
```

**Logic:**
- User clicks "Mark as Up-to-Date" in console widget
- Save current `latest_version` to `user_ignored_version`
- Badge turns green
- Badge stays green until a NEW `latest_version` appears (different from ignored version)

**UI Changes:**
- Add button to `ModpackVersionCard.tsx`
- Button only shows when `update_available = true`
- Button label: "Mark as Up-to-Date" or "Ignore This Version"
- Add API endpoint: `POST /servers/{server}/modpack/ignore-version`

**API Endpoint:**
```php
public function ignoreVersion(Request $request, Server $server)
{
    $modpackVersion = ModpackVersion::where('server_uuid', $server->uuid)->first();
    
    $modpackVersion->update([
        'user_ignored_version' => $modpackVersion->latest_version
    ]);
    
    return response()->json(['success' => true]);
}
```

**Badge Logic Update:**
```php
// In CheckModpackUpdates command
if ($latestVersion !== $installedVersion) {
    // Check if user has ignored this specific version
    if ($modpackVersion->user_ignored_version === $latestVersion) {
        $updateAvailable = false; // Keep badge green
    } else {
        $updateAvailable = true;
    }
}
```

**Deliverable:** Users can dismiss false-positive version alerts without support tickets

---

### **Phase 7: Backoff Logic for Unsupported Servers** (1-2 hours)
**Priority:** HIGH — Prevents Wings API spam for vanilla/custom servers

**Problem:**
- Cron attempts file detection every hour
- Vanilla servers have no manifest files
- Infinite failed attempts = wasted Wings API calls

**Solution (Gemini-Validated):**
Stop scanning servers after 3 failed attempts until user manually triggers "Force Check"

**Database Changes:**
```sql
ALTER TABLE modpack_versions 
  ADD COLUMN auto_detect_failed_count INT DEFAULT 0,
  ADD COLUMN last_auto_detect_attempt TIMESTAMP NULL;
```

**Logic:**
```php
// In CheckModpackUpdates command
if ($modpackVersion->auto_detect_failed_count >= 3) {
    continue; // Skip this server in cron
}

try {
    $detected = $this->attemptAutoDetection($server);
    
    if ($detected) {
        $modpackVersion->update([
            'auto_detect_failed_count' => 0,
            'last_auto_detect_attempt' => now()
        ]);
    } else {
        $modpackVersion->increment('auto_detect_failed_count');
        $modpackVersion->update(['last_auto_detect_attempt' => now()]);
    }
} catch (DaemonConnectionException $e) {
    // Node offline — don't count as failed detection
    continue;
}
```

**UI Changes:**
- "Force Check" button in console widget resets `auto_detect_failed_count`
- Shows message: "Auto-detection paused after 3 failed attempts. Click to retry."

**Deliverable:** Cron doesn't spam Wings API for unsupported servers

---

### **Phase 8: Commercial Documentation** (3-4 hours)
**Priority:** CRITICAL — Reduces support tickets by 70%

**Structure (Gemini-Validated):**

#### **1. README.md (Overview)**
- What it does (one paragraph)
- Compatibility matrix table
- System requirements
- Quick links to other docs

#### **2. INSTALLATION.md**
- Prerequisites checklist
- Three-command install process
- Database migration steps
- Panel restart instructions
- Verification steps

#### **3. CONFIGURATION.md (The API Key Hub)**
**CurseForge API Key:**
- Step 1: Go to https://console.curseforge.com
- Step 2: Create application
- Step 3: Generate API key
- Step 4: Paste into Admin Panel

**Modrinth API Key:**
- Step 1: Go to https://modrinth.com/settings/pats
- Step 2: Create Personal Access Token
- Step 3: Set scopes (read-only)
- Step 4: Paste into Admin Panel

#### **4. HOW-IT-WORKS.md (The Tiered System)**
**Critical Section — Prevents "It's Broken" Tickets**

Explain the three-tier detection process:

**Tier 1: Egg Variables** (Instant, Rarely Present)
- Checks server egg for `MODPACK_PLATFORM` and `MODPACK_ID`
- Most eggs don't have these

**Tier 2: File Detection** (Auto-Discovery, CurseForge + Modrinth)
- Reads `manifest.json` (CurseForge) or `modrinth.index.json` (Modrinth)
- Runs in background cron job (hourly)
- Requires manifest files to exist on server

**Tier 3: Manual Configuration** (Universal Fallback)
- Console widget → "Configure Manually" button
- Works for ANY platform (FTB, Technic, ATLauncher, Custom)
- User enters platform + modpack ID once

**Why Your Server Might Not Auto-Detect:**
1. It's a vanilla server (no modpack manifest)
2. It's a custom modpack (no manifest from supported platform)
3. It uses FTB/Technic/ATLauncher (manual config required)
4. Manifest file was deleted or moved

#### **5. MANUAL-CONFIGURATION.md**
- When to use manual config
- How to find modpack IDs for each platform
- Step-by-step screenshots

#### **6. TROUBLESHOOTING.md**
**Common Issues:**

**"My badge is gray / shows 'Not Configured'"**
- Server needs manual configuration
- Click "Configure Manually" in console widget

**"It says there's an update but I'm already on the latest version"**
- Modpack author changed naming convention
- Click "Mark as Up-to-Date" to dismiss alert

**"I see a 429 error"**
- API rate limit hit (rare)
- Extension respects 2 req/min limit
- Wait 60 seconds and retry

**"Auto-detection stopped working"**
- 3 failed attempts triggered backoff
- Click "Force Check" to retry
- If still failing, use manual config

**"Server is offline/suspended but still shows old version"**
- Cron skips offline servers
- Version will update next time server is online

#### **7. FAQ.md**
- What platforms are supported?
- Do I need API keys for all platforms?
- How often does it check for updates?
- Can I check updates manually instead of cron?
- What happens if I delete the manifest file?
- Does this work with custom modpacks?
- Can I disable auto-detection for specific servers?

**Deliverable:** Complete documentation preventing 70% of support tickets

---

### **Phase 9: BuiltByBit Listing Materials** (2-3 hours)
**Priority:** CRITICAL — Sets accurate expectations, prevents refunds

#### **Product Description Structure:**

**1. The Hook (One-Sentence Pitch)**
> Stop checking modpacks manually. Start managing them automatically with the industry's first dual-engine version tracker for Pterodactyl.

**2. Value Propositions (Reframe Limitations)**
- ✅ **85%+ Instant Coverage:** Auto-detection for CurseForge & Modrinth
- ✅ **Universal Manual Fallback:** Support for ANY platform via simple ID entry
- ✅ **Dashboard Pulse:** High-visibility status integrated into server list
- ✅ **Performance First:** Passive background checks, zero panel impact

**3. Compatibility Matrix (Top of Listing)**
```
| Platform          | Auto-Detection | Manual Config | Notes                    |
|-------------------|----------------|---------------|--------------------------|
| CurseForge        | ✅ Yes         | ✅ Yes         | Uses manifest.json       |
| Modrinth          | ✅ Yes         | ✅ Yes         | Uses modrinth.index.json |
| FTB (Modern)      | ❌ No          | ✅ Yes         | Requires FTB ID entry    |
| Technic           | ❌ No          | ✅ Yes         | Requires Slug entry      |
| Custom/Vanilla    | ❌ No          | ✅ Yes         | Requires Manual Setup    |
```

**4. Features List**
- Automatic version checking for CurseForge & Modrinth modpacks
- At-a-glance dashboard badge showing update status
- Console widget with detailed version information
- Manual configuration for unsupported platforms
- Smart caching (60-second TTL, minimal API usage)
- Rate limiting protection (won't get your API keys banned)
- "Ignore Version" feature for handling naming convention changes
- Admin panel for API key management

**5. Requirements**
- Pterodactyl Panel 1.12.x or higher
- Blueprint beta-2026-01 or higher
- PHP 8.3+
- PostgreSQL database
- CurseForge API key (free)
- Modrinth API key (free)

**6. Installation**
Three-command install via Blueprint (see documentation for details)

**7. "Read Before You Buy" (Bottom of Listing)**
1. **Vanilla Servers:** This extension will not auto-detect vanilla Minecraft servers (no modpack manifest exists)
2. **Manifest Dependency:** Auto-detection requires `manifest.json` or `modrinth.index.json` in server root
3. **Exact String Matching:** Version comparison uses exact string matching, not semantic versioning. If modpack authors change naming formats, extension will flag for your review.

**8. Support & Updates**
- Comprehensive documentation included
- Active support via BuiltByBit messages
- Free updates for life

#### **Screenshots Needed:**
1. Dashboard with update badges (green, yellow, red states)
2. Console widget showing version details
3. Console widget "Configure Manually" modal
4. Console widget "Mark as Up-to-Date" button
5. Admin panel API key configuration
6. Example of Modrinth auto-detection working
7. Example of manual configuration for FTB pack

**Deliverable:** Transparent, accurate BuiltByBit listing preventing refunds

---

### **Phase 10: Blueprint Packaging Fix** (2-3 hours)
**Priority:** HIGH — Ensures clean install experience

**Current Issue (from Pathmaker #63):**
- `build.sh` doesn't run on production install
- PHP files stay in extension subfolder
- React components need manual injection

**Solution Options:**

**Option A: Fix Blueprint Packaging**
- Research Blueprint native wrapper injection
- Eliminate build.sh dependency
- Ensure PHP files auto-copy on install
- Test clean install cycle

**Option B: Provide Clear Manual Steps**
- Document exact post-install commands
- Include in INSTALLATION.md
- Test commands on fresh panel
- Accept this as "advanced install" product

**Decision:** Start with Option B (document manual steps), upgrade to Option A in v1.1

**Deliverable:** Clean installation process (manual or automated)

---

### **Phase 11: Licensing & Support Infrastructure** (6-8 hours)
**Priority:** CRITICAL — Protects your time and prevents support burnout

**Gemini's Core Philosophy:**
> "The real anti-piracy measure is gating your updates and your Discord support."

**Don't fight pirates with DRM. Fight them by making legitimate ownership MORE VALUABLE than piracy.**

#### **A) BuiltByBit Order ID Validation System** (3-4 hours)

**The Simplified License Model:**
- ❌ NO complex UUID generation
- ❌ NO encrypted license keys
- ❌ NO IonCube obfuscation (breaks panel updates)
- ✅ YES BuiltByBit Order ID as "the key"
- ✅ YES lightweight validation API
- ✅ YES 7-day grace period

**Validation Flow:**
1. Buyer purchases on BuiltByBit (receives Order ID)
2. Buyer installs extension on their panel
3. Extension admin panel asks for: **BuiltByBit Order ID** + **Discord Username**
4. Extension calls validation API: `POST https://panel.firefrostgaming.com/api/validate-mvc`
5. API checks BuiltByBit API: "Is this Order ID valid?"
6. If valid → extension fully functional
7. If invalid → 7-day grace period starts

**Validation Frequency:**
- Once every 72 hours via cron job
- **NEVER on page load** (if validation server is down, panels don't crash)
- Store last validation timestamp in database

**Grace Period Logic:**
- If validation fails (network issue, server down, etc.) → 7-day grace period
- During grace period: Extension works normally
- After grace period expires: Disable auto-detection cron, show "License Invalid" warning
- UI remains functional (manual configuration still works)

**Database Schema:**
```sql
CREATE TABLE mvc_licenses (
    id SERIAL PRIMARY KEY,
    license_key VARCHAR(64) UNIQUE NOT NULL, -- This is the BuiltByBit Order ID
    builtbybit_order_id VARCHAR(50),
    buyer_email VARCHAR(255),
    buyer_discord_id VARCHAR(20),
    buyer_discord_username VARCHAR(100),
    purchase_date TIMESTAMP,
    
    -- Multi-panel support
    max_activations INT DEFAULT 2, -- Allow dev + production panels
    current_activations INT DEFAULT 0,
    hardware_ids JSONB, -- Store panel domains/IPs as array
    
    -- Activation tracking
    is_activated BOOLEAN DEFAULT false,
    activated_panel_domain VARCHAR(255), -- Primary panel
    activation_date TIMESTAMP,
    last_check_in TIMESTAMP,
    last_validation_attempt TIMESTAMP,
    validation_failures INT DEFAULT 0,
    grace_period_expires TIMESTAMP,
    
    -- Status management
    status VARCHAR(20) DEFAULT 'active', -- active, suspended, refunded, expired
    is_revoked BOOLEAN DEFAULT false,
    revoke_reason TEXT,
    
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_license_key ON mvc_licenses(license_key);
CREATE INDEX idx_buyer_email ON mvc_licenses(buyer_email);
CREATE INDEX idx_buyer_discord ON mvc_licenses(buyer_discord_id);
CREATE INDEX idx_activated_panel ON mvc_licenses(activated_panel_domain);
CREATE INDEX idx_status ON mvc_licenses(status);
```

**Validation API Endpoint:**
```
POST /api/validate-mvc
Body: {
  "order_id": "BBB-12345",
  "panel_domain": "panel.example.com",
  "discord_username": "frostystyle"
}

Response: {
  "valid": true,
  "status": "active",
  "grace_period_expires": null,
  "max_activations": 2,
  "current_activations": 1,
  "message": "License validated successfully"
}
```

**Code Changes:**
- Add admin panel UI for Order ID entry
- Add cron job for 72-hour validation check
- Add grace period tracking
- Add UI warning for invalid licenses
- Add BuiltByBit API integration

**Testing:**
- Test valid Order ID
- Test invalid Order ID (grace period triggers)
- Test network failure (grace period triggers)
- Test grace period expiration (cron disables, UI shows warning)
- Test multi-panel activation (dev + production)

---

#### **B) Discord Support Infrastructure** (2-3 hours)

**The Gated Community Approach:**
- Keep everything in Firefrost Gaming Discord (no separate server)
- Gate support channels to `ModpackChecker Owner` role
- Buyers verify purchase → auto-assigned role → channels appear

**Discord Channel Structure:**
1. **#mvc-general** (Public to all MVC Owners)
   - Peer-to-peer support
   - Tips and tricks
   - Community discussion
   - Identifies future "Community Helper" moderators

2. **#mvc-support** (Ticket Tool category, role-gated)
   - Private tickets for official support
   - Only visible to MVC Owners
   - Response SLA: 24-48 business hours

**Ticket Tool Configuration:**
- Add 7th ticket type: "ModpackChecker Support"
- Require `ModpackChecker Owner` role to see/open tickets
- Auto-responder message sets boundaries

**Auto-Responder Message:**
```
Thanks for reaching out about ModpackChecker! 

Our official support hours are Monday-Friday, 9 AM - 5 PM CST. We typically respond within 24 hours.

While you wait, please check:
📖 Documentation: [GitBook URL]
🔍 Troubleshooting Guide: [Direct link]
💬 #mvc-general: Other owners may have solved similar issues

Please ensure your ticket includes:
✅ Pterodactyl Panel version
✅ Blueprint version
✅ PHP version
✅ Platform (CurseForge/Modrinth/FTB/Technic)
✅ Screenshots of any errors

We'll be with you shortly!
```

**Pre-Ticket Form (Ticket Tool feature):**
Before ticket opens, collect:
- Panel Version: _______
- Blueprint Version: _______
- PHP Version: _______
- Have you checked the Troubleshooting Guide? [Yes/No]
- Have you verified your API key spelling? [Yes/No]

---

#### **C) Discord Verification Bot** (1-2 hours)

**Purpose:** Link BuiltByBit purchases to Discord roles automatically

**Flow:**
1. Buyer purchases on BuiltByBit (receives Order ID via email/DM)
2. Buyer joins Firefrost Gaming Discord
3. Buyer runs command: `/verify-mvc [order-id]`
4. Bot calls validation API to check Order ID
5. If valid → assigns `ModpackChecker Owner` role
6. Channels `#mvc-general` and support ticket button appear
7. Bot DMs buyer: "Verification successful! You now have access to MVC support channels."

**Implementation Options:**

**Option A: Extend Existing Bot (Carl-bot or custom)**
- Add `/verify-mvc` command
- Calls validation API
- Assigns role on success

**Option B: Standalone Verification Bot**
- Simple Node.js bot
- Single command: `/verify-mvc`
- Minimal maintenance

**Option C: BuiltByBit Native Integration**
- Research if BuiltByBit has Discord OAuth
- May auto-assign role on purchase

**Recommended:** Start with Option B (standalone bot), evaluate Option C availability

**Bot Database Table:**
```sql
CREATE TABLE discord_verifications (
    id SERIAL PRIMARY KEY,
    discord_id VARCHAR(20) NOT NULL,
    discord_username VARCHAR(100),
    order_id VARCHAR(50) NOT NULL,
    verified_at TIMESTAMP DEFAULT NOW(),
    role_assigned BOOLEAN DEFAULT true,
    
    FOREIGN KEY (order_id) REFERENCES mvc_licenses(license_key)
);

CREATE INDEX idx_discord_id ON discord_verifications(discord_id);
CREATE INDEX idx_order_id ON discord_verifications(order_id);
```

**Anti-Sharing Logic:**
- 1 Order ID = 1 Discord account
- If Order ID already verified → "This order has already been verified by another Discord account. Please contact support if you changed accounts."
- Allow transfer via support ticket (verify ownership, unlink old account, link new account)

---

#### **D) Descriptive UI Error Messages** (1 hour)

**Gemini's Highest ROI Recommendation:**
> "The highest ROI for support reduction isn't a Discord channel; it's UX and Error Handling within the extension itself."

**Bad UX:**
- API call fails → badge just breaks silently
- User confused → opens support ticket

**Good UX:**
- API call fails → Red warning icon on badge
- Hover text: "CurseForge API Key Missing. Configure in Admin → Extensions → ModpackChecker Settings"
- Console widget shows: "⚠️ No API key configured. [Click here to add one]"

**Error States to Handle:**

| Error | UI Display | Hover Text | Action Link |
|-------|------------|------------|-------------|
| Missing API Key | Red warning icon | "CurseForge API key not configured" | "Configure Now" → Admin panel |
| Invalid API Key | Red warning icon | "CurseForge API key invalid (check spelling)" | "Update Key" → Admin panel |
| API Rate Limited | Yellow warning icon | "API rate limit hit. Retrying in 60 seconds." | "Learn More" → Docs |
| License Invalid | Red warning icon | "License validation failed. Grace period: 5 days remaining." | "Update License" → Admin panel |
| Server Offline | Gray badge | "Server offline. Version check skipped." | No action |
| Manifest Not Found | Yellow badge | "No modpack manifest detected. Configure manually." | "Configure" → Console widget |

**Implementation:**
- Add error state enum to database
- Update badge component to show error icons
- Add tooltip text for each error state
- Link errors directly to fix location

---

#### **E) GitBook Knowledge Base** (1-2 hours)

**Why GitBook over GitHub README:**
- ✅ Searchable (users can find answers instantly)
- ✅ Professional appearance
- ✅ Screenshot support (better than markdown)
- ✅ SEO (Google indexes it)
- ✅ Analytics (see which docs are most-read)

**Migration Plan:**
1. Create free GitBook account (gitbook.com)
2. Port all 7 docs from markdown to GitBook:
   - README.md → Getting Started
   - INSTALLATION.md → Installation Guide
   - CONFIGURATION.md → API Key Setup
   - HOW-IT-WORKS.md → How Detection Works
   - MANUAL-CONFIGURATION.md → Manual Configuration
   - TROUBLESHOOTING.md → Troubleshooting
   - FAQ.md → Frequently Asked Questions
3. Add screenshots for each step
4. Enable search
5. Link from BuiltByBit listing: "📖 Full Documentation: [GitBook URL]"

**Structure:**
```
ModpackChecker Documentation
├── 🚀 Getting Started
├── 📦 Installation
├── 🔑 API Key Setup
│   ├── CurseForge
│   ├── Modrinth
│   └── FTB (manual only)
├── ⚙️ How It Works
│   ├── Tiered Detection System
│   ├── Egg Variables
│   ├── File Detection
│   └── Manual Configuration
├── 🛠️ Manual Configuration
│   ├── CurseForge
│   ├── Modrinth
│   ├── FTB
│   └── Technic
├── 🔍 Troubleshooting
│   ├── Badge is Gray
│   ├── API Rate Limits
│   ├── License Issues
│   └── Version Mismatches
└── ❓ FAQ
    ├── What platforms are supported?
    ├── Does it work with custom modpacks?
    ├── Can I use one license on multiple panels?
    └── How do I get support?
```

---

#### **F) BuiltByBit Listing Updates** (30 minutes)

**Add to Product Description:**

**Support Section:**
```markdown
## 🎟️ Support

Support is provided via our Discord server. 

**Response Time:** We aim to respond to all tickets within 24-48 business hours.  
**Support Hours:** Monday-Friday, 9 AM - 5 PM CST  
**Discord:** [Invite Link]

After purchase:
1. Join our Discord
2. Run `/verify-mvc [your-order-id]` 
3. Access #mvc-support and #mvc-general channels

📖 **Full Documentation:** [GitBook URL]
```

**Read Before You Buy Section (Bottom of Listing):**
```markdown
## ⚠️ Read Before You Buy

1. **License Validation:** This extension performs a lightweight validation check every 72 hours. If your panel cannot reach our validation server, you have a 7-day grace period before features are disabled.

2. **Multi-Panel Use:** Your license allows installation on up to 2 panels (e.g., dev + production). Contact support to increase this limit.

3. **Support Requirements:** Support is provided via Discord only. You must verify your purchase to access support channels.

4. **Vanilla Servers:** This extension will not auto-detect vanilla Minecraft servers (no modpack manifest exists).

5. **Manifest Dependency:** Auto-detection requires `manifest.json` (CurseForge) or `modrinth.index.json` (Modrinth) in server root.

6. **Exact String Matching:** Version comparison uses exact string matching, not semantic versioning. If modpack authors change naming formats, the extension will flag for your review.
```

---

#### **G) Business Hours & Boundaries** (Documentation Only)

**Gemini's Critical Warning:**
> "Do not answer tickets at 11 PM on a Saturday, even if you are awake and bored. You train your customers on how to treat you."

**Establish NOW (Before First Sale):**
- ✅ Support hours: Monday-Friday, 9 AM - 5 PM CST
- ✅ Response SLA: 24-48 business hours
- ✅ Weekend/holiday auto-responder: "Thanks for your ticket. Our team is away for the weekend/holiday. We'll respond on [next business day]."
- ✅ DO NOT answer tickets outside business hours (even if awake)
- ✅ DO NOT promise faster SLA (underpromise, overdeliver)

**Document in:**
- BuiltByBit listing
- Ticket Tool auto-responder
- GitBook FAQ
- Discord #mvc-general pinned message

---

#### **H) Future: Community Helper Program** (6-12 months post-launch)

**The Long-Term Sustainability Plan:**

After 6-12 months:
1. Identify the most helpful person in `#mvc-general`
2. Offer them:
   - ✅ Free access to all future extensions
   - ✅ "Community Helper" role (special color, permissions)
   - ✅ Recognition on website/docs
3. They handle Tier 1 support (setup questions, basic troubleshooting)
4. You handle Tier 2 support (code bugs, complex issues, feature requests)

**Benefits:**
- Reduces your support load by 50-70%
- Builds community loyalty
- Identifies potential future staff/moderators
- Creates "super users" who become advocates

**Document this strategy now** so future you remembers the plan.

---

**Deliverable (Phase 11 Complete):** 
- License validation system operational
- Discord verification bot functional
- Support channels gated and configured
- GitBook documentation published
- BuiltByBit listing updated with support info
- Business hours boundaries established
- Descriptive UI errors implemented

---

## 📋 COMPLETE FEATURE MATRIX

| Feature | Status | Priority | Time Estimate |
|---------|--------|----------|---------------|
| CurseForge auto-detection | ✅ Complete | Critical | Done |
| Modrinth auto-detection | ⏳ Phase 5 | Critical | 4-6 hours |
| Manual configuration UI | ✅ Complete | Critical | Done |
| Dashboard badge | ✅ Complete | Critical | Done |
| Console widget | ✅ Complete | Critical | Done |
| Admin panel | ✅ Complete | Critical | Done |
| "Ignore Version" button | ⏳ Phase 6 | Critical | 2-3 hours |
| Backoff logic | ⏳ Phase 7 | High | 1-2 hours |
| Documentation (Markdown) | ⏳ Phase 8 | Critical | 3-4 hours |
| BuiltByBit listing | ⏳ Phase 9 | Critical | 2-3 hours |
| Blueprint packaging | ⏳ Phase 10 | High | 2-3 hours |
| License validation API | ⏳ Phase 11 | Critical | 3-4 hours |
| Discord verification bot | ⏳ Phase 11 | Critical | 1-2 hours |
| Descriptive UI errors | ⏳ Phase 11 | Critical | 1 hour |
| GitBook migration | ⏳ Phase 11 | High | 1-2 hours |
| Gated support channels | ⏳ Phase 11 | Critical | 30 min |
| FTB auto-detection | 📦 v1.1 | Medium | 4-6 hours |
| Technic auto-detection | 📦 v1.1 | Low | 4-6 hours |

---

## ⏱️ TIME ESTIMATES

### **Minimum Viable Flagship (Launch-Ready)**
- Phase 5: Modrinth auto-detection — 4-6 hours
- Phase 6: "Ignore Version" feature — 2-3 hours
- Phase 7: Backoff logic — 1-2 hours
- Phase 8: Documentation (Markdown) — 3-4 hours
- Phase 9: BuiltByBit listing — 2-3 hours
- Phase 10: Blueprint packaging — 2-3 hours
- **Phase 11: Licensing & Support Infrastructure — 6-8 hours**

**Total: 20-29 hours** (3-4 work sessions)

### **Premium Flagship (Optional Enhancements)**
- In-panel Setup Wizard — 3-4 hours
- Video tutorials — 4-6 hours
- Beta testing program — 2-3 hours

**Total: 9-13 additional hours**

---

## 🎯 LAUNCH CRITERIA

Product is launch-ready when ALL of these are true:

### **Code Complete:**
- ✅ CurseForge auto-detection working
- ✅ Modrinth auto-detection working
- ✅ "Ignore Version" feature implemented
- ✅ Backoff logic prevents API spam
- ✅ Manual configuration UI functional
- ✅ Dashboard badge working (all states)
- ✅ Console widget working (all features)
- ✅ Admin panel working
- ✅ Descriptive UI error messages
- ✅ Clean install process documented/automated

### **Licensing & Support Complete:**
- ✅ License validation API operational
- ✅ 72-hour phone-home + 7-day grace period working
- ✅ Discord verification bot functional (`/verify-mvc`)
- ✅ `#mvc-general` channel created (peer support)
- ✅ `#mvc-support` ticket category configured (role-gated)
- ✅ Ticket Tool auto-responder with business hours
- ✅ BuiltByBit Order ID validation tested

### **Documentation Complete:**
- ✅ GitBook knowledge base published
- ✅ Getting Started guide
- ✅ Installation guide
- ✅ API Key Setup (CurseForge + Modrinth)
- ✅ How It Works (tiered system explanation)
- ✅ Manual Configuration (all platforms)
- ✅ Troubleshooting (common issues + solutions)
- ✅ FAQ (edge cases covered)

### **Marketing Complete:**
- ✅ BuiltByBit product description written
- ✅ Compatibility matrix included
- ✅ "Read Before You Buy" section added
- ✅ Support info clearly stated (24-48 hours, Discord-based)
- ✅ All 7 screenshots taken
- ✅ Pricing tier decided ($14.99 or $19.99)
- ✅ GitBook documentation link added

### **Testing Complete:**
- ✅ Tested on CurseForge pack (auto-detection)
- ✅ Tested on Modrinth pack (auto-detection)
- ✅ Tested on FTB pack (manual config)
- ✅ Tested on vanilla server (graceful failure + backoff)
- ✅ Tested "Ignore Version" button
- ✅ Tested offline server handling
- ✅ Tested API rate limiting
- ✅ Tested license validation (valid + invalid + grace period)
- ✅ Tested Discord verification bot
- ✅ Fresh install tested on clean panel

### **Support Ready:**
- ✅ Business hours established (Mon-Fri 9am-5pm CST)
- ✅ SLA documented (24-48 hours)
- ✅ Auto-responders configured
- ✅ Discord roles and channels configured
- ✅ GitBook documentation prevents 70% of tickets
- ✅ Descriptive UI errors reduce confusion
- ✅ Pre-ticket forms collect necessary info

---

## 🚀 SUGGESTED SESSION BREAKDOWN

### **Session 1 (Chronicler #64 - Today):**
- ✅ Gemini consultations (DONE)
- ⏳ Begin Phase 5: Modrinth auto-detection (4-6 hours)
- ⏳ Document this plan (DONE)

### **Session 2 (Chronicler #65):**
- Complete Phase 5: Modrinth auto-detection
- Complete Phase 6: "Ignore Version" feature
- Complete Phase 7: Backoff logic
- Begin Phase 8: Documentation skeleton

### **Session 3 (Chronicler #66):**
- Complete Phase 8: Full documentation
- Complete Phase 9: BuiltByBit listing
- Complete Phase 10: Blueprint packaging
- Final testing & screenshots
- **LAUNCH**

---

## 📞 SUPPORT STRATEGY (TBD)

Michael mentioned: *"there is something else I need done in regards to this and help with, but lets get everything in place before we address that, it isn't anything related to coding, but support"*

**Placeholder for future discussion:**
- Support ticket system/process?
- Response time commitments?
- Refund policy?
- Update/maintenance schedule?
- Community/Discord support channel?

**To be documented after product features are complete.**

---

## 💙 THE FLAGSHIP STANDARD

This is not just a product. This is Firefrost Gaming's introduction to the commercial marketplace.

Every decision prioritizes:
1. **Transparency** — No surprises, no refunds
2. **Quality** — Polished, tested, documented
3. **Support** — 70% of tickets prevented by docs
4. **Reputation** — "That dev ships quality"

**For children not yet born.**

---

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

---

**Document Status:** ACTIVE  
**Next Update:** After Phase 5 completion  
**Maintained By:** Current Chronicler