# User-facing commands
sparki forge                      # Enter Forgery interactive mode
sparki forge scan                 # Scan manuscript for domains
sparki forge quest <domain>       # Start quest for domain
sparki forge quest --tier 3       # Show only hard quests
sparki forge inventory            # Show achievements & stats
sparki forge leaderboard          # View leaderboard
sparki forge leaderboard team     # Team leaderboard (Team+)
sparki forge leaderboard global   # Global leaderboard (Pro+)
sparki forge guild create         # Create guild
sparki forge guild join <code>    # Join guild
sparki forge tournament           # View/create tournaments
sparki forge ritual sync          # Run sync ritual
sparki forge transmute <domain>   # Evolve domain tier
sparki forge crucible <scenario>  # Network stress test (Pro+)
sparki forge lore                 # Read smithy lore
sparki forge dashboard            # View stats & recommendations
sparki forge upgrade tier         # Upgrade subscription

╔═════════════════╦═════════════╦═══════════╦═════════╦════════════╗
║ Feature         ║ Community   ║ Team      ║ Pro     ║ Enterprise ║
╠═════════════════╬═════════════╬═══════════╬═════════╬════════════╣
║ Price           ║ $0          ║ $25/mo    ║ $99/mo  ║ Custom     ║
║ Concurrent      ║ 1 quest     ║ 3 quests  ║ 10      ║ Unlimited  ║
║ Max Quests/Day  ║ 5           ║ 20        ║ ∞       ║ ∞          ║
║ Guild Size      ║ 5 members   ║ 25        ║ 100     ║ ∞          ║
║ Team Features   ║ ✗           ║ ✓         ║ ✓       ║ ✓          ║
║ Persistence     ║ None        ║ 7 days    ║ 90 days ║ ∞          ║
║ Crucible        ║ ✗           ║ ✗         ║ ✓       ║ ✓          ║
║ Tournaments     ║ ✗           ║ ✗         ║ ✓       ║ ✓          ║
║ Global Board    ║ ✗           ║ ✗         ║ ✓       ║ ✓          ║
║ Marketplace     ║ ✗           ║ ✗         ║ ✓       ║ ✓          ║
║ White Label     ║ ✗           ║ ✗         ║ ✗       ║ ✓          ║
╚═════════════════╩═════════════╩═══════════╩═════════╩════════════╝

TIER 1: APPRENTICE (Smoke Tests)
├─ Difficulty:   Easy
├─ Duration:     2-5 minutes
├─ XP Reward:    50-100 base
├─ Tests:        Proto compile, imports, exports
├─ Example:      "Forge the User Domain"
└─ Use Case:     New players, quick wins

TIER 2: JOURNEYMAN (Integration Tests)
├─ Difficulty:   Medium
├─ Duration:     10-30 minutes
├─ XP Reward:    250-500 base (×complexity)
├─ Tests:        Cross-domain imports, serialization
├─ Example:      "User Domain Integration"
└─ Use Case:     Build understanding, level up

TIER 3: MASTER (Network Trials)
├─ Difficulty:   Hard
├─ Duration:     30 minutes - 2 hours
├─ XP Reward:    1,000-2,500 base (×complexity)
├─ Tests:        Load testing, latency injection, timeouts
├─ Example:      "User Domain Under Fire"
└─ Use Case:     Expert players, leaderboards

TIER 4: LEGEND (Transmutation Rituals)
├─ Difficulty:   Extreme
├─ Duration:     2-4 hours
├─ XP Reward:    5,000+ base (×complexity)
├─ Tests:        Full system integration, compliance
├─ Example:      "The User Ascension"
└─ Use Case:     Masters, prestige ranking

BASE_XP = {
  50:    Smoke test
  250:   Integration test
  1000:  Network trial
  5000:  Transmutation
}

MULTIPLIER = DIFFICULTY × COMPLEXITY × SPEED × STREAK

Examples:
  User smoke test, normal pace:
    50 × 1.0 × 1.0 × 1.0 × 1.0 = 50 XP

  User integration, 2x faster, 7-day streak:
    250 × 1.5 × 1.5 × 1.3 × 1.1 = 810 XP

  Document network trial, normal, team synergy:
    1000 × 2.5 × 1.8 × 1.0 × 1.2 = 5,400 XP

  Collaboration transmutation, speedrun, legendary:
    5000 × 5.0 × 2.0 × 1.3 × 1.5 = 97,500 XP

Level  XP Required  Cumulative  Title                 Unlocks
──────────────────────────────────────────────────────────────────
1      0            0           Novice Smith          First quest
2      1,000        1,000       Apprentice Smith      (Auto)
3      1,150        2,150       Skilled Smith         Integration
4      1,323        3,473       Journeyman Smith      (Auto)
5      1,521        4,994       Expert Smith          Guilds
6      1,750        6,744       Master Smith          (Auto)
7      2,012        8,756       Grand Master          (Auto)
8      2,313        11,069      Legendary Smith       Leaderboards
9      2,661        13,730      Mythic Smith          (Auto)
10     3,059        16,789      Ascended Smith        (Auto)
...
20     52,000+      ...         Grandmaster +5        Crucible
...
50     2,000,000+   ...         Prestige Ascended     Prestige

Community User
  ↓
Level 5 Unlock: Guilds
  ├─ Modal: "Create a guild!"
  ├─ Benefit highlight: Team features
  └─ CTA: "Upgrade to Team - $25/mo" [7-day free trial]
  ↓
[Trial Converts to Team] → 70% trial-to-paid rate
  ↓
Team User
  ├─ Enjoys collaborative features
  ├─ Joins guild tournament
  └─ Sees Pro tier features needed
  ↓
Level 20 Unlock: Crucible
  ├─ Modal: "Advanced testing unlocked!"
  ├─ Feature: Stress testing, marketplace
  └─ CTA: "Upgrade to Pro - $99/mo" [30-day free trial]
  ↓
[Trial Converts to Pro] → 60% trial-to-paid rate
  ↓
Pro User
  ├─ Uses marketplace
  ├─ Hosts tournaments
  ├─ Competes globally
  └─ Engagement 3x+ vs community
  ↓
Enterprise Option
  └─ $2K-20K/mo custom contracts

┌─ XP & Leveling ─────────────────────────────────┐
│ Base XP × Multipliers → Level progression       │
│ Level 1-50 → Prestige system for infinite play  │
└─────────────────────────────────────────────────┘

┌─ Achievements ──────────────────────────────────┐
│ Progression: Level milestones                   │
│ Performance: Speed runs, perfect scores         │
│ Social: Guilds, mentoring, tournaments          │
│ Mastery: Complete all domain quests             │
│ Secret: Hidden easter eggs                      │
└─────────────────────────────────────────────────┘

┌─ Leaderboards ──────────────────────────────────┐
│ Community: Local (free) - see who you know      │
│ Team: Collaborative (Team+) - beat other teams  │
│ Global: All-time (Pro+) - ultimate prestige     │
│ Seasons: Monthly resets + seasonal themes       │
└─────────────────────────────────────────────────┘

┌─ Guilds & Social ───────────────────────────────┐
│ Create: Requires level 5, 3+ members            │
│ Roles: Founder, officer, member                 │
│ Treasury: 5% of member XP → guild pool          │
│ Tournaments: Guild-level tournaments            │
│ Vault: Share artifacts (Pro+)                   │
└─────────────────────────────────────────────────┘

┌─ Streaks & Momentum ────────────────────────────┐
│ Daily Streak: 3, 7, 14, 30+ day milestones     │
│ Momentum Meter: Team bonus (0-100%)             │
│ Bonus XP: 1.5x at peak momentum                 │
│ Decay: 2% per day inactive                      │
└─────────────────────────────────────────────────┘

SETUP (Week 1-2)
  ☐ Create Polar merchant account
  ☐ Set up tax compliance
  ☐ Configure payout bank account
  ☐ Review Polar API documentation
  ☐ Get webhook secret & API keys

IMPLEMENTATION (Week 2-3)
  ☐ Implement checkout flow
  ☐ Create Polar product records (Team, Pro, Enterprise)
  ☐ Build feature flag system
  ☐ Implement webhook handlers
  ☐ Add subscription status check

TESTING (Week 4)
  ☐ Test checkout flow with test card
  ☐ Verify webhook delivery
  ☐ Test feature upgrades
  ☐ Verify Polar fees calculation
  ☐ Test churn/cancellation flows

LAUNCH (Week 5)
  ☐ Enable production in Polar
  ☐ Set up monitoring/alerts
  ☐ Create support documentation
  ☐ Announce tier system
  ☐ Begin gradual rollout (5% users)

POST-LAUNCH
  ☐ Monitor conversion rates
  ☐ Track churn metrics
  ☐ Optimize pricing/positioning
  ☐ Build win-back campaigns
  ☐ Expand to annual billing

DOMAIN DISCOVERY
  ☐ Proto file scanner (.msx/domains/*.proto)
  ☐ Message extractor (events, fields)
  ☐ Complexity calculator
  ☐ Dependency resolver
  ☐ Caching system (checksums)

QUEST GENERATION
  ☐ Tier 1 (Smoke) test generator
  ☐ Tier 2 (Integration) test generator
  ☐ Tier 3 (Network) test generator
  ☐ Tier 4 (Transmutation) test generator
  ☐ XP calculator per quest

SYNC & UPDATES
  ☐ Scribe webhook listener
  ☐ Change detection algorithm
  ☐ Quest update logic
  ☐ Player notification system
  ☐ Progress reset logic

VALIDATION
  ☐ Local quest runner
  ☐ Quality metrics (duration, difficulty)
  ☐ Integration test suite
  ☐ Peer review process (first 10)
  ☐ Community beta testing

SCALABILITY
  ☐ Domain grouping (20+ events)
  ☐ Caching & checksums
  ☐ Async quest generation
  ☐ Database indexing
  ☐ Performance monitoring

ENGAGEMENT (Real-time)
  DAU:                   [Target: 5,000 by Month 6]
  Avg Session Length:    [Target: 25+ min]
  7-Day Retention:       [Target: 70%]
  Quest Completion Rate: [Target: 80%+]
  Streak Participation:  [Target: 60%]

MONETIZATION (Weekly)
  Community Users:       [Target: 20,000 by Month 6]
  Team Subscribers:      [Target: 1,500 by Month 6]
  Pro Subscribers:       [Target: 100 by Month 6]
  MRR:                   [Target: $50,000 by Month 6]
  Trial Conversion:      [Target: 20%+]
  Churn Rate:            [Target: <5% monthly]

COMMUNITY (Weekly)
  GitHub Stars:          [Target: 2,000 by Month 6]
  Community PRs:         [Target: 15+/month by Month 6]
  Discord Members:       [Target: 1,000+ by Month 3]
  Issues Response Time:  [Target: <24h]

QUALITY (Daily)
  System Uptime:         [Target: 99.9%]
  Quest Completion Time: [Target: within ±10% estimate]
  Player Satisfaction:   [Target: 4.0+/5.0 stars]
  Bug Report Rate:       [Target: <2% of sessions]

LICENSING
  Core Code:             Apache-2.0 (open, forkable)
  Proprietary Features:  Cloud services (Polar integrated)
  Trademark:             "Forgery by Sparki" ™ (protected)
  Community:             May fork, must credit

DECISION MAKING
  Major Features:        Steering Committee vote
  Tier Gating:           Fairness assessment
  Licensing Changes:     Community consent
  Roadmap:               Public, community input

STEERING COMMITTEE
  Members:               7 elected (annual rotation)
  Composition:           3 Sparki + 3 Community + 1 Customer
  Frequency:             Monthly meetings
  Transparency:          Public meeting notes

CONTRIBUTION PATH
  Bug Fixes:             Direct PRs welcome
  Features:              Discuss in issues first
  Domains/Quests:        Community-contributed
  Lore/Cosmetics:        Open for creativity
  Revenue Share:         10% for cosmetic sales

USER FLOW (20-minute integration test)

1. START (2 min)
   ├─ Player clicks "User Domain Integration"
   ├─ Quest loads with context narrative
   ├─ TUI shows "Ignition Phase - 10%"
   └─ "Compiling domain proto..."

2. IGNITION (3 min)
   ├─ TUI: "Validating schemas... ✓"
   ├─ TUI: "Preparing test fixtures... ✓"
   ├─ TUI: "Starting forge... ✓"
   └─ Progress: 40%

3. TEMPERING (12 min)
   ├─ TUI shows test progress in real-time
   ├─ Test 1/5: "Proto serialization" ✓ (2.3ms)
   ├─ Test 2/5: "Cross-domain imports" ✓ (1.8ms)
   ├─ Test 3/5: "Event ordering" ✓ (3.1ms)
   ├─ Test 4/5: "Message round-trip" ✓ (1.5ms)
   ├─ Test 5/5: "Dependency resolution" ✓ (2.0ms)
   └─ Progress: 95%

4. INSPECTION (3 min)
   ├─ TUI: Final results displayed
   ├─ ✓ 5/5 tests PASSED
   ├─ ⏱ Total time: 18m 45s (vs 20m estimated)
   ├─ 🏅 Achievement Unlocked: "Speedrunner"
   ├─ +375 XP earned
   ├─ +50 XP bonus (achievement)
   ├─ Total: 425 XP
   ├─ Level progress: 8,450 → 8,875 / 50,250 XP
   ├─ Leaderboard: You: Rank 47 (team), +2 this week
   └─ Motivation: "Next level in ~42 hours. Keep forging!"

5. CONTINUE OR RELAX
   ├─ CTA: "Start another quest?"
   ├─ CTA: "Check leaderboard?"
   ├─ CTA: "Hang out in guild?"
   └─ CTA: "Exit forge"

PROBLEM: "Quest takes too long"
SOLUTION:
  ├─ Check tier (Tier 4 takes 2-4h by design)
  ├─ Run locally vs cloud (network latency?)
  ├─ Check for infrastructure bottlenecks
  └─ Adjust difficulty in next iteration

PROBLEM: "Not earning enough XP"
SOLUTION:
  ├─ Speed bonus: Complete quests faster
  ├─ Streak bonus: Play daily for multiplier
  ├─ Complexity factor: Try harder domains
  ├─ Achievements: Unlock for bonus XP
  └─ Crucible: Pro tier 5000+ XP per session

PROBLEM: "Too many players on leaderboard"
SOLUTION:
  ├─ Seasonal resets (monthly)
  ├─ Tier separation (community vs team vs global)
  ├─ Time windows (daily, weekly, all-time)
  └─ Prestige system for veterans

PROBLEM: "Polar webhook not firing"
SOLUTION:
  ├─ Check webhook secret configured
  ├─ Verify endpoint URL is public
  ├─ Check logs for 404 errors
  ├─ Test with Polar dashboard
  └─ Verify signature validation code

PROBLEM: "Guild members can't see shared vault"
SOLUTION:
  ├─ Confirm all users on Pro+ tier
  ├─ Check guild permissions
  ├─ Verify database sync
  └─ Restart service if needed

MONTH 1: Foundation
  Week 1:   Team kickoff, GitHub setup, architecture review
  Week 2:   Core engine implementation
  Week 3:   Smith engine + XP system
  Week 4:   Bubbletea TUI, closed beta signup opens

MONTH 2: Gamification
  Week 5:   Leaderboards, guilds, achievements
  Week 6-7: Tournaments, cosmetics, polish
  Week 8:   Community alpha (50 users)

MONTH 3: Monetization + Launch
  Week 9:   Polar integration
  Week 10:  Feature flags, tier gating
  Week 11:  Testing, compliance review
  Week 12:  PUBLIC BETA LAUNCH

MONTH 4-6: Growth
  Month 4:  Community tier: 5,000+ users
            MRR: $12,500
  Month 5:  Community tier: 15,000+ users
            MRR: $50,000
  Month 6:  Community tier: 20,000+ users
            MRR: $75,000+

Documentation:
  ├─ FORGERY-SPEC-001 (core system design)
  ├─ FORGERY-GAMIFICATION-001 (mechanics)
  ├─ FORGERY-POLAR-MONETIZATION-001 (business)
  ├─ FORGERY-DOMAIN-SYNC-001 (manuscript integration)
  └─ FORGERY-OPEN-SOURCE-SUSTAINABILITY-001 (strategy)

External Resources:
  ├─ Polar.sh API docs
  ├─ Bubbletea TUI framework
  ├─ Apache-2.0 license text
  └─ Sparki.tools main documentation

Community Platforms:
  ├─ GitHub: sparki/forgery
  ├─ Discord: #forgery-dev
  ├─ Twitter: @sparki_tools
  └─ Community Forum: community.sparki.tools/forgery