decharge-scout 2.5.5 → 4.0.0

package/.env

@@ -0,0 +1,18 @@
+# EIA API Key (Required - Get from https://www.eia.gov/opendata/register.php)
+EIA_API_KEY=w0FzlyIlSkmb0Rw8H8IpxssShajZkQp9eT2sAZ0V
+
+# Solana Configuration
+SOLANA_NETWORK=devnet
+SOLANA_RPC_URL=https://api.devnet.solana.com
+
+# Mock Oracle Escrow Address (Replace with your test wallet for demo)
+ORACLE_ESCROW_ADDRESS=YourDevWalletPublicKeyHere
+
+# Dashboard API (Optional - for testing dashboard integration)
+DASHBOARD_API_URL=http://localhost:3000/submit
+
+# Stake Amount (in SOL)
+STAKE_AMOUNT=0.01
+
+# Premium Feature Price (in SOL)
+PREMIUM_PRICE=0.001

package/.env.example

@@ -1,5 +1,16 @@
-# EIA API Key (Required - Get from https://www.eia.gov/opendata/register.php)
+# Energy Data API Keys
+# Choose ONE based on your location (FREE options available!):
+#
+# 🇺🇸 USA (FREE): EIA API - Get from https://www.eia.gov/opendata/register.php
 EIA_API_KEY=your_eia_api_key_here
+#
+# 🇪🇺 Europe (FREE): ENTSO-E - Get from https://transparency.entsoe.eu/
+ENTSOE_API_KEY=your_entsoe_api_key_here
+#
+# 🇬🇧 UK (NO KEY NEEDED): Carbon Intensity API is completely FREE!
+#
+# 🌍 Global (PAID): Electricity Maps - Get from https://www.electricitymaps.com/
+ELECTRICITY_MAPS_API_KEY=your_electricity_maps_api_key_here
 
 # Solana Configuration
 SOLANA_NETWORK=devnet

package/README.md

@@ -1,6 +1,8 @@
-# DeCharge Scout
+# 🌍 Global Energy Scout
 
-AI-powered energy grid data scout with Solana blockchain integration. This CLI tool scouts public energy grid data, performs optimizations to find the cheapest EV charging windows, and submits anonymized results to a mock DeCharge oracle on Solana.
+**Weather-powered intelligent energy price forecasting with Solana blockchain integration.**
+
+This CLI tool uses **real-time weather data** to simulate energy grid pricing globally, helping you find the cheapest EV charging windows. No expensive APIs needed - completely FREE weather-based simulation that works worldwide!
 
 ## 🚀 Quick Install
 
@@ -14,22 +16,47 @@ Then run: `decharge-scout`
 
 [See more installation options →](ONE_COMMAND_INSTALL.md)
 
-## Features
-
-- **Real-time Energy Data**: Fetches live energy pricing and demand data from EIA and Electricity Maps APIs
-- **Smart Optimization**: Finds the cheapest charging windows in the next 24 hours
-- **Blockchain Integration**: Submits results to Solana devnet with anti-spam staking
-- **Points System**: Earn points for successful submissions and good optimizations
-- **Location Tracking**: Auto-detects location via IP for global dashboard visualization
-- **Premium Features**: x402 micropayments for enhanced forecast data
-- **Dashboard Ready**: Structured data output for global visualization
+## ✨ Features
+
+### 🌤️ **Weather-Powered Simulation** (NEW!)
+- **FREE** real-time weather data from Open-Meteo API (no key required!)
+- Simulates energy pricing based on:
+  - 🌡️ **Temperature** (AC/heating demand)
+  - 💨 **Wind speed** (renewable energy availability)
+  - ☀️ **Solar radiation** (solar energy generation)
+  - 🌙 **Time-of-day** patterns (peak/off-peak)
+- **50+ regional pricing models** (US, EU, IN, BR, JP, AU, etc.)
+- Intelligent insights explaining **why** certain times are cheaper
+
+### 🧠 **Smart Optimization**
+- Finds the cheapest 1-hour EV charging window in next 24 hours
+- Shows weather conditions at optimal time
+- Calculates potential savings (%)
+- Regional peak/off-peak pattern matching
+
+### 🌍 **Local Alpha Contribution**
+- Share your local grid knowledge (e.g., "7-9PM peak in Lagos")
+- Earn bonus points for contributing
+- Community-driven peak time database
+
+### ⛓️ **Blockchain Integration**
+- Submits results to Solana devnet with anti-spam staking
+- Points system for successful submissions
+- x402 micropayments for premium features (optional)
+
+### 🗺️ **Global Coverage**
+- Works **anywhere in the world**
+- Auto-detects location via IP
+- Custom location override supported
+- Dashboard-ready structured output
 
 ## Prerequisites
 
 - Node.js v20 or higher
-- A Solana wallet keypair file (JSON format)
-- EIA API key (free from https://www.eia.gov/opendata/register.php)
-- At least 0.02 SOL in your devnet wallet for staking + fees
+- **NO API KEYS REQUIRED!** 🎉
+  - Uses FREE Open-Meteo weather API (no registration needed)
+  - Works globally without any paid subscriptions
+- At least 0.02 SOL in your devnet wallet for staking + fees (auto-airdropped in setup)
 
 ## Installation
 
@@ -233,19 +260,47 @@ decharge-scout/
 
 ## API Data Sources
 
-### Primary: EIA API (ERCOT)
-- Endpoint: `https://api.eia.gov/v2/electricity/rto/region-data/data/`
-- Provides: Real-time demand and pricing for Texas (ERCOT)
-- Requires: Free API key from https://www.eia.gov/opendata/register.php
-
-### Secondary: Electricity Maps
-- Endpoint: `https://api.electricitymaps.com/v3/power-breakdown/latest`
-- Provides: Power grid forecasts and carbon intensity
-- Free tier available
-
-### Fallback: Mock Data
-- Generated locally if APIs are unavailable
-- Simulates realistic daily pricing patterns
+The CLI uses **smart routing** to automatically choose the best FREE API based on your location!
+
+### 🆓 FREE APIs (Recommended!)
+
+#### 🇺🇸 EIA API (US-only, FREE)
+- **Coverage**: United States only (ERCOT, CAISO, NYISO, PJM, MISO, ISNE)
+- **Endpoint**: `https://api.eia.gov/v2/electricity/rto/region-data/data/`
+- **Provides**: Real-time demand and pricing for US grid regions
+- **Get Key**: FREE at https://www.eia.gov/opendata/register.php
+- **Auto-used for**: Texas, California, New York, etc.
+
+#### 🇪🇺 ENTSO-E (Europe, FREE)
+- **Coverage**: All European countries
+- **Endpoint**: `https://web-api.tp.entsoe.eu/api`
+- **Provides**: Day-ahead electricity prices and demand forecasts
+- **Get Key**: FREE at https://transparency.entsoe.eu/
+- **Auto-used for**: Germany, France, Spain, Italy, Poland, Netherlands, Belgium, Austria
+- **Registration**: Free account required, instant approval
+
+#### 🇬🇧 UK Carbon Intensity (UK, FREE - No key needed!)
+- **Coverage**: United Kingdom only
+- **Endpoint**: `https://api.carbonintensity.org.uk`
+- **Provides**: Real-time carbon intensity and price forecasts
+- **Get Key**: No key needed! Completely open API
+- **Auto-used for**: UK locations (works out of the box!)
+
+### 💰 PAID API (Global fallback)
+
+#### 🌍 Electricity Maps (GLOBAL, PAID)
+- **Coverage**: Global (India, EU, UK, Australia, US, and more)
+- **Endpoint**: `https://api.electricitymaps.com/v3/carbon-intensity/forecast`
+- **Provides**: Carbon intensity forecasts and grid data for 200+ zones
+- **Get Key**: Paid API at https://www.electricitymaps.com/
+- **Auto-used for**: India, Australia, and regions not covered by free APIs
+- **Pricing**: Expensive - use only if free options don't cover your region
+
+### 📊 Mock Data (FREE - Always available!)
+- **Coverage**: Worldwide
+- **Generated**: Locally using realistic pricing patterns
+- **Auto-used**: When no API keys are configured or all APIs fail
+- **Perfect for**: Testing, demos, and development
 
 ## Points System
 
@@ -264,8 +319,17 @@ decharge-scout/
 
 ## Troubleshooting
 
-### "EIA_API_KEY not set"
-Get your free API key from https://www.eia.gov/opendata/register.php and add to `.env`
+### "EIA_API_KEY not configured" or "No energy data API keys configured"
+Choose an API based on your location:
+- **US users**: Get FREE EIA API key from https://www.eia.gov/opendata/register.php
+- **International users**: Get Electricity Maps API key from https://www.electricitymaps.com/
+- **Testing**: Press Enter to skip and use mock data
+
+Add your key to `.env`:
+```
+EIA_API_KEY=your_key_here                    # For US
+ELECTRICITY_MAPS_API_KEY=your_key_here       # For global
+```
 
 ### "Insufficient balance"
 Fund your devnet wallet:

package/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 /**
- * DeCharge Scout - Energy Grid Data Scout CLI
+ * Global Energy Scout - Intelligent Energy Price Forecasting CLI
+ * Powered by real-time weather data and smart simulation
  *
  * Main entry point for the CLI application that scouts energy grid data,
  * performs optimizations, and submits results to Solana blockchain.
@@ -26,18 +27,20 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 
-// Load environment variables
-dotenv.config();
+// Load environment variables from current working directory (not package dir)
+dotenv.config({ path: path.join(process.cwd(), '.env') });
 
 // Import modules
 import { startWalletServer, openWalletConnection, waitForWalletConnection, getConnectedWallet } from './src/wallet-server.js';
 import { setConnectedWallet, getBalance, checkBalance, mockStake, refundStake } from './src/browser-wallet.js';
-import { fetchEnergyData, fetchElectricityMapsData } from './src/energy-data.js';
+import { getWeatherForLocation } from './src/weather-data.js';
+import { generateSmartPricing, getPricingInsights, getRegionalPricing } from './src/smart-pricing.js';
 import { findCheapestWindow, calculateSavings } from './src/optimizer.js';
 import { submitToOracle } from './src/oracle.js';
 import { initializePoints, awardPoints, getPoints, savePoints } from './src/points.js';
 import { getLocation } from './src/geolocation.js';
 import { purchasePremiumData } from './src/x402.js';
+import { hasBeenAskedForAlpha, markAskedForAlpha, parseAlphaContribution, saveAlphaContribution, calculateAlphaBonus, getAlphaInsights, verifyContribution, getInformationSources } from './src/local-alpha.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -71,52 +74,52 @@ function generateAgentName() {
  * Auto-configure .env if needed
  */
 async function ensureEnvironment() {
-  const envPath = path.join(__dirname, '.env');
+  // Use current working directory for .env (so npx works correctly)
+  const envPath = path.join(process.cwd(), '.env');
 
   // Create .env from example if missing
   if (!existsSync(envPath)) {
+    // Look for .env.example in package directory
     const examplePath = path.join(__dirname, '.env.example');
     if (existsSync(examplePath)) {
       console.log(chalk.yellow('⚠️  .env file not found, creating from template...'));
       const example = readFileSync(examplePath, 'utf-8');
       writeFileSync(envPath, example);
-      console.log(chalk.green('✓ .env file created'));
-    }
-  }
-
-  // Check for EIA API key
-  if (!process.env.EIA_API_KEY || process.env.EIA_API_KEY === 'your_eia_api_key_here') {
-    console.log(chalk.yellow('\n⚠️  EIA_API_KEY not configured'));
-    console.log(chalk.blue('\n📝 How to get a FREE EIA API key:'));
-    console.log(chalk.gray('  1. Visit: https://www.eia.gov/opendata/register.php'));
-    console.log(chalk.gray('  2. Fill out the registration form'));
-    console.log(chalk.gray('  3. Check your email and verify your email address'));
-    console.log(chalk.gray('  4. Your API key will be sent to your email'));
-    console.log(chalk.gray('  5. Copy the API key and paste it below\n'));
-
-    const answer = await question('Enter your EIA API key (or press Enter to skip): ');
-
-    if (answer.trim()) {
-      // Update .env file
-      let envContent = readFileSync(envPath, 'utf-8');
-      envContent = envContent.replace(/EIA_API_KEY=.*/g, `EIA_API_KEY=${answer.trim()}`);
-      writeFileSync(envPath, envContent);
-
-      // Update process.env
-      process.env.EIA_API_KEY = answer.trim();
-
-      console.log(chalk.green('✓ API key saved to .env'));
+      console.log(chalk.green(`✓ .env file created at ${envPath}`));
     } else {
-      console.log(chalk.yellow('⚠️  Running without EIA API key (will use fallback data sources)'));
+      // Create a basic .env file if no example exists
+      const basicEnv = `# Energy Data API Keys
+# Choose ONE based on your location:
+# - EIA (FREE, US-only): Get from https://www.eia.gov/opendata/register.php
+# - Electricity Maps (GLOBAL, paid): Get from https://www.electricitymaps.com/
+EIA_API_KEY=your_eia_api_key_here
+ELECTRICITY_MAPS_API_KEY=your_electricity_maps_api_key_here
+
+# Solana Configuration
+SOLANA_NETWORK=devnet
+SOLANA_RPC_URL=https://api.devnet.solana.com
+
+# Stake Amount (in SOL)
+STAKE_AMOUNT=0.01
+`;
+      writeFileSync(envPath, basicEnv);
+      console.log(chalk.green(`✓ .env file created at ${envPath}`));
     }
   }
+
+  // Info: No API keys needed for weather-based simulation!
+  console.log(chalk.green('\n✅ Using FREE weather-based simulation (no API keys required!)'));
+  console.log(chalk.gray('   • Real-time weather data from Open-Meteo'));
+  console.log(chalk.gray('   • Smart pricing based on temperature, wind, solar radiation'));
+  console.log(chalk.gray('   • Regional patterns for accurate predictions\n'));
 }
 
 /**
  * Main CLI function
  */
 async function main(options) {
-  console.log(chalk.cyan.bold('\n🔋 DeCharge Scout - Energy Grid Data Scout\n'));
+  console.log(chalk.cyan.bold('\n🌍 Global Energy Scout - Intelligent Price Forecasting\n'));
+  console.log(chalk.gray('   Powered by real-time weather data & smart simulation'));
 
   try {
     // Auto-configure environment
@@ -169,49 +172,19 @@ async function main(options) {
       const detectedLocation = await getLocation();
       locationSpinner.succeed(chalk.green(`📍 Detected Location: ${detectedLocation}`));
 
-      // Ask user to confirm or override (with timeout)
+      // Ask user to confirm or override (no timeout - wait for input)
       console.log(chalk.blue('\nYou can use this location or enter a custom one.'));
-      console.log(chalk.gray('(Press Enter to use detected location, or type custom location)'));
-      console.log(chalk.gray('You have 30 seconds to respond...'));
+      console.log(chalk.gray('(Press Enter to use detected location, or type a custom location like "Dallas,TX,USA")'));
 
       try {
-        let timeoutId;
-        let hasResolved = false;
-
-        // Create a promise that auto-resolves after 30 seconds
-        const timeoutPromise = new Promise((resolve) => {
-          timeoutId = setTimeout(() => {
-            if (!hasResolved) {
-              hasResolved = true;
-              console.log(chalk.yellow('\n⏱️  Timeout - using detected location...'));
-              resolve('__TIMEOUT__');
-            }
-          }, 30000);
-        });
+        const customLocation = await question('Enter location (or press Enter for auto-detected): ');
 
-        const questionPromise = question('Enter custom location (or press Enter): ').then(answer => {
-          if (!hasResolved) {
-            hasResolved = true;
-            clearTimeout(timeoutId);
-            return answer;
-          }
-          return '__TIMEOUT__'; // If timeout already occurred, ignore this answer
-        });
-
-        const customLocation = await Promise.race([questionPromise, timeoutPromise]);
-
-        // If timeout occurred, use detected location
-        if (customLocation === '__TIMEOUT__') {
-          location = detectedLocation;
-          console.log(chalk.green(`✓ Using detected location: ${location}`));
+        // Use custom location if provided, otherwise use detected
+        location = customLocation.trim() || detectedLocation;
+        if (customLocation.trim()) {
+          console.log(chalk.green(`✓ Using custom location: ${location}`));
         } else {
-          // Use custom location if provided, otherwise use detected
-          location = customLocation.trim() || detectedLocation;
-          if (customLocation.trim()) {
-            console.log(chalk.green(`✓ Using custom location: ${location}`));
-          } else {
-            console.log(chalk.green(`✓ Using detected location: ${location}`));
-          }
+          console.log(chalk.green(`✓ Using detected location: ${location}`));
         }
       } catch (error) {
         console.log(chalk.yellow(`\n⚠️  Prompt error, using detected location: ${detectedLocation}`));
@@ -280,24 +253,31 @@ async function runQueryCycle(wallet, agentName, location, options) {
       console.log(chalk.cyan.bold(`🔍 Run #${totalRuns} - ${new Date().toLocaleString()}`));
       console.log(chalk.cyan(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`));
 
-      // Fetch energy data
-      const dataSpinner = ora('Fetching energy grid data...').start();
-      let energyData;
+      // Fetch weather data and generate smart pricing simulation
+      const weatherSpinner = ora('Fetching real-time weather forecast...').start();
+      let weatherData, energyData, countryCode;
 
       try {
-        energyData = await fetchEnergyData(location);
-        const gridRegion = energyData[0]?.source?.split('-')[1] || 'Unknown';
-        dataSpinner.succeed(chalk.green(`Fetched ${energyData.length} data points from ${energyData[0]?.source || 'EIA'}`));
-      } catch (error) {
-        dataSpinner.warn(chalk.yellow(`EIA API failed, trying Electricity Maps...`));
+        // Get real weather forecast from Open-Meteo (FREE!)
+        weatherData = await getWeatherForLocation(location);
+        countryCode = weatherData.location.country || 'DEFAULT';
+        weatherSpinner.succeed(chalk.green(`✓ Fetched ${weatherData.forecast.length}h weather forecast (FREE!)`));
+
+        // Generate intelligent pricing based on weather + regional patterns
+        const pricingSpinner = ora('Simulating energy grid pricing...').start();
+        energyData = generateSmartPricing(weatherData, countryCode);
+        pricingSpinner.succeed(chalk.green(`✓ Generated ${energyData.length} hours of smart pricing data`));
+
+        // Show pricing insights
+        const insights = getPricingInsights(energyData, countryCode);
+        console.log(chalk.blue(`\n💡 Smart Simulation Insights:`));
+        console.log(chalk.gray(`   Region: ${insights.region}`));
+        console.log(chalk.gray(`   Price range: $${insights.minPrice}-$${insights.maxPrice}/kWh (${insights.priceRange}% variation)`));
+        console.log(chalk.gray(`   Savings potential: ${insights.savingsPotential}% by timing your charge`));
 
-        try {
-          energyData = await fetchElectricityMapsData();
-          dataSpinner.succeed(chalk.green(`Fetched forecast data from Electricity Maps`));
-        } catch (fallbackError) {
-          dataSpinner.fail(chalk.red('All data sources failed'));
-          throw new Error('Unable to fetch energy data from any source');
-        }
+      } catch (error) {
+        weatherSpinner.fail(chalk.red('Failed to fetch weather data'));
+        throw new Error(`Unable to generate pricing simulation: ${error.message}`);
       }
 
       // Run optimization
@@ -306,12 +286,31 @@ async function runQueryCycle(wallet, agentName, location, options) {
       const savings = calculateSavings(energyData, cheapestWindow);
       optSpinner.succeed(chalk.green('Optimization complete'));
 
-      // Display results
+      // Display results with intelligent insights
       console.log(chalk.green.bold('\n✨ Optimization Results:'));
       console.log(chalk.white(`   Cheapest charge window: ${cheapestWindow.timeWindow}`));
       console.log(chalk.white(`   Price: $${cheapestWindow.price.toFixed(4)}/kWh`));
       console.log(chalk.white(`   Savings: ${savings.toFixed(1)}%`));
 
+      // Show why this time is cheap (weather-based reasons)
+      const cheapestHourData = energyData.find(d => d.hour === cheapestWindow.hour);
+      if (cheapestHourData && cheapestHourData.reasons) {
+        console.log(chalk.blue('\n🧠 Why this time is optimal:'));
+        cheapestHourData.reasons.forEach(reason => {
+          console.log(chalk.gray(`   • ${reason}`));
+        });
+
+        // Show weather conditions
+        if (cheapestHourData.weather) {
+          console.log(chalk.blue('\n🌤️  Weather conditions at optimal time:'));
+          console.log(chalk.gray(`   Temperature: ${cheapestHourData.weather.temperature.toFixed(1)}°C`));
+          console.log(chalk.gray(`   Wind: ${cheapestHourData.weather.windSpeed.toFixed(1)} m/s`));
+          if (cheapestHourData.hour >= 6 && cheapestHourData.hour <= 18) {
+            console.log(chalk.gray(`   Solar: ${cheapestHourData.weather.solarRadiation.toFixed(0)} W/m²`));
+          }
+        }
+      }
+
       // Prepare submission data
       const submissionData = {
         agent_name: agentName,
@@ -379,6 +378,95 @@ async function runQueryCycle(wallet, agentName, location, options) {
       console.log(chalk.magenta(`\n⭐ Earned ${totalPointsEarned} points! (${basePoints} base${bonusPoints > 0 ? ` + ${bonusPoints} bonus` : ''})`));
       console.log(chalk.magenta(`⭐ Total Points: ${currentPoints}`));
 
+      // Local Alpha Contribution (ask once after first run)
+      if (totalRuns === 1 && !hasBeenAskedForAlpha()) {
+        console.log(chalk.cyan('\n💡 Local Alpha Contribution - Help Improve Global Energy Data!'));
+        console.log(chalk.gray('   Share your local electricity peak time knowledge for bonus points.\n'));
+
+        // Show where to find this information
+        console.log(chalk.blue('📚 Where to find peak time information:'));
+        const sources = getInformationSources(location);
+
+        // General sources
+        sources.general.forEach(source => {
+          console.log(chalk.gray(`   ${source}`));
+        });
+
+        // Region-specific sources
+        const regionKeys = Object.keys(sources.byRegion);
+        if (regionKeys.length > 0) {
+          console.log(chalk.blue('\n📍 For your region:'));
+          regionKeys.forEach(region => {
+            sources.byRegion[region].forEach(source => {
+              console.log(chalk.gray(`   ${source}`));
+            });
+          });
+        }
+
+        console.log(chalk.blue('\n💬 Examples of good contributions:'));
+        console.log(chalk.gray('   • "7-9PM peak in Lagos" (evening peak)'));
+        console.log(chalk.gray('   • "1-5AM cheap in Berlin" (off-peak)'));
+        console.log(chalk.gray('   • "5-8PM peak in Mumbai" (dinner time surge)'));
+        console.log(chalk.gray('   • "2-6AM cheap in Texas" (wind energy overnight)\n'));
+
+        const alphaInput = await question(chalk.blue('Share local peak times (or press Enter to skip): '));
+
+        if (alphaInput.trim()) {
+          const parsed = parseAlphaContribution(alphaInput, location);
+          if (parsed) {
+            // Verify contribution against current pricing data
+            const verification = verifyContribution(parsed, energyData);
+
+            // Save contribution with verification status
+            const contribution = saveAlphaContribution(parsed, agentName, location, verification);
+
+            // Calculate bonus (higher for verified contributions)
+            const alphaBonus = calculateAlphaBonus(parsed, verification);
+
+            awardPoints(wallet, alphaBonus);
+
+            console.log(chalk.green(`\n✅ Thanks for contributing! Earned ${alphaBonus} bonus points!`));
+            console.log(chalk.gray(`   Contribution: ${parsed.type} hours ${parsed.startHour}-${parsed.endHour} in ${parsed.location}`));
+
+            // Show verification results
+            if (verification.verified) {
+              console.log(chalk.green(`   🎯 Verified! Confidence: ${(verification.confidence * 100).toFixed(0)}%`));
+              verification.reasons.forEach(reason => {
+                console.log(chalk.gray(`   ${reason}`));
+              });
+              console.log(chalk.green(`   +${alphaBonus - 10} extra points for verified contribution!`));
+            } else {
+              console.log(chalk.yellow(`   ⚠️  Low confidence: ${(verification.confidence * 100).toFixed(0)}%`));
+              verification.reasons.forEach(reason => {
+                console.log(chalk.gray(`   ${reason}`));
+              });
+              console.log(chalk.gray(`   Tip: Contributions that match actual price patterns earn more points!`));
+            }
+          } else {
+            console.log(chalk.yellow('⚠️  Could not parse contribution.'));
+            console.log(chalk.gray('   Accepted formats:'));
+            console.log(chalk.gray('   • "7-9PM peak in Lagos"'));
+            console.log(chalk.gray('   • "1-5AM cheap in Berlin"'));
+            console.log(chalk.gray('   • "19-21 peak Mumbai" (24-hour format also works)'));
+          }
+        }
+
+        markAskedForAlpha();
+      }
+
+      // Show alpha insights if available
+      if (totalRuns === 1) {
+        const alphaInsights = getAlphaInsights(location);
+        if (alphaInsights && alphaInsights.contributions > 0) {
+          console.log(chalk.cyan(`\n🌍 Community Knowledge for ${location}:`));
+          console.log(chalk.gray(`   ${alphaInsights.contributions} local contribution(s)`));
+          if (alphaInsights.commonPeakHours.length > 0) {
+            const topPeaks = alphaInsights.commonPeakHours.map(p => `${p.hour}:00`).join(', ');
+            console.log(chalk.gray(`   Most reported peak hours: ${topPeaks}`));
+          }
+        }
+      }
+
       // Premium upgrade option
       if (options.premium && totalRuns % 3 === 0) {
         console.log(chalk.yellow('\n🔒 Premium Feature Available!'));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "decharge-scout",
-  "version": "2.5.5",
-  "description": "AI-powered energy grid data scout with Solana integration",
+  "version": "4.0.0",
+  "description": "Global Energy Scout - Weather-powered intelligent energy price forecasting with Solana integration",
   "main": "index.js",
   "type": "module",
   "bin": {
@@ -20,7 +20,12 @@
     "blockchain",
     "ev-charging",
     "energy-optimization",
-    "ercot",
+    "weather",
+    "simulation",
+    "global",
+    "renewable-energy",
+    "smart-grid",
+    "price-forecasting",
     "web3"
   ],
   "author": "",