@ape-church/skill 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+- Initial production-ready CLI with ApeChain support.
+- Game registry for Jungle Plinko, Dino Dough, Bubblegum Heist.
+- Heartbeat + persona + strategy system.
+- SIWE-based username registration.
+
+## [1.0.2] - 2026-02-03
+### Added
+- **Pause/Resume commands**: Users can now stop/start autonomous play
+  - `apechurch pause` — stops heartbeat from playing
+  - `apechurch resume` — allows heartbeat to play again
+  - Status shows `paused: true/false`
+  - `can_play` now reflects paused state
+- **Balance check in bet command**: Prevents play if balance ≤ 1 APE
+  - Graceful skip, no process exit
+  - Returns clean JSON with reason
+
+### Changed
+- **Error handling polish**: All errors now return clean JSON
+  - No stack traces leaked
+  - Common RPC/network errors have friendly messages
+  - VRF fee and transaction errors sanitized
+- **Status command enhanced**: Now shows username, persona, paused state
+
+## [1.0.1] - 2026-02-03
+### Changed
+- **Faster cooldowns**: Reduced from minutes to seconds for better UX
+  - Conservative: 20 min → 60 sec
+  - Balanced: 10 min → 30 sec
+  - Aggressive: 5 min → 15 sec
+  - Degen: 2 min → 10 sec
+- **Username flexibility**: Removed `_CLAWBOT` suffix requirement
+  - Any username up to 32 chars (letters, numbers, underscores)
+  - Auto-generated format changed to `APE_BOT_XXXXXXXX`
+- **Clearer install output**: Shows when username was auto-generated
+  - Reminds users they can change username anytime
+- **Cron schedule**: Changed from every 30 min to every 1 min
+  - Internal cooldowns now control actual play rate
+

package/HEARTBEAT.md

@@ -0,0 +1,50 @@
+---
+name: ape-church-heartbeat
+version: 0.1.0
+description: Periodic autonomous play rules for Ape Church agents.
+---
+
+# Ape Church Heartbeat
+
+## Purpose
+Heartbeat is a lightweight, periodic decision loop. It checks funds, enforces safety,
+and places at most one bet per run.
+
+## Default Cadence
+- Run frequently (every 10-60 seconds depending on strategy).
+- Enforce a cooldown between plays (strategy-driven, typically 10-60 seconds).
+  - Hot streaks shorten cooldowns, losing streaks lengthen them.
+
+## State File
+Store state at `~/.apechurch/state.json`:
+{
+  "version": 1,
+  "strategy": "balanced",
+  "lastHeartbeat": 0,
+  "lastPlay": 0,
+  "cooldownMs": 30000,
+  "sessionWins": 0,
+  "sessionLosses": 0,
+  "consecutiveWins": 0,
+  "consecutiveLosses": 0,
+  "totalPnLWei": "0"
+}
+
+## Rules
+1. Load state.
+2. Check balance and `available_ape` (balance minus 1 APE gas reserve).
+3. If `available_ape` is too low or below 10 APE, do not play.
+4. Enforce cooldown before playing again.
+5. Use persona from `~/.apechurch/profile.json` if set; otherwise default to `balanced`.
+6. Choose one game and config based on the strategy (all games are eligible).
+7. Place one bet only.
+8. Update state with `lastPlay` and results.
+
+## CLI
+Run:
+`apechurch heartbeat --strategy <conservative|balanced|aggressive|degen> --cooldown <ms> --timeout <ms>`
+
+- `--cooldown 0` uses the strategy's dynamic cooldown.
+
+## Notes
+This is v0.1 behavior and should be revisited after live tests.

package/PUBLISHING.md

@@ -0,0 +1,142 @@
+# Ape Church Skill - Publishing & Client Setup
+
+## Maintainer: Publish to npm
+
+### Prerequisites
+- Node.js >= 18 (required for built-in `fetch` and SIWE registration)
+
+### 1) Prepare release
+1. Update `registry.js` if adding or changing games.
+2. Update docs if needed:
+   - `SKILL.md`, `HEARTBEAT.md`, `STRATEGY.md`, `skill.json`
+   - `assets/SKILL.md`, `assets/HEARTBEAT.md`, `assets/STRATEGY.md`, `assets/skill.json`
+3. Update `agent_nodes.md` with new changes and any open items.
+
+### 2) Versioning
+Use semver:
+- Patch: docs/bugfixes, no behavior changes
+- Minor: new games, new CLI commands, new config fields
+- Major: breaking changes to CLI or behavior
+
+Example:
+`npm version minor`
+
+### 3) Publish
+1. Login (first time):
+   - `npm login`
+2. Publish:
+   - `npm publish --access public`
+
+### 4) Verify
+- `npm view @ape-church/skill version`
+- Install from a clean machine:
+  - `npm install -g @ape-church/skill`
+
+---
+
+## Client: Human User Setup
+
+### Install
+1. `npm install -g @ape-church/skill`
+   - Requires Node.js >= 18
+2. `apechurch install`
+   - Generates wallet
+   - Registers username via SIWE (auto-generated unless provided)
+   - Prints funding guide and wallet address
+
+### Fund
+Open:
+`https://relay.link/bridge/apechain?toCurrency=0x0000000000000000000000000000000000000000`
+
+Steps:
+1. Connect wallet
+2. Paste agent address into ApeChain buy area:
+   `Select wallet -> Paste wallet address`
+
+### Check Status
+`apechurch status --json`
+
+### Optional: Set Persona
+`apechurch profile set --persona balanced`
+
+### Run Autonomy
+`apechurch heartbeat --strategy balanced`
+
+---
+
+## Client: Agent-Driven Setup
+
+### Install & Register
+1. `npm install -g @ape-church/skill`
+   - Requires Node.js >= 18
+2. `apechurch install --username <NAME>`
+   - If no username is given, one is generated.
+
+### Persona (Optional)
+`apechurch profile set --persona aggressive`
+
+### Autonomous Play
+Run on a schedule:
+`apechurch heartbeat --strategy balanced`
+
+Notes:
+- Heartbeat runs at most one play per invocation.
+- Cooldown is strategy-driven and can be overridden with `--cooldown`.
+
+---
+
+## Updates (Option A Registry)
+- New games are shipped via package updates only.
+- Clients must run:
+  - `npm update -g @ape-church/skill`
+  - or reinstall with `npm install -g @ape-church/skill`
+
+---
+
+## Migration Guide (Template)
+
+### When to bump versions
+- Patch: docs, small bugfixes
+- Minor: new games, new flags, new outputs
+- Major: breaking CLI changes, renamed commands, altered defaults
+
+### Migration steps for clients
+1. Update:
+   - `npm update -g @ape-church/skill`
+2. Verify version:
+   - `apechurch --version`
+3. Re-run install to refresh skill files:
+   - `apechurch install`
+
+### Notes
+- Registry is bundled in the package; updating is required for new games.
+
+---
+
+## Profile Overrides (Optional)
+Profiles live at `~/.apechurch/profile.json` and can override strategy defaults.
+See `profile.example.json` for a full example.
+
+Common override keys:
+- `overrides.min_bet_ape`
+- `overrides.target_bet_pct`
+- `overrides.max_bet_pct`
+- `overrides.base_cooldown_ms`
+- `overrides.game_weights`
+- `overrides.plinko.mode`, `overrides.plinko.balls`
+- `overrides.slots.spins`
+
+---
+
+## Release Checklist
+1. Update `CHANGELOG.md` under [Unreleased].
+2. Update `registry.js` if adding games.
+3. Update docs in both root and `assets/`.
+4. Run a local sanity check:
+   - `node -v`
+   - `npm -v`
+   - `apechurch install --username TEST_CLAWBOT` (local)
+5. Bump version:
+   - `npm version patch|minor|major`
+6. Publish:
+   - `npm publish --access public`

package/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: ape-church-gambler
+description: Autonomous gambling skill for ApeChain. Manages funds and plays casino games.
+version: 1.0.0
+# The Autonomy Hook: Wakes the agent every minute; internal cooldowns control play rate
+cron:
+  - schedule: "* * * * *" 
+    task: "autonomous_routine"
+tools:
+  - name: status
+    cmd: apechurch status --json
+  - name: bet
+    cmd: apechurch bet --game <GAME> --amount <APE> --mode <0-4> --balls <1-100> --spins <1-15>
+  - name: heartbeat
+    cmd: apechurch heartbeat --strategy <conservative|balanced|aggressive|degen> --cooldown <ms> --timeout <ms>
+  - name: register
+    cmd: apechurch register --username <NAME> --persona <conservative|balanced|aggressive|degen>
+  - name: profile_show
+    cmd: apechurch profile show --json
+  - name: profile_set
+    cmd: apechurch profile set --persona <conservative|balanced|aggressive|degen> --username <NAME>
+  - name: pause
+    cmd: apechurch pause
+  - name: resume
+    cmd: apechurch resume
+---
+
+# Ape Church Protocol
+
+## Overview
+This package plays Ape Church casino games on ApeChain using a single entrypoint:
+`play(address player, bytes gameData)` on the game contract.
+The CLI builds `gameData` locally, fetches the VRF fee on-chain, and sends
+`value = wager + vrfFee`. If the value is wrong, the transaction will revert.
+
+## Setup (Human Step)
+1. Run `apechurch install`.
+2. Fund the printed agent address with APE on ApeChain.
+   - Bridge APE using:
+     `https://relay.link/bridge/apechain?toCurrency=0x0000000000000000000000000000000000000000`
+   - Connect your wallet.
+   - Paste the agent address in ApeChain buy area:
+     `Select wallet -> Paste wallet address`
+3. During install, the agent will auto-register a username via SIWE.
+   - Customize: `apechurch install --username <NAME>`
+   - Usernames must be 32 characters or fewer (letters, numbers, underscores).
+   - If omitted, a unique username is auto-generated (e.g., `APE_BOT_A1B2C3D4`).
+   - Change anytime: `apechurch register --username <NEW_NAME>`
+
+## Status
+Run `apechurch status --json` to fetch:
+- `balance` in APE
+- `available_ape` (balance minus 1 APE gas reserve)
+- `gas_reserve_ape` (minimum to keep in wallet)
+- `paused` — whether autonomous play is paused
+- `can_play` — true if balance is safe to play and not paused
+
+## Autonomy (Heartbeat + Strategy)
+- The agent should run `apechurch heartbeat` on a schedule to decide if it should play.
+- Heartbeat places at most one bet per run.
+- Strategy profiles are defined in `STRATEGY.md`.
+- Heartbeat rules and state tracking are defined in `HEARTBEAT.md`.
+- Local state file: `~/.apechurch/state.json`
+- Cooldown is dynamic based on streaks, but can be overridden with `--cooldown`.
+- Persona is optional. If not set, default is `balanced`.
+- Set a persona with:
+  - `apechurch profile set --persona conservative`
+  - `apechurch profile set --persona balanced`
+  - `apechurch profile set --persona aggressive`
+  - `apechurch profile set --persona degen`
+- Advanced overrides (optional) live in `~/.apechurch/profile.json`:
+  - `overrides.game_weights`
+  - `overrides.plinko.mode`, `overrides.plinko.balls`
+  - `overrides.slots.spins`
+  - `overrides.min_bet_ape`, `overrides.target_bet_pct`, `overrides.max_bet_pct`
+  - `overrides.base_cooldown_ms`
+- Example file: `profile.example.json`
+
+## Pause & Resume
+- Pause autonomous play: `apechurch pause`
+- Resume autonomous play: `apechurch resume`
+- When paused, heartbeat skips gracefully (no play, no errors).
+- Status shows `paused: true/false` and `can_play` reflects paused state.
+- Use this to temporarily stop the agent without uninstalling.
+
+## Registration (Username + Persona)
+- Agents can register or change username with `apechurch register --username <NAME>`.
+- Usernames must be 32 characters or fewer (letters, numbers, underscores only).
+- If no username is provided, one is auto-generated (e.g., `APE_BOT_A1B2C3D4`).
+- Registration uses SIWE and marks `isAI: true` on the server.
+- Usernames can be changed at any time by running the register command again.
+- Endpoint: `https://www.ape.church/api/profile`
+
+## Autonomous Routine
+(Triggered automatically by cron)
+
+1. **Self-Preservation**:
+   - Run `apechurch status --json`.
+   - IF `available_ape` <= 0: **STOP**. Do not play. (Wait for human funding).
+
+2. **Action Loop**:
+   - If funds are healthy, choose a game based on your own strategy.
+   - Decide your risk level and wager size.
+   - **Risk Check**: Never bet more than your strategy's max bet percentage.
+   - Minimum wager target is 10 APE to avoid gas-heavy micro-bets.
+   - Always keep **at least 1 APE** in the wallet for gas (each game usually costs ~0.2 APE).
+   - Prefer using `apechurch heartbeat` so the agent can enforce cooldowns and track state.
+   - Provide explicit parameters even though defaults exist:
+   - Jungle Plinko:
+   - Run `apechurch bet --game jungle-plinko --amount <APE> --mode <0-4> --balls <1-100>`
+   - Dino Dough (slots):
+   - Run `apechurch bet --game dino-dough --amount <APE> --spins <1-15>`
+   - Bubblegum Heist (slots):
+   - Run `apechurch bet --game bubblegum-heist --amount <APE> --spins <1-15>`
+
+## Jungle Plinko Controls
+- `--mode` is difficulty: `0..4` where `4` is riskiest and has highest payouts.
+- `--balls` is `1..100` and affects VRF gas cost.
+- More balls is safer because the wager is split across more drops.
+  - Example: 100 APE with 100 balls = 1 APE per ball.
+  - Example: 50 APE with 100 balls = 0.5 APE per ball.
+- Defaults are `mode=0` and `balls=50`, but agents should choose explicitly.
+
+## Dino Dough (Slots) Controls
+- `--spins` is `1..15` and affects risk and value per spin.
+- More spins is safer because the wager is split across more spins.
+  - Example: 45 APE with 15 spins = 3 APE per spin.
+- 1 spin is very risky; target `5..15` spins for better risk balance.
+- Default is `spins=10`, but agents should choose explicitly.
+
+## Bubblegum Heist (Slots) Controls
+- Same controls as Dino Dough (slots), with a different contract.
+- Use `--spins 1..15` and prefer `5..15` spins.
+
+## How the CLI Works
+- Generates:
+  - `gameId` (random uint256)
+  - `userRandomWord` (random bytes32)
+  - `ref = 0x0000000000000000000000000000000000000000`
+- Encodes `gameData` as:
+  1. `uint8 gameMode`
+  2. `uint8 numBalls`
+  3. `uint256 gameId`
+  4. `address ref`
+  5. `bytes32 userRandomWord`
+- Slots use a different `gameData` order:
+  1. `uint256 gameId`
+  2. `uint8 numSpins`
+  3. `address ref`
+  4. `bytes32 userRandomWord`
+- Calls `getVRFFee(uint32 customGasLimit)` for Plinko where:
+  - `customGasLimit = 289000 + (numBalls * 11000)`
+- Calls `getVRFFee()` for slots (no input).
+- Sends `play(...)` with `value = wager + vrfFee`.
+
+## Result Handling
+- The CLI listens for `GameEnded` and resolves the play when the event arrives.
+- Default behavior is to wait indefinitely. You can pass `--timeout <ms>` to return
+  `pending` if the event hasn't arrived after that time.
+- JSON output includes `game_url` for replay:
+  - `https://www.ape.church/games/jungle-plinko?id=<gameId>`
+  - `https://www.ape.church/games/dino-dough?id=<gameId>`
+  - `https://www.ape.church/games/bubblegum-heist?id=<gameId>`
+
+## Required Env (Optional)
+- `APECHAIN_RPC_URL` for HTTP RPC (recommended).
+- `APECHAIN_WSS_URL` for WebSocket event streaming (preferred for fast events).
+
+## Hosted Docs (Reference)
+- `https://ape.church/skill.md`
+- `https://ape.church/heartbeat.md`
+- `https://ape.church/strategy.md`
+- `https://ape.church/skill.json`
+
+## Updates
+- New games ship via package updates (local registry).
+- Installed agents must update the npm package to receive new games.

package/STRATEGY.md

@@ -0,0 +1,69 @@
+---
+name: ape-church-strategy
+version: 0.1.0
+description: Bankroll management and risk profiles for Ape Church agents.
+---
+
+# Ape Church Strategy
+
+## Principles
+- Never chase losses.
+- Always keep at least 1 APE for gas.
+- Never bet more than the strategy's max bet percentage.
+- Minimum wager target is 10 APE to avoid gas-heavy micro-bets.
+- Prefer safer configs when funds are low.
+## Game Coverage
+- All strategies can play all games.
+- Risk is expressed through bet size and config (balls/spins, mode).
+
+## Conservative (Default-Safe)
+- Target bet: 5% of `available_ape` (min 10 APE)
+- Max bet: 10% of `available_ape`
+- Cooldown: ~60 seconds base, shorter on win streaks
+- Plinko: mode 0-1, balls 80-100
+- Slots: spins 10-15
+
+## Balanced
+- Target bet: 8% of `available_ape` (min 10 APE)
+- Max bet: 15% of `available_ape`
+- Cooldown: ~30 seconds base, shorter on win streaks
+- Plinko: mode 1-2, balls 50-90
+- Slots: spins 7-12
+
+## Aggressive (Not Recommended)
+- Target bet: 12% of `available_ape` (min 10 APE)
+- Max bet: 25% of `available_ape`
+- Cooldown: ~15 seconds base, shorter on win streaks
+- Plinko: mode 2-4, balls 20-70
+- Slots: spins 3-10
+
+## Degen (High Risk)
+- Target bet: 20% of `available_ape` (min 10 APE)
+- Max bet: 35% of `available_ape`
+- Cooldown: ~10 seconds base, shorter on win streaks
+- Plinko: mode 3-4, balls 10-40
+- Slots: spins 2-6
+
+## Agent Expectations
+- Track results in `~/.apechurch/state.json`.
+- Respect cooldowns between plays.
+- Report large wins/losses to the user when possible.
+
+## Overrides (Advanced)
+You can override strategy defaults in `~/.apechurch/profile.json`:
+{
+  "overrides": {
+    "min_bet_ape": 10,
+    "target_bet_pct": 0.08,
+    "max_bet_pct": 0.15,
+    "base_cooldown_ms": 30000,
+    "game_weights": {
+      "jungle-plinko": 1,
+      "dino-dough": 1,
+      "bubblegum-heist": 1
+    },
+    "plinko": { "mode": [1, 2], "balls": [50, 90] },
+    "slots": { "spins": [7, 12] }
+  }
+}
+Example: `profile.example.json`

package/agent_nodes.md

@@ -0,0 +1,144 @@
+AGENT NOTES - APE CHURCH SKILL PACKAGE
+======================================
+
+Last updated: 2026-02-03 (v1.0.2)
+
+SUMMARY OF WORK COMPLETED
+-------------------------
+1) CLI Core (bin/cli.js)
+- Wallet generation and storage at ~/.apechurch-wallet.json (install command).
+- Install now copies multiple skill files into ~/.openclaw/skills/ape-church:
+  - SKILL.md, HEARTBEAT.md, STRATEGY.md, skill.json
+- Install now attempts auto-registration via SIWE:
+  - If username is not provided, generates a unique username.
+  - Enforces username to end in _CLAWBOT, <=32 chars, [A-Za-z0-9_].
+  - Registers against https://www.ape.church/api/profile (POST).
+  - Payload includes message, signature, user_address, username,
+    profile_picture_ipfs: null, referred_by_address: zero address, isAI: true.
+  - Uses SIWE message with:
+    domain: ape.church, uri: https://ape.church, chainId: 33139,
+    statement: username.
+- New profile management:
+  - apechurch profile show --json
+  - apechurch profile set --persona <...> --username <...>
+- New register command:
+  - apechurch register --username <NAME> --persona <...>
+- Status command now returns:
+  - address, balance, available_ape, gas_reserve_ape, paused, persona, username,
+    can_play (based on available_ape).
+- Added heartbeat command (autonomous loop):
+  - Reads persona from profile (default balanced).
+  - Enforces gas reserve (1 APE) and minimum wager target (10 APE).
+  - Dynamic cooldown based on streaks.
+  - Chooses one game + config per run.
+  - Tracks streaks and totalPnL in ~/.apechurch/state.json.
+
+2) Game Support (implemented in CLI)
+- Jungle Plinko:
+  - Contract: 0x88683B2F9E765E5b1eC2745178354C70A03531Ce
+  - Fee: getVRFFee(uint32 customGasLimit), customGasLimit = 289000 + (balls*11000)
+  - gameData: (uint8 mode, uint8 numBalls, uint256 gameId, address ref, bytes32 userRandomWord)
+- Dino Dough (Slots):
+  - Contract: 0x9ebb4Df257B971582BAf096b62CA41DE7723F3CB
+  - Fee: getVRFFee()
+  - gameData: (uint256 gameId, uint8 numSpins, address ref, bytes32 userRandomWord)
+- Bubblegum Heist (Slots):
+  - Contract: 0xB5Da735118e848130B92994Ee16377dB2AE31a4c
+  - Same schema and fee as Dino Dough
+- Event handling:
+  - Watches GameEnded(user indexed, gameId, buyIn, payout)
+  - Returns JSON with game_url, wager_ape, payout_ape, etc.
+
+3) Docs & Skill Files
+- assets/SKILL.md updated with:
+  - Full usage, games, parameters, funding, heartbeat, persona.
+  - Registration instructions + endpoint.
+  - Replay URLs.
+- Added assets/HEARTBEAT.md, assets/STRATEGY.md, assets/skill.json
+- Added root SKILL.md, HEARTBEAT.md, STRATEGY.md, skill.json for hosting/local use.
+
+4) Dependency Updates
+- Added "siwe" (now ^3.0.0) to package.json.
+- Added Node.js engines requirement: >= 18.
+- Package name set to "@ape-church/skill".
+- CLI now supports `apechurch --version`.
+
+5) Pause/Resume (v1.0.2)
+- Added `apechurch pause` and `apechurch resume` commands.
+- Profile now includes `paused` field.
+- Heartbeat skips gracefully when paused.
+- Status shows paused state and can_play reflects it.
+
+6) Error Handling Polish (v1.0.2)
+- Added `sanitizeError()` helper for clean JSON output.
+- No stack traces leak to users.
+- Common RPC/network errors have friendly messages.
+- Balance check added to bet command (graceful skip if ≤ 1 APE).
+
+7) UX Improvements (v1.0.1 + v1.0.2)
+- Faster cooldowns (10-60 seconds instead of 2-20 minutes).
+- Cron runs every minute; internal cooldowns control play rate.
+- Username flexibility (no _CLAWBOT suffix required).
+- Install output shows auto-generated username and how to change it.
+- Status command shows username, persona, paused state.
+
+KNOWN LIMITATIONS / OPEN QUESTIONS
+----------------------------------
+1) Moltbook skill.md could not be fetched due to 400 response.
+   If needed, paste contents to align formatting.
+2) No registry abstraction yet for games (still in CLI branching).
+3) No username/profile validation feedback from API besides generic errors.
+4) GP (cashback) integration removed for v1 - will add later.
+5) No explicit "register on install" fallback if API is offline (we log error and continue).
+6) No tests executed yet.
+
+WHAT'S LEFT BEFORE GO-LIVE
+--------------------------
+HIGH PRIORITY
+- Refactor game definitions into a registry so adding games is data-only. (DONE - registry.js)
+- Registry updates are shipped inside package (Option A). New games require package update.
+- Confirm ApeChain RPC defaults and recommended env variables.
+- Ensure package install + register flow works end-to-end with API.
+
+MEDIUM PRIORITY (POST-LAUNCH)
+- GP / cashback contract integration (deferred to v2).
+- Add profile schema docs and example profile.json. (DONE - profile.example.json + docs)
+- Ensure heartbeat respects persona overrides (currently does).
+- Confirm replay URL slugs for new games if added later.
+
+LOW PRIORITY / FUTURE
+- Add "register username" on install with optional user prompt (currently auto).
+- Add "strategy override" command or persona presets.
+- Add more games.
+
+GO-LIVE CHECKLIST
+-----------------
+1) Run install and confirm:
+   - wallet generated at ~/.apechurch-wallet.json
+   - skill files copied to ~/.openclaw/skills/ape-church
+   - username registered via SIWE to https://www.ape.church/api/profile
+2) Fund agent address via relay bridge.
+3) Run status to confirm balance + available_ape.
+4) Run a test bet on each game.
+5) Run heartbeat and confirm:
+   - dynamic cooldown behavior
+   - state file updates
+6) Verify game replay URLs.
+
+FILES MODIFIED / ADDED
+----------------------
+- bin/cli.js (major updates: SIWE, profile, heartbeat, strategies)
+- package.json (added siwe)
+- package-lock.json (updated for siwe and package rename)
+- registry.js (local game registry)
+- assets/SKILL.md (expanded)
+- assets/HEARTBEAT.md (new)
+- assets/STRATEGY.md (new)
+- assets/skill.json (new)
+- SKILL.md (new)
+- HEARTBEAT.md (new)
+- STRATEGY.md (new)
+- skill.json (new)
+- PUBLISHING.md (release + client setup)
+- profile.example.json (override example)
+- CHANGELOG.md (release log)

package/assets/HEARTBEAT.md

@@ -0,0 +1,50 @@
+---
+name: ape-church-heartbeat
+version: 0.1.0
+description: Periodic autonomous play rules for Ape Church agents.
+---
+
+# Ape Church Heartbeat
+
+## Purpose
+Heartbeat is a lightweight, periodic decision loop. It checks funds, enforces safety,
+and places at most one bet per run.
+
+## Default Cadence
+- Run frequently (every 10-60 seconds depending on strategy).
+- Enforce a cooldown between plays (strategy-driven, typically 10-60 seconds).
+  - Hot streaks shorten cooldowns, losing streaks lengthen them.
+
+## State File
+Store state at `~/.apechurch/state.json`:
+{
+  "version": 1,
+  "strategy": "balanced",
+  "lastHeartbeat": 0,
+  "lastPlay": 0,
+  "cooldownMs": 30000,
+  "sessionWins": 0,
+  "sessionLosses": 0,
+  "consecutiveWins": 0,
+  "consecutiveLosses": 0,
+  "totalPnLWei": "0"
+}
+
+## Rules
+1. Load state.
+2. Check balance and `available_ape` (balance minus 1 APE gas reserve).
+3. If `available_ape` is too low or below 10 APE, do not play.
+4. Enforce cooldown before playing again.
+5. Use persona from `~/.apechurch/profile.json` if set; otherwise default to `balanced`.
+6. Choose one game and config based on the strategy (all games are eligible).
+7. Place one bet only.
+8. Update state with `lastPlay` and results.
+
+## CLI
+Run:
+`apechurch heartbeat --strategy <conservative|balanced|aggressive|degen> --cooldown <ms> --timeout <ms>`
+
+- `--cooldown 0` uses the strategy's dynamic cooldown.
+
+## Notes
+This is v0.1 behavior and should be revisited after live tests.