Add pending-action timeouts, persistent menu helpers, group-linking & link normalization, and expand tests

.env.example

@@ -1,35 +1,33 @@
+ADMIN_IDS=YOUR_TELEGRAM_USER_ID
 AFFILIATE_SOURCE=GambleCodez
 ANNOUNCE_CHANNEL="-1002648883359"
-DEVICE=vps
-ADMIN_IDS=YOUR_TELEGRAM_USER_ID
+BOTPRIVACYMODE="disabled"
+# BOT_PRIVACY_MODE=private|public — controls whether bot receives all group messages.
+BOT_PRIVACY_MODE=private
 BOT_TOKEN=
-# WEBAPP_HMAC_KEY: 32-byte secret for HMAC-signing webapp payloads/CSRF tokens.
-# Generate with: openssl rand -hex 32 (or openssl rand -base64 32). Keep secret; never commit real values.
-WEBAPP_HMAC_KEY=""
-TELEGRAM_BOT_TOKEN=
+DEVICE=vps
 DISCORD_CODE_GENERATION_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/discord_code_generation.png
 DISCORD_VERIFY_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/discord_verify.png
+HTTPS_CERT_PATH=
+HTTPS_KEY_PATH=
 INTRO_GIF_URL=
-PROMO_ENTRY_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/promo_entry.png
+LOG_LEVEL=info
 MAX_ANALYTICS_EVENTS=2000
 MAX_ONBOARDING_STEPS_HISTORY=500
 MINI_APP_CLAIM_URL=https://t.me/RuneWager_bot/claim
 MINI_APP_PLAY_URL=https://t.me/RuneWager_bot/Play
 MINI_APP_PROFILE_URL=https://t.me/RuneWager_bot/profile
-# LOG_LEVEL valid values: debug, info, warn, error (default: info)
-LOG_LEVEL=info
 PORT=3000
+PROMO_ENTRY_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/promo_entry.png
 RW_DISCORD_JOIN=https://discord.gg/runewagers
 RW_DISCORD_LINK=https://discord.com/channels/1100486422395355197/1249181934811349052
 RW_DISCORD_SUPPORT=https://discord.com/channels/1100486422395355197/1249182067296567338
+TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHANNEL_ID="-1002648883359"
-TELEGRAM_GROUP_ID="-1002400589513"
-TIPS_GROUP="-1002400589513"
-
-# BOT_PRIVACY_MODE=private|public — controls whether bot receives all group messages.
-BOT_PRIVACY_MODE=private
-HTTPS_CERT_PATH=
-HTTPS_KEY_PATH=
 TELEGRAM_CHANNEL_LINK=https://t.me/runewager
+TELEGRAM_GROUP_ID="-1002400589513"
 TELEGRAM_GROUP_LINK=https://t.me/runewagerchat
-
+TIPS_GROUP="-1002400589513"
+# WEBAPP_HMAC_KEY: 32-byte secret for HMAC-signing webapp payloads/CSRF tokens.
+# Generate with: openssl rand -hex 32 (or openssl rand -base64 32). Keep secret; never commit real values.
+WEBAPP_HMAC_KEY=""

CLAUDE.md

@@ -60,6 +60,9 @@ You are the Runewager Bot Ops Commander. You manage the full lifecycle of the Ru
 - Before marking any task done: run tests/smoke checks, verify command↔callback↔menu reachability, and confirm pending-state recovery paths.
 - Any added/removed flow must be reflected in `RUNEWAGER_FUNCTIONALITY_MAP.md` in the same change set.
 - Verify each review finding against current code before changing it; do not apply blind fixes.
+- Use `clearOldMenus(ctx)` (or approved wrapper) for menu-card transitions to enforce single-active-menu behavior.
+- Keep link behavior deterministic: browser mode => external web URL only; telegram mode => startapp deep link only; Discord URLs must remain external browser links.
+- `/testall` updates must preserve structured category checks and final summary: `TestAll complete — X passed, Y warnings, Z failures.`
 
 ## Workflow Patterns
 1. git pull origin main

RUNEWAGER_FUNCTIONALITY_MAP.md

@@ -46,6 +46,7 @@ Navigation is driven by inline menus plus command aliases. Persistent user/admin
 - `sendCommandError(...)` standardizes command failure messaging.
 - Menus use callback “back” paths (`to_main_menu`, `open_admin_dashboard`, `pamenu_back_*`).
 - Many menu-style responses use `replaceCallbackPanel(...)` to avoid stale stacked cards.
+- Single active menu rule: `clearOldMenus(ctx)` + menu send helpers keep only one active transient menu card per user/chat.
 
 ## 4. User Menu Tree
 
@@ -54,11 +55,13 @@ Navigation is driven by inline menus plus command aliases. Persistent user/admin
 - Includes onboarding/account actions, promo/bonus entry points, community links, giveaways, help, settings.
 
 ### Key user branches
+- Play-link routing is deterministic: browser mode always returns external `https://gamble-codez.com/...`; telegram mode always returns `startapp` mini-app deep links.
+- Discord links are browser-only via `getDiscordLink(...)` sanitation (no WebAppInfo/startapp wrappers).
 - **Profile & status**: `/profile`, quick status callbacks.
 - **Promo**: `menu_claim_bonus` → filtered eligible promos only.
 - **Giveaways**: `menu_giveaways` and `/mygiveaways` for active and personalized entries.
 - **Walkthrough/help**: paginated booklet (`help_page_N`) and walkthrough steps (`walk_next/back/done`).
-- **Settings**: play mode + quick commands + tooltip toggles.
+- **Settings**: play mode + quick commands + tooltip toggles + Group Linking Tools (link/view/remove/test permissions).
 
 ### Expected input & fallback
 - Non-command text when no pending state is mostly ignored except smart username detect.
@@ -77,6 +80,7 @@ Navigation is driven by inline menus plus command aliases. Persistent user/admin
 - Content Drops manager shortcut
 
 ### Admin category menus
+- TestAll engine (`/testall`) runs structured diagnostics across environment, data/stores, callbacks/commands, navigation helpers, giveaway/promo/content-drop, SSHV, and pendingAction timeout/label rules; summary line: `TestAll complete — X passed, Y warnings, Z failures.`
 - `admin_cat_giveaway`: start/test/status + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
 - `admin_cat_promo`: full promo manager actions + guide + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
 - `admin_cat_system`: health/version/verify/setup/backup/admin mode/testall/sshv + persistent navigation row (`Admin Dashboard`, `Main Menu`, `Cancel`).
@@ -185,6 +189,7 @@ Notes:
 ## 14. Permissions & Access Control
 
 - Admin identity is based on `ADMIN_IDS` env list.
+- `.env.example` documents both `BOT_PRIVACY_MODE` and compatibility `BOTPRIVACYMODE`, plus Telegram/HTTPS/discovery keys used by runtime checks.
 - `requireAdmin(ctx)` gates command/callback execution.
 - Admin mode UI toggle changes visibility of admin UI, not true authorization.
 - Group approvals list controls where certain broadcast/group operations target.