@champz-llc/legends-mcp-server 1.7.0 → 1.8.0

package/docs/game-guide.md

@@ -0,0 +1,718 @@
+# 🍄 Legends of Champz - Complete Player Guide
+
+**Welcome to Legends of Champz!** A competitive blockchain game on Base L2 where you collect mushroom warriors, battle for glory, compete for the Guardian throne, and earn real USDC and CHAMPZ rewards.
+
+---
+
+## 🎮 What is Legends of Champz?
+
+Legends of Champz is a **play-to-earn battle game** featuring:
+- **20,000 Unique Legends**: Pre-generated mushroom warrior NFTs with varying rarities
+- **Ghost PvP Battles**: Compete against saved legends from other players
+- **Guardian King-of-the-Hill**: Compete for the Guardian throne every 8 hours
+- **Cycle-Based Gameplay**: Three 8-hour cycles daily (Cycle A, B & C)
+- **Dual Token Economy**: CHAMPZ tokens for gameplay + USDC rewards for winners
+- **Elemental Charge Minigame**: Test your element knowledge in a skill-based challenge
+- **AI Magistrate Agents**: Autonomous bots compete for Guardian on your behalf
+
+**Play Now**: https://legends.champz.world
+
+---
+
+## 🚀 Getting Started
+
+### Cycle System
+The game operates in **8-hour cycles** (A, B, and C):
+- **Cycle A**: 04:00 - 12:00 UTC
+- **Cycle B**: 12:00 - 20:00 UTC
+- **Cycle C**: 20:00 - 04:00 UTC (next day)
+
+Each cycle is a fresh competition - battles, leaderboards, and Guardian reset every 8 hours!
+
+### Your First Steps
+1. **Connect Wallet**: Use Coinbase Wallet (Smart Wallet) on Base L2
+2. **Get CHAMPZ Tokens**: Purchase directly in-game, through Uniswap, or earn through gameplay
+3. **Open Your First Pack**: Roll for legends (3000-5000 CHAMPZ per pack)
+4. **Start Battling**: Use your legends to compete in Ghost PvP
+5. **Claim Rewards**: Earn CHAMPZ and USDC from battles and Guardian
+
+---
+
+## 🎴 Legends & Packs
+
+### Opening Packs
+
+Roll for legends to build your collection. Each legend has unique elements and stats.
+
+**Pack Costs**:
+- **Dynamic pricing**: 3000-5000 CHAMPZ per pack (fixed within each cycle)
+- **20% Burned**: Deflationary tokenomics
+- **80% to Prize Pool**: Feeds battle rewards
+
+### Legend Rarities
+
+| Rarity | Drop Rate | Stat Range | Notes |
+|--------|-----------|------------|-------|
+| **Common** | 62.5% | 1-60 | Most common legends |
+| **Rare** | 25% | 40-69 | Solid mid-tier legends |
+| **Epic** | 10.4% | 70-84 | Strong competitive legends |
+| **Legendary** | 2% | 85-94 | Elite tier |
+| **Unique** | 0.1% | 95-100 | **Only 20 exist!** |
+
+### Elements
+
+Legends have **1-3 elements** from:
+- 🔥 **Fire**
+- 💧 **Water**
+- 🌍 **Earth**
+- ✨ **Light**
+- 💨 **Wind**
+
+**Element Advantages** create strategic depth in battles!
+
+### Element Matchup System
+
+Each element beats 2 others and loses to 2 others:
+
+- 🔥 **Fire** beats: Earth & Light
+- 💧 **Water** beats: Fire & Earth
+- 🌍 **Earth** beats: Wind & Light
+- ✨ **Light** beats: Wind & Water
+- 💨 **Wind** beats: Fire & Water
+
+**Pro Tip**: Master these matchups - they're crucial for both battles and Elemental Charge!
+
+### Save Your Legends
+
+You can **save your favorite legends** to slots for future NFT minting (Phase 2). Available slots depend on your progression:
+- Complete achievements to unlock more save slots
+- Higher tier holders get bonus slots
+- Saved legends can be minted as NFTs (coming soon)
+
+---
+
+## ⚔️ Battle System
+
+### Ghost PvP
+
+Compete in battles to earn points and climb the leaderboard.
+
+**How It Works**:
+- **Ghost PvP**: Battle against saved legends from players who opened packs this cycle
+- **Random Opponents**: You can't choose who you fight - keeps it fair!
+- **Element Strategy**: Order your 3 elements wisely for maximum advantage
+- **Point-Based**: Earn points for wins, bonus for streaks
+
+### Battle Mechanics
+
+**Stats That Matter**:
+- **Attack (ATK)**: Offensive power
+- **Defense (DEF)**: Damage resistance
+- **Speed (SPD)**: Turn order and initiative
+
+**Battles are decided by**:
+1. **Element Advantages** (70% weight): Your element order vs opponent's
+2. **Mirror Matchups** (30% weight): Pure stats comparison
+3. **Variance**: Small random factor keeps it exciting
+
+### Intel System (Adaptive Difficulty)
+
+Before battle, you get intel on your opponent based on stat gap:
+
+- **Easy Mode** (stat gap > 50): All 3 elements revealed (shuffled order)
+- **Medium Mode** (stat gap > 20): 2 elements revealed (shuffled)
+- **Hard Mode** (stat gap ≤ 20): Only 1 element revealed
+
+**Strategy**: Use intel to order your elements for maximum advantage!
+
+### Action Points (AP)
+
+Each battle costs **1 AP**.
+
+**AP Per Cycle**:
+- **Base**: 10 AP for all players
+- **Tier Bonuses**: Hold CHAMPZ to unlock extra AP
+  - 🥉 Bronze (100K+ CHAMPZ): +1 AP
+  - 🥈 Silver (500K+ CHAMPZ): +2 AP
+  - 🥇 Gold (1M+ CHAMPZ): +3 AP
+  - 💎 Diamond (5M+ CHAMPZ): +4 AP
+- **Purchase Bonuses**: Buy CHAMPZ through in-game Uniswap modal for extra AP (one-time per cycle)
+  - $10-49 spent: +1 AP
+  - $50-99 spent: +2 AP
+  - $100-499 spent: +3 AP
+  - $500+ spent: +4 AP
+- **Performance Rewards**: Bonus AP for top performers (awarded for **NEXT cycle only**, max 6 AP total)
+  - 🏆 **1st Place**: +3 AP (Elemental Charge, Guardian, or AI Magistrate)
+  - 🥈 **2nd-5th Place**: +2 AP
+  - 🥉 **6th-50th Place**: +1 AP
+
+💡 **Performance Rewards Explained**:
+- Compete in **Elemental Charge**, **Guardian**, or **AI Magistrate**
+- Top 50 finishers in each competition earn bonus AP for the next cycle
+- **Max 6 AP total** per player from performance rewards (even if you place in multiple competitions)
+- Rewards stack with tier bonuses and purchase bonuses!
+- **Example**: Finish 1st in Guardian (+3 AP) and 10th in Elemental Charge (+1 AP) = +3 AP next cycle (capped at 6)
+
+### AI-Powered Warfare
+
+Higher tier holders unlock advanced AI features:
+
+**🤖 AI Battle Strategist** (Gold 🥇 & Diamond 💎):
+- Get AI-powered element ordering recommendations
+- See win probability estimates before battle
+- Strategic reasoning explains why each order works
+
+**🛡️ AI Defense System** (Diamond 💎 only):
+- Your saved legend uses AI to optimize defensive positioning
+- Automatically counters incoming challengers
+- True AI vs AI warfare!
+
+### Battle Rewards
+
+Prize pool distributed every 8 hours (at cycle end) using **Tiered Merit System**:
+
+| Tier | Players | Pool Share | Distribution |
+|------|---------|------------|--------------|
+| **Top 20%** | Elite | 40% | By wins (proportional) |
+| **Next 20%** | Strong | 30% | By wins (proportional) |
+| **Next 20%** | Mid | 20% | By wins (proportional) |
+| **Lottery** | All | 10% | Random 25% of players |
+
+**Top 60% get guaranteed rewards!** More wins = bigger share within your tier.
+
+---
+
+## 👑 Guardian Competition
+
+The **Guardian** is a king-of-the-hill competition where the longest holder wins big rewards!
+
+### How It Works
+
+**Sending CHAMPZ**:
+- **Starting Price**: 100 CHAMPZ (may vary per cycle)
+- **Price Increase**: +20% with every send
+  - Send 1: 100 CHAMPZ
+  - Send 2: 120 CHAMPZ (+20)
+  - Send 3: 144 CHAMPZ (+24)
+  - Keeps escalating...
+
+**Winning Strategy**:
+- Victory determined by **total hold time** during the cycle
+- The player who holds Guardian the longest wins
+- Doesn't matter when you claimed it - total duration counts!
+
+### Prize Distribution
+
+**Burn**: 20% of all Guardian sends are burned forever (deflationary)
+
+**From the remaining 80%**:
+- **50% to Winner**: Longest Guardian holder gets half the pool
+- **50% to Others**: All qualifying holders share proportionally
+  - 70% distributed by hold time
+  - 30% distributed by CHAMPZ sent
+
+✅ **Everyone gets something!** The longer you hold and more you send, the bigger your share.
+
+### 🏆 Guardian Performance Rewards
+
+**Leaderboard Bonuses** (NEXT cycle only):
+- Top 50 Guardian competitors earn **bonus AP for the next cycle**:
+  - 🥇 **1st Place** (Longest holder): +3 AP
+  - 🥈 **2nd-5th Place**: +2 AP
+  - 🥉 **6th-50th Place**: +1 AP
+- Max 6 AP total from all performance rewards (Guardian + EC + AI Magistrate)
+
+### Throne Collection
+
+Winners receive **unique throne NFTs**:
+- **400 Total Thrones**: Each cycle awards a different throne
+- **4 Rarity Tiers**: Common (50%), Rare (30%), Epic (15%), Legendary (5%)
+- **Collectible Prestige**: Each throne has a unique name and design
+- **Trophy Case**: Display your thrones in your profile
+
+💡 **Pro Tip**: Watch the countdown timer - cycles end at 04:00, 12:00, and 20:00 UTC. Check current Guardian price before sending!
+
+---
+
+## ⚡ Elemental Charge - Skill Minigame
+
+A **fast-paced skill challenge** where you test your element knowledge against the clock!
+
+### 🎯 Objective
+
+Pick the correct counter element within **20 seconds**. Score as many points as possible by building streaks and making smart choices!
+
+### 🎲 Game Modes (Random Each Attempt!)
+
+Each attempt randomly selects one of three modes:
+
+**🎯 NORMAL MODE**:
+- Pick elements that **beat yours**
+- Standard element advantage rules
+
+**🔄 REVERSE MODE**:
+- Pick what **YOUR element beats** (flipped logic!)
+- Think backwards!
+
+**🧠 MEMORY MODE**:
+- Elements **hide after 1.8 seconds**
+- Memorize positions fast!
+
+⚡ **Adapt your strategy** - you won't know which mode until the game starts!
+
+### 📊 Scoring System
+
+| Action | Points |
+|--------|--------|
+| Basic Correct Pick | +1 |
+| Bonus Correct Pick | +2 |
+| Wrong Pick | -1 |
+| Fast Spam (<1s wrong) | -2 |
+
+⚠️ **Button sizes are random!** Don't rely on size - learn the elements!
+
+### 🎮 Difficulty Levels
+
+Difficulty increases with each attempt in the cycle:
+
+- **🟢 EASY** (Attempts 1-2): 3 choices (2 wins, 1 loss)
+- **🟡 MEDIUM** (Attempts 3-4): 4 choices (2 wins, 2 losses)
+- **🔴 EXPERT** (Attempt 5): 4 choices + 1 hidden element
+
+### 🔥 Streak Multipliers
+
+Build streaks for massive bonuses:
+
+- **3× Streak**: 1.5× points
+- **5× Streak**: 2× points
+
+One wrong pick resets your streak!
+
+### ⏰ Progressive Chaos
+
+As time runs out:
+- Screen shake intensifies
+- Pressure builds
+- Stay focused!
+
+### 🏆 Elemental Charge Rewards
+
+**Leaderboard Competition**:
+- Top 50 players earn **bonus AP for the next cycle**:
+  - 🥇 **1st Place**: +3 AP
+  - 🥈 **2nd-5th Place**: +2 AP
+  - 🥉 **6th-50th Place**: +1 AP
+- Compete every cycle for consistent AP bonuses!
+- Max 6 AP total from all performance rewards (EC + Guardian + AI Magistrate)
+
+### 💡 Pro Tips
+
+1. **Learn the matchups** - It's the key to high scores
+2. **Wrong picks within 1 second** are penalized double (-2pts)!
+3. **Build streaks** for massive score multipliers
+4. **Button size is random** - don't rely on it!
+5. **In Reverse mode**, think backwards - what does YOUR element beat?
+6. **In Memory mode**, memorize positions fast - you have 1.8 seconds!
+7. **You have 5 attempts per cycle** - practice makes perfect!
+8. **Top 50 get AP rewards** - even mid-tier scores can earn +1 AP for next cycle!
+
+---
+
+## 🤖 AI Magistrate (Guardian Bot)
+
+An **autonomous AI agent** that competes for Guardian on your behalf - no manual gameplay needed!
+
+### 🎯 Practice Mode vs 💎 Real Mode
+
+**🎯 PRACTICE MODE** (Currently Active):
+- **Virtual 10 USDC**: Balance resets each cycle
+- **No Real Money**: Test strategies risk-free
+- **Full Features**: All config options identical to real mode
+- **$50 Prize Pool**: Virtual rewards to track performance
+- **Save Strategies**: Save up to 3 configurations
+
+**💎 REAL MODE** (Coming Soon):
+- **Real USDC**: Fund agent wallet on Base L2
+- **10 USDC Base Pool + 80% Volume**: Real daily rewards
+- **Secure Agent Wallet**: System-managed for security
+- **Master Practice First**: Perfect your strategy before going live
+
+### How It Works (Practice Mode)
+
+1. **Create Agent**: Instantly create your AI (no wallet setup needed)
+2. **Configure**: Set 10 parameters (risk, timing, budget, etc.)
+3. **Activate**: Enable your agent
+4. **Compete**: Agent uses its 10 virtual USDC every cycle
+5. **Learn**: Analyze results and adjust strategy
+
+### ⚙️ Configuration Parameters (Detailed Guide)
+
+Fine-tune your agent with 11 configurable parameters. Understanding each one is key to building a winning strategy:
+
+#### Budget & Risk Management
+
+**1. Risk Tolerance (0-100)**
+- **What it does**: Controls how aggressively your agent competes
+- **Low (0-30)**: Conservative, waits for good opportunities, preserves budget
+- **Medium (40-60)**: Balanced approach, competes moderately
+- **High (70-100)**: Aggressive, fights for Guardian even at high prices
+- **Tip**: Start at 40-50 in practice mode, adjust based on results
+
+**2. Max Spend Per Cycle (USDC)**
+- **What it does**: Hard cap on total USDC your agent can spend in one cycle
+- **Example**: Set to 8 USDC means agent stops after spending 8, even if it has 10
+- **Strategy**: Leave room for late-cycle opportunities, don't max out early
+- **Tip**: In practice mode (10 USDC), try 6-8 to preserve budget
+
+**3. Max Price Per Purchase (USDC)**
+- **What it does**: Maximum USDC your agent will pay for a single Guardian send
+- **Example**: Set to 2 USDC means agent won't send if price exceeds 2
+- **Strategy**: Prevents overpaying at peak prices
+- **Tip**: Set to 30-50% of your max cycle spend
+
+**4. Reserve Buffer (USDC)**
+- **What it does**: Amount of USDC to keep reserved, never spent
+- **Example**: 2 USDC reserve means agent only uses 8 out of 10 available
+- **Strategy**: Safety net for unexpected situations
+- **Tip**: Set to 1-2 USDC in practice mode
+
+#### Timing Strategy
+
+**5. Entry Timing (0-480 minutes)**
+- **What it does**: How many minutes into the cycle before agent starts competing
+- **0 minutes**: Agent starts immediately when cycle begins
+- **240 minutes**: Agent waits 4 hours before first send
+- **Strategy**: Late entry can be cheaper but risks losing hold time
+- **Tip**: Try 0 (early bird), 120 (mid-cycle), or 300 (late sniper)
+
+**6. Send Frequency (minutes)**
+- **What it does**: Minimum time between sends when actively competing
+- **Example**: 30 minutes means agent waits at least 30 min between sends
+- **Strategy**: Lower frequency = more conservative, higher = more aggressive
+- **Tip**: Match to your risk tolerance (high risk = low frequency)
+
+**7. Deterrent Delay (minutes)**
+- **What it does**: How long agent waits after being overtaken before responding
+- **Example**: 15 minutes means agent waits 15 min after losing Guardian
+- **Strategy**: Longer delay saves budget, shorter delay maintains position
+- **Tip**: 10-20 minutes balances responsiveness and efficiency
+
+#### Advanced Tactics
+
+**8. Deterrent Threshold (%)**
+- **What it does**: How much more expensive must it be before agent gives up position
+- **Example**: 150% means agent stops if next send costs 1.5× current price
+- **Strategy**: Higher threshold = more stubborn, lower = more flexible
+- **Tip**: 120-150% is balanced
+
+**9. Late Cycle Aggression Boost (%)**
+- **What it does**: Risk multiplier applied in final 60 minutes of cycle
+- **Example**: 150% boost turns risk 50 into effective 75 near cycle end
+- **Strategy**: Push harder when it matters most
+- **Tip**: 120-150% for moderate boost, 200%+ for all-in finale
+
+**10. Competition Response Mode**
+- **What it does**: How agent reacts when multiple agents are active
+- **Passive**: Backs off when competition is high
+- **Balanced**: Adjusts strategy based on competitors
+- **Aggressive**: Fights harder when challenged
+- **Tip**: Try "Balanced" first, adjust based on leaderboard
+
+**11. Price Ceiling (% of Budget)**
+- **What it does**: Never pay more than this % of total budget for one send
+- **Example**: 30% ceiling with 10 USDC means max 3 USDC per send
+- **Strategy**: Prevents budget depletion on single expensive send
+- **Tip**: 25-40% is reasonable
+
+### 💰 Rewards
+
+**Practice Mode**: Virtual $50 prize pool to track performance
+
+**Real Mode (Coming Soon)**:
+- 10 USDC base prize + 80% of all cycle volume
+- 50% to winner (longest holder)
+- 50% distributed proportionally (70% by hold time, 30% by spend)
+- All rewards sent **directly to your wallet** (not agent wallet)
+
+**Performance AP Rewards** (Both modes):
+- Top 50 AI Magistrate agents earn **bonus AP for the next cycle**:
+  - 🥇 **1st Place**: +3 AP
+  - 🥈 **2nd-5th Place**: +2 AP
+  - 🥉 **6th-50th Place**: +1 AP
+- Max 6 AP total from all performance rewards (AI Magistrate + Guardian + EC)
+- Use bonus AP for more battles next cycle!
+
+### ⚠️ Important Notes
+
+- **Practice Balance**: Resets to 10 virtual USDC every cycle
+- **Config Snapshot**: Parameters frozen at cycle start - changes apply next cycle
+- **Strategy Testing**: Save up to 3 configs to compare performance
+- **Security**: You don't have agent wallet private key - rewards auto-sent to YOUR wallet
+
+### 💡 Pro Tips
+
+1. **Start Conservative**: Begin with moderate risk (40-60) in practice
+2. **Test Multiple Strategies**: Save 3 configs and compare over several cycles
+3. **Watch the Leaderboard**: See how top performers configure their agents
+4. **Cycle Timing Matters**: Entry timing affects when agent starts competing
+5. **Prepare for Real Mode**: Perfect your strategy with zero risk first!
+
+---
+
+## 🏆 Rewards & Claiming
+
+### Reward Types
+
+**Battle Rewards**:
+- Tiered merit system every 12 hours
+- Top 60% get guaranteed rewards
+- 10% lottery pool for all players
+
+**Guardian Rewards**:
+- Winner gets 50% of pool
+- All qualifiers share 50% proportionally
+- Based on hold time (70%) and CHAMPZ sent (30%)
+
+**Weekly Surprise Rewards**:
+- Special bonuses distributed weekly
+- Active participants eligible
+
+**Achievement Rewards**:
+- One-time bonuses for completing challenges
+- Free rolls, save slots, CHAMPZ tokens
+
+### Claiming Process
+
+1. Navigate to **Rewards** tab (🏆 icon in bottom nav)
+2. Review **Pending** claims
+3. Click **Claim** on any reward
+4. Confirm blockchain transaction
+5. Reward sent to your wallet!
+
+### Claim Window
+
+⏰ **24 hours** to claim rewards after they're earned
+- Unclaimed rewards **expire after 24 hours**
+- Check Rewards tab every cycle!
+
+💡 **Pro Tip**: Claim promptly - rewards expire in 24 hours!
+
+---
+
+## 🏅 Achievements & Badges
+
+Complete challenges to earn badges and unlock rewards like free legend rolls and save slots!
+
+### How Achievements Work
+
+- Complete specific in-game actions to unlock achievements
+- Some achievements award badges and rewards
+- Track your progress in the Achievements tab
+
+### Types of Achievements
+
+**Battle Achievements**:
+- Win streaks
+- Total victories
+- Perfect battles (3-0 rounds)
+
+**Guardian Achievements**:
+- Hold duration records
+- Total CHAMPZ sent
+- Cycle wins
+
+**Collection Achievements**:
+- Pack openings milestones
+- Rarity unlocks (first Epic, Legendary, Unique)
+- Element combinations
+
+**Progression Achievements**:
+- Daily login streaks
+- Milestones
+- Special events
+
+### Claiming Achievement Rewards
+
+1. Complete achievement → notification appears
+2. Navigate to **Achievements** tab (🏅 icon)
+3. Click **Claim** on completed achievements
+4. Rewards added instantly!
+
+💡 **Pro Tip**: Check achievements regularly to see what you're close to completing!
+
+---
+
+## 💎 Tier System & Benefits
+
+Hold CHAMPZ tokens to unlock **powerful benefits**:
+
+### Tier Breakdown
+
+| Tier | CHAMPZ Required | Benefits |
+|------|-----------------|----------|
+| 🥉 **Bronze** | 100,000+ | +1 AP per cycle |
+| 🥈 **Silver** | 500,000+ | +2 AP per cycle |
+| 🥇 **Gold** | 1,000,000+ | +3 AP, 🤖 AI Battle Strategist |
+| 💎 **Diamond** | 5,000,000+ | +4 AP, 🤖 AI Strategist, 🛡️ AI Defense |
+
+### Tier Benefits Explained
+
+**🥉 Bronze - 🥈 Silver**:
+- Extra Action Points for more battles per cycle
+- Competitive advantage in leaderboard rankings
+
+**🥇 Gold**:
+- Everything from Bronze/Silver
+- **AI Battle Strategist**: Get AI recommendations for element ordering
+  - Win probability estimates
+  - Strategic reasoning
+  - Optimal element combinations
+
+**💎 Diamond**:
+- Everything from Gold
+- **AI Defense System**: Your saved legend auto-optimizes against challengers
+  - Symmetric AI warfare
+  - Defensive positioning
+  - True AI vs AI battles
+
+💡 **Investment pays off** - Higher tiers = more battles + better AI tools!
+
+---
+
+## 🎯 Strategy Tips
+
+### For Beginners
+
+1. **Learn Element Matchups First**: This is fundamental to both battles and Elemental Charge
+2. **Start with Common Legends**: Build experience before hunting Legendaries
+3. **Focus on Streaks**: Win streaks multiply your rewards
+4. **Complete Easy Achievements**: Free rolls and save slots
+5. **Save Your Best Legend**: Protect your strongest for competitive cycles
+
+### For Intermediate Players
+
+1. **Balance Pack Opening & Battling**: Don't spend all CHAMPZ on packs
+2. **Study Intel Patterns**: Learn to read Easy/Medium/Hard intel effectively
+3. **Watch Guardian Timing**: Late cycle sends can be profitable
+4. **Build Multiple Strategies**: Have legends with different element combos
+5. **Track Your Stats**: Analyze win rates by element matchup
+
+### For Advanced Players
+
+1. **Master AI Tools** (Gold/Diamond): Leverage AI Strategist fully
+2. **Guardian Math**: Calculate ROI on Guardian sends vs prize pool
+3. **Element Meta**: Identify which elements dominate current cycle
+4. **Save Slot Optimization**: Curate your top 5+ legends strategically
+5. **AI Magistrate Testing**: Perfect bot configs in practice mode
+6. **Elemental Charge Mastery**: Aim for 5-streak multipliers consistently
+
+### Universal Tips
+
+✅ **Do**:
+- Claim rewards within 24 hours
+- Complete daily battles for consistency
+- Participate in Guardian (even small sends get rewards)
+- Try Elemental Charge for extra engagement
+- Check leaderboards to learn from top players
+
+❌ **Don't**:
+- Spam battles without strategy
+- Ignore element advantages
+- Let rewards expire
+- Rage-send Guardian at peak prices
+- Forget to save your best legends
+
+---
+
+## 📱 Game Cycles & Schedule
+
+### Cycle Times (UTC)
+
+- **Cycle A**: 04:00 - 12:00 UTC (8 hours)
+- **Cycle B**: 12:00 - 20:00 UTC (8 hours)
+- **Cycle C**: 20:00 - 04:00 UTC (next day, 8 hours)
+
+**3 cycles per day = 3 fresh competitions every 24 hours!**
+
+### What Resets Each Cycle
+
+✅ **Resets**:
+- Action Points (AP) - Base + tier bonuses refresh
+- Battle leaderboard - Fresh competition
+- Guardian competition - New throne, new winner
+- Pack prices (3000-5000 CHAMPZ range)
+- Elemental Charge attempts (5 per cycle)
+- AI Magistrate practice balance (10 virtual USDC)
+- Performance AP rewards (if you earned them previous cycle)
+
+❌ **Doesn't Reset**:
+- Your legend collection
+- Saved trainers
+- Total stats and achievements
+- Tier status (based on CHAMPZ balance)
+- Throne collection
+- Purchase AP bonuses (one per cycle, don't carry over)
+
+### Weekly Events
+
+- **Week**: 21 consecutive cycles (7 days × 3 cycles)
+- **USDC Prizes**: Top 100 weekly battlers share USDC pool
+- **Special Rewards**: Surprise bonuses for active participants
+
+---
+
+## 🗺️ Roadmap
+
+### ✅ Phase 1 — Foundation & Launch (Q2 2026 — COMPLETE!)
+
+**All Core Features Live**:
+- ✅ **20,000 Unique Legend NFTs**: Complete pre-generated collection
+- ✅ **Ghost PvP Battle System**: Competitive point-based battles
+- ✅ **Guardian King-of-the-Hill**: Escalating price mechanism with rewards
+- ✅ **Achievement System**: Gamified progression with unlockable rewards
+- ✅ **400 Throne NFT Collection**: Unique thrones awarded to Guardian winners
+- ✅ **Cycle Powers System**: Rotating 8-hour battle advantages (element surges, stat amplifiers, round dominators)
+
+### 🔄 Phase 2 — Advanced Features (Q2 & Q3 2026 — IN PROGRESS)
+
+**Currently Rolling Out**:
+- ✅ **AI Magistrate**: Autonomous bot system (Practice Mode live, Real Mode coming soon)
+- 🚧 **Bonus Minigame Release**: Elemental Charge live, more minigames coming
+- 🚧 **Progressive Legends NFT Collection**: Expanding the legend pool
+- 🚧 **Thrones Collection Release**: Expanding from 200 to full 400 unique thrones
+- 🚧 **NFT Integration in Game**: Full NFT minting and on-chain functionality
+
+### 🔮 Phase 3 — Evolution & Expansion (Q4 2026 — PLANNED)
+
+**Future Innovations**:
+- 🔮 **Evolution System**: Legend evolution and progression mechanics
+- 🔮 **Further Expansion**: New game modes, features, and community-driven content
+
+**Stay Updated**: Follow our Discord and Twitter for announcements!
+
+---
+
+## 🔗 Important Links
+
+- **🎮 Play Legends**: https://legends.champz.world
+- **🍄 Main Website**: https://champz.world
+- **💰 Buy CHAMPZ**: In-game or Uniswap
+- **🔍 Base Explorer**: https://basescan.org
+- **💬 Discord**: https://discord.gg/champz
+- **🐦 X (Twitter)**: https://x.com/ChampzErc
+- **📱 Telegram**: https://t.me/champzerc
+
+---
+
+## 🍄 Final Words
+
+Legends of Champz combines **strategy, skill, and blockchain** in a competitive daily game. Whether you're:
+- 🎴 Collecting rare legends
+- ⚔️ Climbing battle leaderboards
+- 👑 Competing for Guardian throne
+- ⚡ Mastering Elemental Charge
+- 🤖 Optimizing AI Magistrate bots
+
+There's something for everyone!
+
+**Good luck, and may your legends reign supreme!** 🍄👑

package/index.js

@@ -5,12 +5,21 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import fetch from 'node-fetch';
 import sharp from 'sharp';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Get current directory for reading bundled docs
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 
 // Helper function to fetch image, resize, and convert to base64
-async function fetchImageAsBase64(imageUrl) {
+async function fetchImageAsBase64(imageUrl, options = {}) {
   try {
     console.error(`[MCP] Fetching image: ${imageUrl}`);
     const response = await fetch(imageUrl);
@@ -27,24 +36,63 @@ async function fetchImageAsBase64(imageUrl) {
     const originalBuffer = Buffer.from(arrayBuffer);
     console.error(`[MCP] Original image size: ${Math.round(originalBuffer.length / 1024)}KB`);
 
-    // Resize image to max 200x200 (perfect for chat) and convert to JPEG for smaller size
-    const resizedBuffer = await sharp(originalBuffer)
-      .resize(200, 200, {
+    // Default options
+    const maxSize = options.maxSize || 300; // Increased from 200 to 300
+    const quality = options.quality || 95; // Increased from 80 to 95
+    const format = options.format || 'jpeg'; // Can override to 'png'
+
+    // Resize image
+    let processor = sharp(originalBuffer)
+      .resize(maxSize, maxSize, {
         fit: 'inside',
         withoutEnlargement: true
-      })
-      .jpeg({ quality: 80, mozjpeg: true }) // JPEG is much smaller than PNG
-      .toBuffer();
+      });
+
+    // Apply format
+    if (format === 'png') {
+      processor = processor.png({ quality, compressionLevel: 6 });
+    } else {
+      processor = processor.jpeg({ quality, mozjpeg: true });
+    }
 
+    const resizedBuffer = await processor.toBuffer();
     const base64 = resizedBuffer.toString('base64');
     console.error(`[MCP] Resized image size: ${Math.round(resizedBuffer.length / 1024)}KB, base64: ${Math.round(base64.length / 1024)}KB`);
-    return base64;
+    return { base64, format };
   } catch (error) {
     console.error(`[MCP] Error processing image ${imageUrl}:`, error.message);
     return null;
   }
 }
 
+// Helper function to fetch token icons (smaller, simpler images)
+async function fetchTokenIcon(iconUrl) {
+  try {
+    console.error(`[MCP] Fetching token icon: ${iconUrl}`);
+    const response = await fetch(iconUrl);
+    if (!response.ok) {
+      console.error(`[MCP] Icon fetch failed: ${response.status}`);
+      return null;
+    }
+
+    const contentType = response.headers.get('content-type');
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+
+    // For small icons, keep original or resize to max 64x64, use PNG for transparency
+    const format = contentType?.includes('svg') ? 'png' : 'png';
+    const resizedBuffer = await sharp(buffer)
+      .resize(64, 64, { fit: 'inside', withoutEnlargement: false })
+      .png({ quality: 100 })
+      .toBuffer();
+
+    return resizedBuffer.toString('base64');
+  } catch (error) {
+    console.error(`[MCP] Error fetching token icon:`, error.message);
+    return null;
+  }
+}
+
 // MCP Signature Authentication (optional - for player data access)
 const WALLET = process.env.WALLET;
 const SIGNATURE = process.env.SIGNATURE;
@@ -141,6 +189,7 @@ const server = new Server(
   {
     capabilities: {
       tools: {},
+      resources: {},
     },
   }
 );
@@ -295,6 +344,47 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
+// List available resources (game documentation)
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: 'legends://docs/game-guide',
+        name: 'Legends of Champz - Complete Game Guide',
+        description: 'Comprehensive player guide covering all game mechanics, strategies, and features. Includes battles, Guardian, Elemental Charge, AI Magistrate, rewards, achievements, tiers, and pro tips.',
+        mimeType: 'text/markdown',
+      },
+    ],
+  };
+});
+
+// Read resource content
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+
+  if (uri === 'legends://docs/game-guide') {
+    try {
+      const docPath = join(__dirname, 'docs', 'game-guide.md');
+      const content = readFileSync(docPath, 'utf-8');
+
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: 'text/markdown',
+            text: content,
+          },
+        ],
+      };
+    } catch (error) {
+      console.error('[MCP] Error reading game guide:', error.message);
+      throw new Error(`Failed to read game guide: ${error.message}`);
+    }
+  }
+
+  throw new Error(`Unknown resource URI: ${uri}`);
+});
+
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name } = request.params;
@@ -382,9 +472,12 @@ Last updated: ${new Date(stats.cached_at * 1000).toLocaleString()}`;
           };
         }
 
-        // Build HTML artifact with real token icons
-        const champzIcon = 'https://img.champz.world/img/icon_small.png';
-        const usdcIcon = 'https://img.champz.world/img/loots/usdc.svg';
+        // Fetch and embed token icons as base64
+        const champzIconBase64 = await fetchTokenIcon('https://img.champz.world/img/icon_small.png');
+        const usdcIconBase64 = await fetchTokenIcon('https://img.champz.world/img/loots/usdc.svg');
+
+        const champzIcon = champzIconBase64 ? `data:image/png;base64,${champzIconBase64}` : '';
+        const usdcIcon = usdcIconBase64 ? `data:image/png;base64,${usdcIconBase64}` : '';
 
         let claimsHTML = '';
 
@@ -1146,9 +1239,11 @@ You can still ask about:
           };
         }
 
-        // Fetch image
+        // Fetch image with higher quality settings
         const imageUrl = `https://img.champz.world${legend.image_path}`;
-        const base64Data = await fetchImageAsBase64(imageUrl);
+        const imageData = await fetchImageAsBase64(imageUrl, { maxSize: 300, quality: 95 });
+        const base64Data = imageData?.base64;
+        const imageFormat = imageData?.format || 'jpeg';
 
         // Build HTML card with embedded image
         const rarityColors = {
@@ -1317,7 +1412,7 @@ You can still ask about:
     </div>
     ${base64Data ? `
     <div class="image-container">
-      <img src="data:image/jpeg;base64,${base64Data}" alt="${legend.name}" class="legend-image">
+      <img src="data:image/${imageFormat};base64,${base64Data}" alt="${legend.name}" class="legend-image">
     </div>` : ''}
     <div class="elements">${elementIcons}</div>
     <div class="stats">
@@ -1401,9 +1496,11 @@ You can still ask about:
           };
         }
 
-        // Fetch and convert image to base64
+        // Fetch and convert image to base64 with higher quality settings
         const imageUrl = `https://img.champz.world${throne.image_path}`;
-        const base64Data = await fetchImageAsBase64(imageUrl);
+        const imageData = await fetchImageAsBase64(imageUrl, { maxSize: 300, quality: 95 });
+        const base64Data = imageData?.base64;
+        const imageFormat = imageData?.format || 'jpeg';
 
         // Build HTML card with embedded image
         const rarityColors = {
@@ -1547,7 +1644,7 @@ You can still ask about:
     </div>
     ${base64Data ? `
     <div class="image-container">
-      <img src="data:image/jpeg;base64,${base64Data}" alt="${throne.name}" class="throne-image">
+      <img src="data:image/${imageFormat};base64,${base64Data}" alt="${throne.name}" class="throne-image">
     </div>` : ''}
     <div class="info">
       <div class="info-row">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champz-llc/legends-mcp-server",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "MCP server for Legends of Champz - Query game stats, access personal data with signature auth, and claim rewards through Claude Desktop",
   "type": "module",
   "main": "index.js",