better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md

@@ -0,0 +1,209 @@
+---
+title: "Minecraft Modpack Server — Host modded Minecraft servers (CurseForge, Modrinth)"
+sidebar_label: "Minecraft Modpack Server"
+description: "Host modded Minecraft servers (CurseForge, Modrinth)"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Minecraft Modpack Server
+
+Host modded Minecraft servers (CurseForge, Modrinth).
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/gaming/minecraft-modpack-server` |
+| Path | `optional-skills/gaming\minecraft-modpack-server` |
+| Version | `1.0.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Minecraft Modpack Server Setup
+
+## When to use
+- User wants to set up a modded Minecraft server from a server pack zip
+- User needs help with NeoForge/Forge server configuration
+- User asks about Minecraft server performance tuning or backups
+
+## Gather User Preferences First
+Before starting setup, ask the user for:
+- **Server name / MOTD** — what should it say in the server list?
+- **Seed** — specific seed or random?
+- **Difficulty** — peaceful / easy / normal / hard?
+- **Gamemode** — survival / creative / adventure?
+- **Online mode** — true (Mojang auth, legit accounts) or false (LAN/cracked friendly)?
+- **Player count** — how many players expected? (affects RAM & view distance tuning)
+- **RAM allocation** — or let agent decide based on mod count & available RAM?
+- **View distance / simulation distance** — or let agent pick based on player count & hardware?
+- **PvP** — on or off?
+- **Whitelist** — open server or whitelist only?
+- **Backups** — want automated backups? How often?
+
+Use sensible defaults if the user doesn't care, but always ask before generating the config.
+
+## Steps
+
+### 1. Download & Inspect the Pack
+```bash
+mkdir -p ~/minecraft-server
+cd ~/minecraft-server
+wget -O serverpack.zip "<URL>"
+unzip -o serverpack.zip -d server
+ls server/
+```
+Look for: `startserver.sh`, installer jar (neoforge/forge), `user_jvm_args.txt`, `mods/` folder.
+Check the script to determine: mod loader type, version, and required Java version.
+
+### 2. Install Java
+- Minecraft 1.21+ → Java 21: `sudo apt install openjdk-21-jre-headless`
+- Minecraft 1.18-1.20 → Java 17: `sudo apt install openjdk-17-jre-headless`
+- Minecraft 1.16 and below → Java 8: `sudo apt install openjdk-8-jre-headless`
+- Verify: `java -version`
+
+### 3. Install the Mod Loader
+Most server packs include an install script. Use the INSTALL_ONLY env var to install without launching:
+```bash
+cd ~/minecraft-server/server
+ATM10_INSTALL_ONLY=true bash startserver.sh
+# Or for generic Forge packs:
+# java -jar forge-*-installer.jar --installServer
+```
+This downloads libraries, patches the server jar, etc.
+
+### 4. Accept EULA
+```bash
+echo "eula=true" > ~/minecraft-server/server/eula.txt
+```
+
+### 5. Configure server.properties
+Key settings for modded/LAN:
+```properties
+motd=\u00a7b\u00a7lServer Name \u00a7r\u00a78| \u00a7aModpack Name
+server-port=25565
+online-mode=true          # false for LAN without Mojang auth
+enforce-secure-profile=true  # match online-mode
+difficulty=hard            # most modpacks balance around hard
+allow-flight=true          # REQUIRED for modded (flying mounts/items)
+spawn-protection=0         # let everyone build at spawn
+max-tick-time=180000       # modded needs longer tick timeout
+enable-command-block=true
+```
+
+Performance settings (scale to hardware):
+```properties
+# 2 players, beefy machine:
+view-distance=16
+simulation-distance=10
+
+# 4-6 players, moderate machine:
+view-distance=10
+simulation-distance=6
+
+# 8+ players or weaker hardware:
+view-distance=8
+simulation-distance=4
+```
+
+### 6. Tune JVM Args (user_jvm_args.txt)
+Scale RAM to player count and mod count. Rule of thumb for modded:
+- 100-200 mods: 6-12GB
+- 200-350+ mods: 12-24GB
+- Leave at least 8GB free for the OS/other tasks
+
+```
+-Xms12G
+-Xmx24G
+-XX:+UseG1GC
+-XX:+ParallelRefProcEnabled
+-XX:MaxGCPauseMillis=200
+-XX:+UnlockExperimentalVMOptions
+-XX:+DisableExplicitGC
+-XX:+AlwaysPreTouch
+-XX:G1NewSizePercent=30
+-XX:G1MaxNewSizePercent=40
+-XX:G1HeapRegionSize=8M
+-XX:G1ReservePercent=20
+-XX:G1HeapWastePercent=5
+-XX:G1MixedGCCountTarget=4
+-XX:InitiatingHeapOccupancyPercent=15
+-XX:G1MixedGCLiveThresholdPercent=90
+-XX:G1RSetUpdatingPauseTimePercent=5
+-XX:SurvivorRatio=32
+-XX:+PerfDisableSharedMem
+-XX:MaxTenuringThreshold=1
+```
+
+### 7. Open Firewall
+```bash
+sudo ufw allow 25565/tcp comment "Minecraft Server"
+```
+Check with: `sudo ufw status | grep 25565`
+
+### 8. Create Launch Script
+```bash
+cat > ~/start-minecraft.sh << 'EOF'
+#!/bin/bash
+cd ~/minecraft-server/server
+java @user_jvm_args.txt @libraries/net/neoforged/neoforge/<VERSION>/unix_args.txt nogui
+EOF
+chmod +x ~/start-minecraft.sh
+```
+Note: For Forge (not NeoForge), the args file path differs. Check `startserver.sh` for the exact path.
+
+### 9. Set Up Automated Backups
+Create backup script:
+```bash
+cat > ~/minecraft-server/backup.sh << 'SCRIPT'
+#!/bin/bash
+SERVER_DIR="$HOME/minecraft-server/server"
+BACKUP_DIR="$HOME/minecraft-server/backups"
+WORLD_DIR="$SERVER_DIR/world"
+MAX_BACKUPS=24
+mkdir -p "$BACKUP_DIR"
+[ ! -d "$WORLD_DIR" ] && echo "[BACKUP] No world folder" && exit 0
+TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
+BACKUP_FILE="$BACKUP_DIR/world_${TIMESTAMP}.tar.gz"
+echo "[BACKUP] Starting at $(date)"
+tar -czf "$BACKUP_FILE" -C "$SERVER_DIR" world
+SIZE=$(du -h "$BACKUP_FILE" | cut -f1)
+echo "[BACKUP] Saved: $BACKUP_FILE ($SIZE)"
+BACKUP_COUNT=$(ls -1t "$BACKUP_DIR"/world_*.tar.gz 2>/dev/null | wc -l)
+if [ "$BACKUP_COUNT" -gt "$MAX_BACKUPS" ]; then
+    REMOVE=$((BACKUP_COUNT - MAX_BACKUPS))
+    ls -1t "$BACKUP_DIR"/world_*.tar.gz | tail -n "$REMOVE" | xargs rm -f
+    echo "[BACKUP] Pruned $REMOVE old backup(s)"
+fi
+echo "[BACKUP] Done at $(date)"
+SCRIPT
+chmod +x ~/minecraft-server/backup.sh
+```
+
+Add hourly cron:
+```bash
+(crontab -l 2>/dev/null | grep -v "minecraft/backup.sh"; echo "0 * * * * $HOME/minecraft-server/backup.sh >> $HOME/minecraft-server/backups/backup.log 2>&1") | crontab -
+```
+
+## Pitfalls
+- ALWAYS set `allow-flight=true` for modded — mods with jetpacks/flight will kick players otherwise
+- `max-tick-time=180000` or higher — modded servers often have long ticks during worldgen
+- First startup is SLOW (several minutes for big packs) — don't panic
+- "Can't keep up!" warnings on first launch are normal, settles after initial chunk gen
+- If online-mode=false, set enforce-secure-profile=false too or clients get rejected
+- The pack's startserver.sh often has an auto-restart loop — make a clean launch script without it
+- Delete the world/ folder to regenerate with a new seed
+- Some packs have env vars to control behavior (e.g., ATM10 uses ATM10_JAVA, ATM10_RESTART, ATM10_INSTALL_ONLY)
+
+## Verification
+- `pgrep -fa neoforge` or `pgrep -fa minecraft` to check if running
+- Check logs: `tail -f ~/minecraft-server/server/logs/latest.log`
+- Look for "Done (Xs)!" in the log = server is ready
+- Test connection: player adds server IP in Multiplayer

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/gaming/gaming-pokemon-player.md

@@ -0,0 +1,240 @@
+---
+title: "Pokemon Player — Play Pokemon via headless emulator + RAM reads"
+sidebar_label: "Pokemon Player"
+description: "Play Pokemon via headless emulator + RAM reads"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Pokemon Player
+
+Play Pokemon via headless emulator + RAM reads.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/gaming/pokemon-player` |
+| Path | `optional-skills/gaming\pokemon-player` |
+| Version | `1.0.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Pokemon Player
+
+Play Pokemon games via headless emulation using the `pokemon-agent` package.
+
+## When to Use
+- User says "play pokemon", "start pokemon", "pokemon game"
+- User asks about Pokemon Red, Blue, Yellow, FireRed, etc.
+- User wants to watch an AI play Pokemon
+- User references a ROM file (.gb, .gbc, .gba)
+
+## Startup Procedure
+
+### 1. First-time setup (clone, venv, install)
+The repo is NousResearch/pokemon-agent on GitHub. Clone it, then
+set up a Python 3.10+ virtual environment. Use uv (preferred for speed)
+to create the venv and install the package in editable mode with the
+pyboy extra. If uv is not available, fall back to python -m venv + pip.
+
+If a checkout already exists (e.g. ~/pokemon-agent with a venv ready),
+just cd there and source .venv/bin/activate instead of recloning.
+
+You also need a ROM file. Ask the user for theirs (a previous setup may
+already have one at roms/pokemon_red.gb inside the checkout).
+NEVER download or provide ROM files — always ask the user.
+
+### 2. Start the game server
+From inside the pokemon-agent directory with the venv activated, run
+pokemon-agent serve with --rom pointing to the ROM and --port 9876.
+Run it in the background with &.
+To resume from a saved game, add --load-state with the save name.
+Wait 4 seconds for startup, then verify with GET /health.
+
+### 3. Set up live dashboard for user to watch
+Use an SSH reverse tunnel via localhost.run so the user can view
+the dashboard in their browser. Connect with ssh, forwarding local
+port 9876 to remote port 80 on the keyless localhost.run endpoint
+(ssh -R 80:localhost:9876 ssh://nokey@localhost.run). Redirect output
+to a log file, wait 10 seconds, then grep the log for the .lhr.life
+URL. Give the user the URL with /dashboard/ appended.
+The tunnel URL changes each time — give the user the new one if restarted.
+
+## Save and Load
+
+### When to save
+- Every 15-20 turns of gameplay
+- ALWAYS before gym battles, rival encounters, or risky fights
+- Before entering a new town or dungeon
+- Before any action you are unsure about
+
+### How to save
+POST /save with a descriptive name. Good examples:
+before_brock, route1_start, mt_moon_entrance, got_cut
+
+### How to load
+POST /load with the save name.
+
+### List available saves
+GET /saves returns all saved states.
+
+### Loading on server startup
+Use --load-state flag when starting the server to auto-load a save.
+This is faster than loading via the API after startup.
+
+## The Gameplay Loop
+
+### Step 1: OBSERVE — check state AND take a screenshot
+GET /state for position, HP, battle, dialog.
+GET /screenshot and save to /tmp/pokemon.png, then use vision_analyze.
+Always do BOTH — RAM state gives numbers, vision gives spatial awareness.
+
+### Step 2: ORIENT
+- Dialog/text on screen → advance it
+- In battle → fight or run
+- Party hurt → head to Pokemon Center
+- Near objective → navigate carefully
+
+### Step 3: DECIDE
+Priority: dialog > battle > heal > story objective > training > explore
+
+### Step 4: ACT — move 2-4 steps max, then re-check
+POST /action with a SHORT action list (2-4 actions, not 10-15).
+
+### Step 5: VERIFY — screenshot after every move sequence
+Take a screenshot and use vision_analyze to confirm you moved where
+intended. This is the MOST IMPORTANT step. Without vision you WILL get lost.
+
+### Step 6: RECORD progress to memory with PKM: prefix
+
+### Step 7: SAVE periodically
+
+## Action Reference
+- press_a — confirm, talk, select
+- press_b — cancel, close menu
+- press_start — open game menu
+- walk_up/down/left/right — move one tile
+- hold_b_N — hold B for N frames (use for speeding through text)
+- wait_60 — wait about 1 second (60 frames)
+- a_until_dialog_end — press A repeatedly until dialog clears
+
+## Critical Tips from Experience
+
+### USE VISION CONSTANTLY
+- Take a screenshot every 2-4 movement steps
+- The RAM state tells you position and HP but NOT what is around you
+- Ledges, fences, signs, building doors, NPCs — only visible via screenshot
+- Ask the vision model specific questions: "what is one tile north of me?"
+- When stuck, always screenshot before trying random directions
+
+### Warp Transitions Need Extra Wait Time
+When walking through a door or stairs, the screen fades to black during
+the map transition. You MUST wait for it to complete. Add 2-3 wait_60
+actions after any door/stair warp. Without waiting, the position reads
+as stale and you will think you are still in the old map.
+
+### Building Exit Trap
+When you exit a building, you appear directly IN FRONT of the door.
+If you walk north, you go right back inside. ALWAYS sidestep first
+by walking left or right 2 tiles, then proceed in your intended direction.
+
+### Dialog Handling
+Gen 1 text scrolls slowly letter-by-letter. To speed through dialog,
+hold B for 120 frames then press A. Repeat as needed. Holding B makes
+text display at max speed. Then press A to advance to the next line.
+The a_until_dialog_end action checks the RAM dialog flag, but this flag
+does not catch ALL text states. If dialog seems stuck, use the manual
+hold_b + press_a pattern instead and verify via screenshot.
+
+### Ledges Are One-Way
+Ledges (small cliff edges) can only be jumped DOWN (south), never climbed
+UP (north). If blocked by a ledge going north, you must go left or right
+to find the gap around it. Use vision to identify which direction the
+gap is. Ask the vision model explicitly.
+
+### Navigation Strategy
+- Move 2-4 steps at a time, then screenshot to check position
+- When entering a new area, screenshot immediately to orient
+- Ask the vision model "which direction to [destination]?"
+- If stuck for 3+ attempts, screenshot and re-evaluate completely
+- Do not spam 10-15 movements — you will overshoot or get stuck
+
+### Running from Wild Battles
+On the battle menu, RUN is bottom-right. To reach it from the default
+cursor position (FIGHT, top-left): press down then right to move cursor
+to RUN, then press A. Wrap with hold_b to speed through text/animations.
+
+### Battling (FIGHT)
+On the battle menu FIGHT is top-left (default cursor position).
+Press A to enter move selection, A again to use the first move.
+Then hold B to speed through attack animations and text.
+
+## Battle Strategy
+
+### Decision Tree
+1. Want to catch? → Weaken then throw Poke Ball
+2. Wild you don't need? → RUN
+3. Type advantage? → Use super-effective move
+4. No advantage? → Use strongest STAB move
+5. Low HP? → Switch or use Potion
+
+### Gen 1 Type Chart (key matchups)
+- Water beats Fire, Ground, Rock
+- Fire beats Grass, Bug, Ice
+- Grass beats Water, Ground, Rock
+- Electric beats Water, Flying
+- Ground beats Fire, Electric, Rock, Poison
+- Psychic beats Fighting, Poison (dominant in Gen 1!)
+
+### Gen 1 Quirks
+- Special stat = both offense AND defense for special moves
+- Psychic type is overpowered (Ghost moves bugged)
+- Critical hits based on Speed stat
+- Wrap/Bind prevent opponent from acting
+- Focus Energy bug: REDUCES crit rate instead of raising it
+
+## Memory Conventions
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| PKM:OBJECTIVE | Current goal | Get Parcel from Viridian Mart |
+| PKM:MAP | Navigation knowledge | Viridian: mart is northeast |
+| PKM:STRATEGY | Battle/team plans | Need Grass type before Misty |
+| PKM:PROGRESS | Milestone tracker | Beat rival, heading to Viridian |
+| PKM:STUCK | Stuck situations | Ledge at y=28 go right to bypass |
+| PKM:TEAM | Team notes | Squirtle Lv6, Tackle + Tail Whip |
+
+## Progression Milestones
+- Choose starter
+- Deliver Parcel from Viridian Mart, receive Pokedex
+- Boulder Badge — Brock (Rock) → use Water/Grass
+- Cascade Badge — Misty (Water) → use Grass/Electric
+- Thunder Badge — Lt. Surge (Electric) → use Ground
+- Rainbow Badge — Erika (Grass) → use Fire/Ice/Flying
+- Soul Badge — Koga (Poison) → use Ground/Psychic
+- Marsh Badge — Sabrina (Psychic) → hardest gym
+- Volcano Badge — Blaine (Fire) → use Water/Ground
+- Earth Badge — Giovanni (Ground) → use Water/Grass/Ice
+- Elite Four → Champion!
+
+## Stopping Play
+1. Save the game with a descriptive name via POST /save
+2. Update memory with PKM:PROGRESS
+3. Tell user: "Game saved as [name]! Say 'play pokemon' to resume."
+4. Kill the server and tunnel background processes
+
+## Pitfalls
+- NEVER download or provide ROM files
+- Do NOT send more than 4-5 actions without checking vision
+- Always sidestep after exiting buildings before going north
+- Always add wait_60 x2-3 after door/stair warps
+- Dialog detection via RAM is unreliable — verify with screenshots
+- Save BEFORE risky encounters
+- The tunnel URL changes each time you restart it