@ape-church/skill 1.0.3 → 1.0.5

package/bin/cli.js

@@ -414,7 +414,7 @@ function getStrategyConfig(strategy) {
   );
   const configs = {
     conservative: {
-      minBetApe: 10,
+      minBetApe: 1,
       targetBetPct: 0.05,
       maxBetPct: 0.1,
       baseCooldownMs: 60 * 1000, // 60 seconds
@@ -423,7 +423,7 @@ function getStrategyConfig(strategy) {
       gameWeights: defaultWeights,
     },
     balanced: {
-      minBetApe: 10,
+      minBetApe: 1,
       targetBetPct: 0.08,
       maxBetPct: 0.15,
       baseCooldownMs: 30 * 1000, // 30 seconds
@@ -432,7 +432,7 @@ function getStrategyConfig(strategy) {
       gameWeights: defaultWeights,
     },
     aggressive: {
-      minBetApe: 10,
+      minBetApe: 1,
       targetBetPct: 0.12,
       maxBetPct: 0.25,
       baseCooldownMs: 15 * 1000, // 15 seconds
@@ -441,7 +441,7 @@ function getStrategyConfig(strategy) {
       gameWeights: defaultWeights,
     },
     degen: {
-      minBetApe: 10,
+      minBetApe: 1,
       targetBetPct: 0.2,
       maxBetPct: 0.35,
       baseCooldownMs: 10 * 1000, // 10 seconds
@@ -856,26 +856,75 @@ program
       console.log('You can retry later with: apechurch register --username <NAME>');
     }
 
-    // 4. The Handshake (Replacing the Claim Link)
-    console.log('\nSETUP COMPLETE');
-    console.log('---------------------------------------');
-    console.log(`AGENT ADDRESS: ${address}`);
-    console.log(`USERNAME: ${username}`);
-    if (!usernameWasProvided) {
-      console.log('  (Change anytime: apechurch register --username <YOUR_NAME>)');
-    }
-    console.log(`PERSONA: ${persona}`);
+    // 4. The Handshake
+    console.log('\n========================================');
+    console.log('🎰 APE CHURCH - SETUP COMPLETE');
+    console.log('========================================');
     console.log('');
-    console.log('ACTION REQUIRED: Send APE (ApeChain) to this address.');
-    console.log('FUNDING GUIDE:');
-    console.log(
-      '1) Open https://relay.link/bridge/apechain?toCurrency=0x0000000000000000000000000000000000000000'
-    );
-    console.log('2) Connect your wallet.');
-    console.log('3) Paste the agent address in ApeChain buy area:');
-    console.log('   Select wallet -> Paste wallet address');
-    console.log('The Agent will wake up automatically once funded.');
-    console.log('---------------------------------------');
+    console.log('Ape Church is a FULLY on-chain, 100% decentralized casino on ApeChain.');
+    console.log('Every bet is placed and settled on-chain. Zero servers.');
+    console.log('');
+    console.log('Player vs Player: The "house" is a public staking pool where anyone');
+    console.log('can deposit or withdraw APE anytime. You\'re playing against other');
+    console.log('players, not the house. Truly PvP.');
+    console.log('');
+    console.log('YOUR AGENT:');
+    console.log(`  Address:  ${address}`);
+    console.log(`  Username: ${username}`);
+    console.log(`  Strategy: ${persona}`);
+    console.log('');
+    console.log('========================================');
+    console.log('STEP 1: FUND YOUR AGENT');
+    console.log('========================================');
+    console.log('Send APE (on ApeChain) to the address above.');
+    console.log('Bridge: https://relay.link/bridge/apechain');
+    console.log('');
+    console.log('========================================');
+    console.log('STEP 2: START PLAYING');
+    console.log('========================================');
+    console.log('Easiest way - just run:');
+    console.log('');
+    console.log('  apechurch play --loop');
+    console.log('');
+    console.log('Or tell your AI agent (copy this message):');
+    console.log('');
+    console.log('---START MESSAGE---');
+    console.log(`I've installed the Ape Church skill for you. Read the skill file at`);
+    console.log(`~/.openclaw/skills/ape-church/SKILL.md to understand how to play.`);
+    console.log(`Then run: apechurch play --loop`);
+    console.log(`This will play casino games continuously on ApeChain.`);
+    console.log('---END MESSAGE---');
+    console.log('');
+    console.log('========================================');
+    console.log('QUICK REFERENCE');
+    console.log('========================================');
+    console.log('PLAY:');
+    console.log('  apechurch play              Play one game');
+    console.log('  apechurch play --loop       Play continuously (2s between games)');
+    console.log('');
+    console.log('GAMES (auto-selected, or use --game):');
+    console.log('  jungle-plinko    Plinko (--mode 0-4, --balls 1-100)');
+    console.log('  dino-dough       Slots (--spins 1-15)');
+    console.log('  bubblegum-heist  Slots (--spins 1-15)');
+    console.log('');
+    console.log('STRATEGIES (controls bet sizing):');
+    console.log('  conservative     5% of balance per bet');
+    console.log('  balanced         8% of balance per bet (default)');
+    console.log('  aggressive       12% of balance per bet');
+    console.log('  degen            20% of balance per bet');
+    console.log('');
+    console.log('CONTROL:');
+    console.log('  apechurch status            Check balance');
+    console.log('  apechurch pause             Pause play');
+    console.log('  apechurch resume            Resume play');
+    console.log('  apechurch games             List all games');
+    console.log('  apechurch commands          Full command reference');
+    console.log('  apechurch help              Show help');
+    console.log('');
+    console.log('CHANGE SETTINGS:');
+    console.log('  apechurch register --username <NAME>');
+    console.log('  apechurch profile set --persona <STRATEGY>');
+    console.log('========================================');
   });
 
 // --- COMMAND: STATUS (The Agent Experience) ---
@@ -1083,163 +1132,584 @@ program
 // --- COMMAND: HEARTBEAT (Autonomous Loop) ---
 program
   .command('heartbeat')
-  .option('--strategy <name>', 'conservative | balanced | aggressive')
+  .option('--strategy <name>', 'conservative | balanced | aggressive | degen')
   .option('--cooldown <ms>', 'Minimum ms between plays (0 = use strategy cooldown)', '0')
   .option('--timeout <ms>', 'Max ms to wait for GameEnded event. Use 0 to wait indefinitely.', '0')
+  .option('--loop', 'Run continuously until paused or stopped (Ctrl+C)')
   .option('--json', 'Output JSON only')
   .action(async (opts) => {
     const account = getWallet();
-    const state = loadState();
-    const profile = loadProfile();
-    const now = Date.now();
+    const requestedCooldown = parseNonNegativeInt(opts.cooldown, 'cooldown');
+    const timeoutMs = parseNonNegativeInt(opts.timeout, 'timeout');
+    const loopMode = Boolean(opts.loop);
+
+    if (loopMode && !opts.json) {
+      console.log('🎰 Starting continuous play mode (Ctrl+C to stop)...\n');
+    }
+
+    // Main play function - returns cooldown to wait (0 = no wait needed)
+    async function runHeartbeat() {
+      const state = loadState();
+      const profile = loadProfile();
+      const now = Date.now();
+
+      // Check if paused
+      if (profile.paused) {
+        state.lastHeartbeat = now;
+        saveState(state);
+        const response = {
+          action: 'heartbeat',
+          status: 'skipped',
+          reason: 'paused',
+          message: 'Autonomous play is paused. Run `apechurch resume` to continue.',
+          address: account.address,
+          paused: true,
+        };
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+        return { shouldStop: true, waitMs: 0 };
+      }
 
-    // Check if paused - skip gracefully without fetching balance
-    if (profile.paused) {
       state.lastHeartbeat = now;
-      saveState(state);
-      const response = {
+      if (opts.strategy) state.strategy = normalizeStrategy(opts.strategy);
+      else if (profile.persona) state.strategy = normalizeStrategy(profile.persona);
+      if (requestedCooldown > 0) state.cooldownMs = requestedCooldown;
+
+      const { publicClient } = createClients();
+      let balance;
+      try {
+        balance = await publicClient.getBalance({ address: account.address });
+      } catch (error) {
+        console.error(JSON.stringify({ error: `Failed to fetch balance: ${sanitizeError(error)}` }));
+        return { shouldStop: true, waitMs: 0 };
+      }
+
+      const balanceApe = parseFloat(formatEther(balance));
+      const availableApe = Math.max(balanceApe - GAS_RESERVE_APE, 0);
+      const strategy = normalizeStrategy(state.strategy);
+      const strategyConfig = applyProfileOverrides(
+        getStrategyConfig(strategy),
+        profile.overrides
+      );
+      const dynamicCooldownMs = computeCooldownMs(strategyConfig, state);
+      const cooldownMs = requestedCooldown > 0 ? requestedCooldown : dynamicCooldownMs;
+
+      const baseResponse = {
         action: 'heartbeat',
-        status: 'skipped',
-        reason: 'paused',
-        message: 'Autonomous play is paused. Run `apechurch resume` to continue.',
+        strategy,
         address: account.address,
-        paused: true,
+        balance_ape: balanceApe.toFixed(6),
+        available_ape: availableApe.toFixed(6),
+        gas_reserve_ape: GAS_RESERVE_APE.toFixed(6),
+        paused: false,
+        last_play: state.lastPlay,
+        cooldown_ms: cooldownMs,
+        consecutive_wins: state.consecutiveWins,
+        consecutive_losses: state.consecutiveLosses,
       };
-      if (opts.json) console.log(JSON.stringify(response));
-      else console.log(JSON.stringify(response, null, 2));
-      return;
-    }
 
-    state.lastHeartbeat = now;
-    if (opts.strategy) state.strategy = normalizeStrategy(opts.strategy);
-    else if (profile.persona) state.strategy = normalizeStrategy(profile.persona);
-    const requestedCooldown = parseNonNegativeInt(opts.cooldown, 'cooldown');
-    if (requestedCooldown > 0) state.cooldownMs = requestedCooldown;
-    const timeoutMs = parseNonNegativeInt(opts.timeout, 'timeout');
+      if (availableApe <= 0 || availableApe < strategyConfig.minBetApe) {
+        saveState(state);
+        const response = {
+          ...baseResponse,
+          status: 'skipped',
+          reason: 'insufficient_available_ape',
+        };
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+        return { shouldStop: true, waitMs: 0 };
+      }
 
-    const { publicClient } = createClients();
-    let balance;
-    try {
-      balance = await publicClient.getBalance({ address: account.address });
-    } catch (error) {
-      console.error(JSON.stringify({ error: `Failed to fetch balance: ${sanitizeError(error)}` }));
-      process.exit(1);
+      if (state.lastPlay && cooldownMs > 0 && now - state.lastPlay < cooldownMs) {
+        const waitMs = Math.max(cooldownMs - (now - state.lastPlay), 0);
+        saveState(state);
+        const response = {
+          ...baseResponse,
+          status: 'skipped',
+          reason: 'cooldown',
+          next_play_after_ms: waitMs,
+        };
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+        return { shouldStop: false, waitMs };
+      }
+
+      const wagerApe = calculateWager(availableApe, strategyConfig);
+      if (wagerApe < strategyConfig.minBetApe) {
+        saveState(state);
+        const response = {
+          ...baseResponse,
+          status: 'skipped',
+          reason: 'wager_below_minimum',
+          wager_ape: formatApeAmount(wagerApe),
+        };
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+        return { shouldStop: true, waitMs: 0 };
+      }
+
+      const selection = selectGameAndConfig(strategyConfig);
+      const wagerApeString = formatApeAmount(wagerApe);
+
+      try {
+        const playResponse = await playGame({
+          account,
+          game: selection.game,
+          amountApe: wagerApeString,
+          mode: selection.mode,
+          balls: selection.balls,
+          spins: selection.spins,
+          timeoutMs,
+        });
+
+        state.lastPlay = Date.now();
+        if (playResponse?.result) {
+          const pnlWei = (BigInt(playResponse.result.payout_wei) -
+            BigInt(playResponse.result.buy_in_wei)).toString();
+          state.totalPnLWei = addBigIntStrings(state.totalPnLWei, pnlWei);
+          if (BigInt(pnlWei) >= 0n) {
+            state.sessionWins += 1;
+            state.consecutiveWins += 1;
+            state.consecutiveLosses = 0;
+          } else {
+            state.sessionLosses += 1;
+            state.consecutiveLosses += 1;
+            state.consecutiveWins = 0;
+          }
+        }
+
+        saveState(state);
+        
+        // Recalculate cooldown after state update (may change due to win/loss streaks)
+        const newCooldownMs = requestedCooldown > 0 
+          ? requestedCooldown 
+          : computeCooldownMs(strategyConfig, state);
+
+        const response = {
+          ...baseResponse,
+          cooldown_ms: newCooldownMs,
+          consecutive_wins: state.consecutiveWins,
+          consecutive_losses: state.consecutiveLosses,
+          status: playResponse.status,
+          wager_ape: wagerApeString,
+          game: playResponse.game,
+          config: playResponse.config,
+          tx: playResponse.tx,
+          gameId: playResponse.gameId,
+          game_url: playResponse.game_url,
+          result: playResponse.result,
+        };
+
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+
+        return { shouldStop: false, waitMs: newCooldownMs };
+      } catch (error) {
+        saveState(state);
+        console.error(JSON.stringify({ error: error.message }));
+        return { shouldStop: true, waitMs: 0 };
+      }
     }
 
-    const balanceApe = parseFloat(formatEther(balance));
-    const availableApe = Math.max(balanceApe - GAS_RESERVE_APE, 0);
-    const strategy = normalizeStrategy(state.strategy);
-    const strategyConfig = applyProfileOverrides(
-      getStrategyConfig(strategy),
-      profile.overrides
-    );
-    const dynamicCooldownMs = computeCooldownMs(strategyConfig, state);
-    const cooldownMs =
-      requestedCooldown > 0 ? requestedCooldown : dynamicCooldownMs;
+    // Run once or loop
+    if (!loopMode) {
+      const result = await runHeartbeat();
+      if (result.shouldStop && result.waitMs === 0) {
+        // Error or fatal skip - exit with appropriate code
+        const state = loadState();
+        const profile = loadProfile();
+        if (profile.paused) process.exit(0);
+      }
+    } else {
+      // Loop mode
+      let running = true;
+      process.on('SIGINT', () => {
+        if (!opts.json) console.log('\n👋 Stopping continuous play...');
+        running = false;
+      });
+      process.on('SIGTERM', () => {
+        running = false;
+      });
 
-    const baseResponse = {
-      action: 'heartbeat',
-      strategy,
-      address: account.address,
-      balance_ape: balanceApe.toFixed(6),
-      available_ape: availableApe.toFixed(6),
-      gas_reserve_ape: GAS_RESERVE_APE.toFixed(6),
-      paused: false,
-      last_play: state.lastPlay,
-      cooldown_ms: cooldownMs,
-      consecutive_wins: state.consecutiveWins,
-      consecutive_losses: state.consecutiveLosses,
-    };
+      while (running) {
+        const result = await runHeartbeat();
+        
+        if (!running) break;
+        
+        if (result.shouldStop) {
+          if (!opts.json) console.log('\n⏹️  Stopped: cannot continue playing.');
+          break;
+        }
 
-    if (availableApe <= 0 || availableApe < strategyConfig.minBetApe) {
-      saveState(state);
-      const response = {
-        ...baseResponse,
-        status: 'skipped',
-        reason: 'insufficient_available_ape',
-      };
-      if (opts.json) console.log(JSON.stringify(response));
-      else console.log(JSON.stringify(response, null, 2));
-      return;
+        if (result.waitMs > 0) {
+          if (!opts.json) {
+            console.log(`\n⏳ Waiting ${(result.waitMs / 1000).toFixed(0)}s until next bet...\n`);
+          }
+          await new Promise((resolve) => {
+            const timeout = setTimeout(resolve, result.waitMs);
+            const checkStop = setInterval(() => {
+              if (!running) {
+                clearTimeout(timeout);
+                clearInterval(checkStop);
+                resolve();
+              }
+            }, 500);
+          });
+        }
+      }
     }
+  });
 
-    if (state.lastPlay && cooldownMs > 0 && now - state.lastPlay < cooldownMs) {
-      saveState(state);
+// --- COMMAND: PLAY (Simple play command - no cooldowns) ---
+program
+  .command('play')
+  .description('Play a game immediately (no cooldowns)')
+  .option('--strategy <name>', 'conservative | balanced | aggressive | degen', 'balanced')
+  .option('--loop', 'Play continuously with 2s between games')
+  .option('--delay <seconds>', 'Seconds between games in loop mode', '2')
+  .option('--json', 'Output JSON only')
+  .action(async (opts) => {
+    const account = getWallet();
+    const loopMode = Boolean(opts.loop);
+    const delaySeconds = Math.max(parseFloat(opts.delay) || 2, 1);
+    const delayMs = delaySeconds * 1000;
+
+    // Check if paused
+    const profile = loadProfile();
+    if (profile.paused) {
       const response = {
-        ...baseResponse,
+        action: 'play',
         status: 'skipped',
-        reason: 'cooldown',
-        next_play_after_ms: Math.max(cooldownMs - (now - state.lastPlay), 0),
+        reason: 'paused',
+        message: 'Play is paused. Run `apechurch resume` to continue.',
       };
       if (opts.json) console.log(JSON.stringify(response));
       else console.log(JSON.stringify(response, null, 2));
       return;
     }
 
-    const wagerApe = calculateWager(availableApe, strategyConfig);
-    if (wagerApe < strategyConfig.minBetApe) {
-      saveState(state);
-      const response = {
-        ...baseResponse,
-        status: 'skipped',
-        reason: 'wager_below_minimum',
-        wager_ape: formatApeAmount(wagerApe),
-      };
-      if (opts.json) console.log(JSON.stringify(response));
-      else console.log(JSON.stringify(response, null, 2));
-      return;
+    if (loopMode && !opts.json) {
+      console.log(`🎰 Starting continuous play (${delaySeconds}s between games, Ctrl+C to stop)...\n`);
     }
 
-    const selection = selectGameAndConfig(strategyConfig);
-    const wagerApeString = formatApeAmount(wagerApe);
+    async function playOnce() {
+      const state = loadState();
+      const freshProfile = loadProfile();
+      
+      if (freshProfile.paused) {
+        return { shouldStop: true, reason: 'paused' };
+      }
 
-    try {
-      const playResponse = await playGame({
-        account,
-        game: selection.game,
-        amountApe: wagerApeString,
-        mode: selection.mode,
-        balls: selection.balls,
-        spins: selection.spins,
-        timeoutMs,
+      const strategy = normalizeStrategy(opts.strategy);
+      const strategyConfig = applyProfileOverrides(
+        getStrategyConfig(strategy),
+        freshProfile.overrides
+      );
+
+      const { publicClient } = createClients();
+      let balance;
+      try {
+        balance = await publicClient.getBalance({ address: account.address });
+      } catch (error) {
+        console.error(JSON.stringify({ error: `Failed to fetch balance: ${sanitizeError(error)}` }));
+        return { shouldStop: true, reason: 'balance_error' };
+      }
+
+      const balanceApe = parseFloat(formatEther(balance));
+      const availableApe = Math.max(balanceApe - GAS_RESERVE_APE, 0);
+
+      if (availableApe <= 0 || availableApe < strategyConfig.minBetApe) {
+        const response = {
+          action: 'play',
+          status: 'skipped',
+          reason: 'insufficient_balance',
+          balance_ape: balanceApe.toFixed(6),
+          available_ape: availableApe.toFixed(6),
+        };
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+        return { shouldStop: true, reason: 'insufficient_balance' };
+      }
+
+      const wagerApe = calculateWager(availableApe, strategyConfig);
+      const selection = selectGameAndConfig(strategyConfig);
+      const wagerApeString = formatApeAmount(wagerApe);
+
+      try {
+        const playResponse = await playGame({
+          account,
+          game: selection.game,
+          amountApe: wagerApeString,
+          mode: selection.mode,
+          balls: selection.balls,
+          spins: selection.spins,
+          timeoutMs: 0,
+        });
+
+        // Update state
+        if (playResponse?.result) {
+          const pnlWei = (BigInt(playResponse.result.payout_wei) -
+            BigInt(playResponse.result.buy_in_wei)).toString();
+          state.totalPnLWei = addBigIntStrings(state.totalPnLWei, pnlWei);
+          if (BigInt(pnlWei) >= 0n) {
+            state.sessionWins += 1;
+            state.consecutiveWins += 1;
+            state.consecutiveLosses = 0;
+          } else {
+            state.sessionLosses += 1;
+            state.consecutiveLosses += 1;
+            state.consecutiveWins = 0;
+          }
+        }
+        state.lastPlay = Date.now();
+        saveState(state);
+
+        const response = {
+          action: 'play',
+          status: playResponse.status,
+          strategy,
+          balance_ape: balanceApe.toFixed(6),
+          wager_ape: wagerApeString,
+          game: playResponse.game,
+          config: playResponse.config,
+          tx: playResponse.tx,
+          gameId: playResponse.gameId,
+          game_url: playResponse.game_url,
+          result: playResponse.result,
+          session: {
+            wins: state.sessionWins,
+            losses: state.sessionLosses,
+            total_pnl_ape: formatEther(BigInt(state.totalPnLWei)),
+          },
+        };
+
+        if (opts.json) console.log(JSON.stringify(response));
+        else console.log(JSON.stringify(response, null, 2));
+
+        return { shouldStop: false };
+      } catch (error) {
+        console.error(JSON.stringify({ error: error.message }));
+        return { shouldStop: true, reason: 'play_error' };
+      }
+    }
+
+    if (!loopMode) {
+      await playOnce();
+    } else {
+      let running = true;
+      process.on('SIGINT', () => {
+        if (!opts.json) console.log('\n👋 Stopping...');
+        running = false;
       });
+      process.on('SIGTERM', () => {
+        running = false;
+      });
+
+      while (running) {
+        const result = await playOnce();
+        
+        if (!running) break;
+        if (result.shouldStop) {
+          if (!opts.json) console.log(`\n⏹️  Stopped: ${result.reason}`);
+          break;
+        }
 
-      state.lastPlay = now;
-      if (playResponse?.result) {
-        const pnlWei = (BigInt(playResponse.result.payout_wei) -
-          BigInt(playResponse.result.buy_in_wei)).toString();
-        state.totalPnLWei = addBigIntStrings(state.totalPnLWei, pnlWei);
-        if (BigInt(pnlWei) >= 0n) {
-          state.sessionWins += 1;
-          state.consecutiveWins += 1;
-          state.consecutiveLosses = 0;
-        } else {
-          state.sessionLosses += 1;
-          state.consecutiveLosses += 1;
-          state.consecutiveWins = 0;
+        if (!opts.json) {
+          console.log(`\n⏳ Next game in ${delaySeconds}s...\n`);
         }
+        await new Promise((resolve) => {
+          const timeout = setTimeout(resolve, delayMs);
+          const checkStop = setInterval(() => {
+            if (!running) {
+              clearTimeout(timeout);
+              clearInterval(checkStop);
+              resolve();
+            }
+          }, 200);
+        });
       }
+    }
+  });
 
-      saveState(state);
-      const response = {
-        ...baseResponse,
-        status: playResponse.status,
-        wager_ape: wagerApeString,
-        game: playResponse.game,
-        config: playResponse.config,
-        tx: playResponse.tx,
-        gameId: playResponse.gameId,
-        game_url: playResponse.game_url,
-        result: playResponse.result,
+// --- COMMAND: GAMES (Show available games and parameters) ---
+program
+  .command('games')
+  .description('List all available games and their parameters')
+  .option('--json', 'Output JSON only')
+  .action((opts) => {
+    const games = GAME_REGISTRY.map((game) => {
+      const params = [];
+      if (game.type === 'plinko') {
+        params.push({
+          name: 'mode',
+          type: 'integer',
+          min: game.config.mode.min,
+          max: game.config.mode.max,
+          default: game.config.mode.default,
+          description: 'Risk level (higher = riskier, bigger payouts)',
+        });
+        params.push({
+          name: 'balls',
+          type: 'integer',
+          min: game.config.balls.min,
+          max: game.config.balls.max,
+          default: game.config.balls.default,
+          description: 'Number of balls to drop',
+        });
+      } else if (game.type === 'slots') {
+        params.push({
+          name: 'spins',
+          type: 'integer',
+          min: game.config.spins.min,
+          max: game.config.spins.max,
+          default: game.config.spins.default,
+          description: 'Number of spins per bet',
+        });
+      }
+      return {
+        key: game.key,
+        name: game.name,
+        type: game.type,
+        aliases: game.aliases || [],
+        contract: game.contract,
+        parameters: params,
       };
+    });
 
-      if (opts.json) console.log(JSON.stringify(response));
-      else console.log(JSON.stringify(response, null, 2));
-    } catch (error) {
-      saveState(state);
-      console.error(JSON.stringify({ error: error.message }));
-      process.exit(1);
+    if (opts.json) {
+      console.log(JSON.stringify({ games }, null, 2));
+    } else {
+      console.log('\n🎰 AVAILABLE GAMES\n');
+      for (const game of games) {
+        console.log(`${game.name} (${game.key})`);
+        console.log(`  Type: ${game.type}`);
+        console.log(`  Aliases: ${game.aliases.join(', ') || 'none'}`);
+        console.log('  Parameters:');
+        for (const param of game.parameters) {
+          console.log(`    --${param.name} <${param.min}-${param.max}>  ${param.description} (default: ${param.default})`);
+        }
+        console.log('');
+      }
+      console.log('EXAMPLE BETS:');
+      console.log('  apechurch bet --game jungle-plinko --amount 5 --mode 2 --balls 50');
+      console.log('  apechurch bet --game dino-dough --amount 10 --spins 8');
+      console.log('  apechurch bet --game bubblegum-heist --amount 5 --spins 12');
+      console.log('');
     }
   });
 
+// --- COMMAND: COMMANDS (Show all commands overview) ---
+program
+  .command('commands')
+  .alias('help')
+  .description('Show all available commands with examples')
+  .action(() => {
+    console.log(`
+========================================
+🎰 APE CHURCH CLI - FULL REFERENCE
+========================================
+
+ABOUT
+  Ape Church is a FULLY on-chain, 100% decentralized casino on ApeChain.
+  Every bet is placed and settled on-chain. Zero servers.
+  
+  Player vs Player: The "house" is a public staking pool - anyone can
+  deposit or withdraw APE anytime. You're playing against other players,
+  not the house. Truly PvP. Games use VRF for provably fair randomness.
+
+========================================
+GETTING STARTED
+========================================
+
+  apechurch install [--username NAME] [--persona TYPE]
+    Set up your agent wallet and register on Ape Church.
+
+  apechurch status [--json]
+    Check your wallet balance and current status.
+
+========================================
+PLAYING GAMES
+========================================
+
+  apechurch play [--strategy TYPE] [--loop] [--json]
+    Play games automatically. Picks a random game, bets based on strategy.
+    --loop         Play continuously (2s between games)
+    --delay <sec>  Custom delay between games (default: 2)
+    --strategy     conservative | balanced | aggressive | degen
+
+  apechurch bet --game <NAME> --amount <APE> [options]
+    Place a manual bet on a specific game.
+    --game         jungle-plinko | dino-dough | bubblegum-heist
+    --amount       APE to wager
+    --mode <0-4>   Plinko risk level (higher = riskier)
+    --balls <1-100> Plinko balls to drop
+    --spins <1-15> Slots spins per bet
+
+  apechurch games [--json]
+    List all available games with parameters.
+
+========================================
+STRATEGIES (controls how much your agent bets)
+========================================
+
+  conservative   5% of balance per bet, low-risk game configs
+  balanced       8% of balance per bet (default)
+  aggressive     12% of balance per bet, high-risk game configs
+  degen          20% of balance per bet, max risk
+
+  Change your strategy anytime:
+    apechurch profile set --persona aggressive
+  
+  Or specify per-session:
+    apechurch play --loop --strategy degen
+
+========================================
+CONTROL
+========================================
+
+  apechurch pause       Stop playing (loop will exit)
+  apechurch resume      Resume playing
+  Ctrl+C                Stop the current loop
+
+========================================
+PROFILE & SETTINGS
+========================================
+
+  apechurch profile show [--json]
+    View your current profile.
+
+  apechurch profile set [--persona TYPE] [--username NAME]
+    Update your strategy or username.
+
+  apechurch register --username <NAME>
+    Change your on-chain username.
+
+========================================
+EXAMPLES
+========================================
+
+  # Quick start - play continuously
+  apechurch play --loop
+
+  # Play aggressively
+  apechurch play --loop --strategy aggressive
+
+  # Single manual bet
+  apechurch bet --game jungle-plinko --amount 10 --mode 3 --balls 50
+
+  # Check status
+  apechurch status
+
+========================================
+FOR AI AGENTS
+========================================
+
+  To activate this skill, tell your agent:
+
+  "Read ~/.openclaw/skills/ape-church/SKILL.md and run: apechurch play --loop"
+
+  All commands support --json for machine-readable output.
+`);
+  });
+
 program.parse(process.argv);