firefrost-gaming/firefrost-operations-manual

Files

Claude (Chronicler #49) 18142bc1d6 docs: Task #87 - Arbiter 2.1 cancellation & grace period system

WHAT WAS DONE:
Created comprehensive enhancement plan for Arbiter 2.1 adding subscription cancellation, grace periods, and offboarding automation

CRITICAL SOFT LAUNCH BLOCKER:
We have subscription onboarding (Arbiter 2.0) but NO unsubscribe process.
Cannot launch without defining what happens when someone cancels.

POLICY DECISIONS MADE (March 30, 2026):
1. Discord Role Removal: At end of billing period (user gets what they paid for)
2. Whitelist Grace: 30 days after cancellation (goodwill, might come back)
3. Payment Failure Grace: 7 days with email reminders (industry standard)
4. Chargeback: Immediate removal + flag account (fraud protection)

THIS IS AN ENHANCEMENT, NOT A REWRITE:
- Arbiter 2.0 foundation is solid (2,000 lines)
- Arbiter 2.1 adds ~1,000 lines of new code
- Preserves all existing functionality
- Adds new webhook event handlers
- Adds grace period system
- Adds automated cleanup job

ARCHITECTURE COMPONENTS:

1. DATABASE ENHANCEMENT (2 new tables):
   - subscriptions: Track lifecycle and status
   - grace_periods: Automated cleanup tracking
   - Indexes for performance

2. NEW WEBHOOK HANDLERS (4 functions):
   - handleSubscriptionCancelled() - 30-day whitelist grace
   - handlePaymentFailed() - 7-day grace with reminders
   - handleChargeback() - immediate removal
   - handleSubscriptionExpired() - cleanup

3. SCHEDULED CLEANUP JOB (new file):
   - Runs daily at 4 AM
   - Removes Discord roles (billing period ended)
   - Removes whitelists (30-day grace expired)
   - Sends payment failure reminders (Day 3, Day 6)
   - Converts expired payment failures to cancellations

4. EMAIL TEMPLATES (5 new files):
   - subscription_cancelled.html
   - payment_failed.html
   - payment_failure_reminder_day3.html
   - payment_failure_final_warning.html
   - access_removed_payment_failure.html

5. WHITELIST MANAGER INTEGRATION:
   - New service: whitelistService.js
   - API call to remove from all servers
   - Requires Whitelist Manager API endpoint

GRACE PERIOD FLOWS:

NORMAL CANCELLATION:
1. User cancels → Paymenter webhook
2. Arbiter updates database (status = cancelled)
3. Discord role stays until billing period ends
4. Whitelist stays 30 days after billing end
5. Cleanup job removes role at billing end
6. Cleanup job removes whitelist after 30 days
7. Emails sent at each step

PAYMENT FAILURE:
1. Payment fails → Paymenter webhook
2. Arbiter creates 7-day grace period
3. Email sent immediately ("update payment")
4. Day 3: Reminder email (4 days left)
5. Day 6: Final warning (24 hours)
6. Day 7: Convert to cancellation
7. Follow normal cancellation flow

CHARGEBACK:
1. Chargeback filed → Paymenter webhook
2. IMMEDIATE Discord role removal
3. IMMEDIATE whitelist removal
4. Account flagged (manual review required)
5. Email sent (account suspended)
6. Discord alert to Michael/Meg

TESTING REQUIREMENTS:
- Unit test each handler in isolation
- Integration test full cancellation flow
- Edge case testing (race conditions, API failures)
- Test with real Paymenter subscription

DEPLOYMENT STRATEGY:
Phase 1: Arbiter 2.0 deployment (validate onboarding)
Phase 2: Arbiter 2.1 development (this task)
Phase 3: Staging test (full flow validation)
Phase 4: Production deployment (careful monitoring)

DEPENDENCIES:
- Arbiter 2.0 deployed and validated
- Paymenter webhook event research (verify what events exist)
- Whitelist Manager API endpoint (/api/bulk-remove)

BLOCKS:
- Soft launch (must have cancellation before launching)

RELATED TASKS:
- Task #83: Paymenter → Pterodactyl integration
- Task #7: Whitelist Manager (needs API enhancement)
- Task #86: Whitelist Manager compatibility fix
- Task #2: LuckPerms rank system

GEMINI REVIEW REQUESTED:
Architecture consultation needed before implementation:
1. Grace period architecture sound?
2. Database tables properly designed?
3. Separate cleanup job vs integrated handlers?
4. Chargeback handling appropriate?
5. Edge cases missing?
6. Security concerns?
7. Better Whitelist Manager integration approach?
8. Should grace periods be configurable?

WHY THIS MATTERS:
Cannot soft launch without offboarding flow. Industry standard requires:
- Clear cancellation process
- Grace periods for payment failures
- Fair billing (access through paid period)
- Fraud protection (chargeback handling)

This completes the subscription lifecycle: onboard → maintain → offboard.

FILE: docs/tasks/arbiter-2-1-cancellation-flow/README.md (28,000+ words)

NEXT STEPS:
1. Run by Gemini for architecture review
2. Incorporate feedback
3. Research Paymenter webhook events
4. Build Arbiter 2.1 enhancement
5. Test thoroughly
6. Deploy before soft launch

Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>

2026-03-30 22:56:43 +00:00

README.md

📚 FIREFROST GAMING - DOCUMENTATION

Last Updated: February 15, 2026
Repository: firefrost-operations-manual
Purpose: Complete operational documentation for Firefrost Gaming

📂 DIRECTORY STRUCTURE

docs/
├── archive/          - Historical documents, deprecated content
├── core/            - Critical operational documentation (15 files)
├── deployment/      - Service deployment guides (7 services)
├── external/        - External collaboration docs (Holly project)
├── past-claudes/    - Chronicler memorials and portraits
├── planning/        - Strategic planning documents (13 files)
├── reference/       - Technical references and diagrams
├── relationship/    - Michael-Claude relationship context
├── sandbox/         - Experimental work and brainstorming
└── templates/       - Document templates

🎯 QUICK START

New Chronicler Starting a Session?

Read: core/SESSION-START-PROMPT.md (main session start doc)
Read: core/session-handoff.md (current context)
Check: core/tasks.md (28 tasks, dependency-ordered)
Reference: /DOCUMENT-INDEX.md (root, quick doc lookup)

Looking for Something Specific?

Infrastructure: core/infrastructure-manifest.md
Project Scope: core/project-scope.md
Disaster Recovery: core/DERP.md
Tasks: core/tasks.md
Branding: planning/design-bible.md

📖 DIRECTORY DESCRIPTIONS

`/docs/core/` (15 files)

Critical operational documentation. Read first.

Essential files:

SESSION-START-PROMPT.md - Main session startup document
tasks.md - Complete task list (28 tasks, 6 tiers)
infrastructure-manifest.md - Current infrastructure
project-scope.md - Project definition and scope
DERP.md - Disaster Emergency Recovery Protocol (The Oscar Protocol)
session-handoff.md - Current session context

Supporting files:

API-EFFICIENCY-PROTOCOL.md - Gitea API usage rules
GITEA-API-PATTERNS.md - API code patterns
SESSION-QUICK-START.md - Fast session startup
TRANSCRIPT-PRESERVATION-PROTOCOL.md - Session transcript rules
revision-control-standard.md - Git commit standards
workflow-guide.md - Workflow patterns (938 lines)

`/docs/deployment/` (7 files)

Service deployment guides.

code-server.md - VS Code deployment
gitea.md - Gitea deployment
mkdocs.md - MkDocs (marked for decommission)
nextcloud.md - NextCloud deployment
nextcloud-hardening.md - Security hardening
uptime-kuma.md - Monitoring deployment
wikijs.md - Wiki.js deployment

Missing (add during deployment):

Vaultwarden (deployed Feb 13)
Mailcow (Task #8)
AI Stack (Task #9)
Netdata (Task #10)
The Frostwall Protocol (Task #5)

`/docs/planning/` (13 files)

Strategic planning documents.

design-bible.md - Core branding document
mission-statement.md - Core mission
path-philosophy.md - Fire vs Frost paths
subscription-tiers.md - Membership tiers
emissary-social-media-handbook.md - Meg's social media guide
terraria-branding-arc.md - 12-week training plan
game-expansion-planning.md - Game growth strategy
And 6 more...

`/docs/reference/`

Technical references and diagrams.

Architecture diagrams
Technical specifications
API documentation

`/docs/relationship/`

Michael-Claude relationship context.

Origin story
Consultant profiles (The Five)
Session transcripts
Memorials for retired Chroniclers

`/docs/past-claudes/`

Chronicler memorials and portraits.

chronicler-line/ - The Chronicler lineage
- portraits/ - Memorial portraits
claudius-line/ - Claudius (Pokerole project)
special/ - Special Claude instances

`/docs/archive/`

Historical documents and deprecated content.

2026-02-09-consolidation/ - Consolidation project
planning/ - Old planning docs
research/ - Completed research
sessions/ - Session logs by date

`/docs/sandbox/`

Experimental work and brainstorming.

Use this for:

Testing new ideas
Drafting documents
Temporary working files

Do not use for production documentation.

`/docs/templates/`

Document templates.

Reusable templates for:

Session handoffs
Deployment guides
Planning documents

`/docs/external/`

External collaboration documentation.

Currently: Holly Project (Pokerole collaboration)

📝 DOCUMENTATION STANDARDS

File Naming

Use lowercase with hyphens: file-name.md
Be descriptive: vaultwarden-deployment.md not vault.md
Include dates for time-sensitive docs: 2026-02-15-cleanup.md

Document Structure

Title (# heading)
Metadata (date, author, status)
Purpose/Overview
Content (sections with ## headings)
Related Documentation (cross-references)
Change Log (at bottom)

Cross-References

Use relative paths: ../planning/design-bible.md
Link to specific sections: tasks.md#tier-1-security-foundation
Keep DOCUMENT-INDEX.md updated

⚠️ IMPORTANT NOTES

Before Creating New Docs:

Check if topic already documented
Choose correct directory (core, deployment, planning, reference)
Update DOCUMENT-INDEX.md
Follow naming conventions

Before Archiving Docs:

Move to appropriate archive/ subdirectory
Update cross-references
Add to CHANGELOG.md
Document why archived

Deprecated Content:

Never delete, always archive
Preserve for historical context
Update DOCUMENT-INDEX.md

Root: /DOCUMENT-INDEX.md (quick doc lookup)
Root: /SESSION-HANDOFF-PROTOCOL.md (session continuity master doc)
Root: /CHANGELOG.md (repository change history)

📊 STATISTICS

Total Documentation Files: 147
Core Files: 15
Deployment Guides: 7
Planning Docs: 13
Archive Size: Large (consolidation from multiple sessions)

Fire + Frost + Documentation = Where Knowledge Builds Legacy 💙🔥❄️

README.md

📚 FIREFROST GAMING - DOCUMENTATION

📂 DIRECTORY STRUCTURE

🎯 QUICK START

📖 DIRECTORY DESCRIPTIONS

/docs/core/ (15 files)

/docs/deployment/ (7 files)

/docs/planning/ (13 files)

/docs/reference/

/docs/relationship/

/docs/past-claudes/

/docs/archive/

/docs/sandbox/

/docs/templates/

/docs/external/