Overview

Two waves of features land at once. Wave V brings the heavyweight new mechanics — live poll tallies, weighted choices, karma defence, weekly glory, and Claude memory management. Wave W refines and deepens: trivia tournaments, configurable rate limits, operator vision, hourly diagnostics, smarter notes, and a non-destructive poll inspector.

“Accio Intelligence! Every feature summoned. Every operator empowered. The Sorting Hat nods in approval.” 🏰⚡✨

---

🗳️ U3 — Live Poll Tally on Every Vote

Every !vote now broadcasts a live leaderboard immediately after the vote is registered — no waiting for !pollresult.

<teuk> m vote 1
<mediabotv3> teuk voted for "4 fromages" (3 vote(s) cast)
<mediabotv3> Live tally: [1] 4 fromages: 2 (67%)  [2] Regina: 1 (33%)

Each option shows count and percentage. The tally updates with every vote cast. !pollresult still closes the poll with the definitive result.

---

🎲 U5 — Weighted !choose

Options can now carry a weight using option:N syntax. The option is added to the pool N times (cap: 20), making it proportionally more likely to be chosen.

<teuk> m choose pizza:3 | sushi:1
<mediabotv3> teuk: I choose... pizza!   ← 3x more likely than sushi

Plain options (no :N) still work. The French ou separator is also unchanged.

---

⏱️ U6 — Karma Anti-Spam Cooldown (30s)

processKarma now enforces a 30-second per-target cooldown. Voting for the same nick twice within 30 seconds is rejected with a notice:

<boole> teuk++
<mediabotv3> boole: wait 24s before voting for teuk again.

The cooldown is stored in $bot->{_karma_cooldown}{$channel} and can be cleared from the Partyline via .flushcooldown.

---

📅 U7 — Weekly Channel Report (Scheduler)

Every 7 days (604800s, autostart), the bot posts a weekly summary to each joined channel:

<mediabotv3> ✨ Weekly report — Top speakers (7d): teuk(247) | Boole(183) | Poyan(91)
<mediabotv3> ✨ Weekly report — Top karma: teuk(+14) | Boole(+7) | Poyan(+3)

Two DB queries per channel — speakers from CHANNEL_LOG filtered to the last 7 days, karma from KARMA ordered by score. Channels with no activity are silently skipped.

---

🤖 U8 — !ai forget

Users can now clear their own Claude session without needing Owner privileges — or bothering an operator:

<teuk> m ai forget
<mediabotv3> -teuk- Your Claude history and persona have been cleared.

Unlike !ai clear all (Owner only), !ai forget is scoped to the caller’s nick\x00channel key. Both _claude_history and _claude_persona are removed in one call.

---

🏆 V1 — !trivia start N — Multi-Round Tournament

<teuk> m trivia start 5
<mediabotv3> Trivia: starting 5-round game! Scores reset.
<mediabotv3> Round 1/5: ...

After each correct answer, a live scoreboard is shown:

<mediabotv3> Scores after round 3/5: teuk:2  Boole:1  Poyan:0

After the final round:

<mediabotv3> Game over! Final scores: teuk:3  Boole:2  Poyan:1

Scores persist in _trivia{$channel}{scores} across rounds. Max 20 rounds.

---

⏲️ V2 — Configurable Poll Timeout

!poll now accepts an optional leading number as the timeout in seconds:

<teuk> m poll 60 Best pizza? | 4 fromages | Regina
              ^^ 60-second timeout instead of the default 300

Range: 10–3600s. Default unchanged at 300s. Help updated.

---

🔄 V3 — !karmareset <nick> (Master)

Masters can now zero a nick’s karma directly from IRC — no SQL console needed:

<teuk> m karmareset boole
<mediabotv3> teuk reset karma for boole to 0.

require_level('Master') guard. Updates KARMA table directly. Dispatched from command_map and documented in help.

---

🖥️ V4 — Partyline .kick <nick> <#chan> [reason]

.kick spammer #boulets Read the rules
Kicked spammer from #boulets (Read the rules)

Sends KICK via $bot->{irc}->send_message. Default reason: Kicked by operator. Listed in .help.

---

🗑️ V6 — Scheduler: Daily KARMA_LOG Purge

A new karma_log_purge task runs every 24 hours and removes entries older than 90 days from KARMA_LOG. Wrapped in eval so the bot continues gracefully if the table doesn’t exist yet.

---

🏥 W6 — Scheduler: 6-Hour Health Check

Every 6 hours, the bot logs a one-line diagnostic:

[health_check] uptime=2d 3h db=ok claude_sessions=4 karma_cooldowns=12

Covers: uptime (days/hours/minutes), DB connectivity, active Claude history sessions, and open karma cooldown entries. No channel output — log level 3 (debug) only.

---

🔍 W7 — !note search <word>

<teuk> m note search unix
<mediabotv3> -teuk- 2 note(s) matching 'unix':
<mediabotv3> -teuk-   [1] Read the Unix philosophy book
<mediabotv3> -teuk-   [2] Check man pages for unix socket

Case-insensitive substring match across all of the caller’s notes. Scoped to the calling nick — others can’t search your notes.

---

📊 W8 — !pollstatus — Live Results Without Closing

<teuk> m pollstatus
<mediabotv3> "Best pizza?" -- 4 vote(s) so far:
<mediabotv3>   [1] 4 fromages: 3 (75%)
<mediabotv3>   [2] Regina: 1 (25%)

The poll stays active. Useful during a vote when curiosity strikes. !pollresult remains the command to actually close the poll.

---

🛠️ W2 — Configurable Claude Rate Limit

[anthropic]
RATE_MAX    = 10   # requests per window (default 5)
RATE_WINDOW = 120  # window in seconds  (default 60)

Both values are read at runtime per request — no restart needed. Clamped: RATE_MAX ≥ 1, RATE_WINDOW ≥ 10.

---

🧑‍💻 W4 — Partyline .who <#chan>

.who #boulets
9 nick(s) on #boulets:
  teuk [Master]  Boole [Voice]  Poyan        CyberGirl    Menz
  spammer        lurker         bot42        GuestX

Nicks are shown in sorted alphabetical order, in chunks of 8 per line. Where a bot-registered level exists in USER_CHANNEL, it is shown in brackets. Unknown nicks show no level tag.

---

🔁 V10 — Partyline .flushcooldown [#chan]

.flushcooldown #boulets
Karma cooldown cleared for #boulets.

.flushcooldown
All karma cooldowns cleared.

Immediately resets the _karma_cooldown hash for a single channel (or globally). Useful when a legitimate karma wave was blocked by the 30s anti-spam.

---

🧪 Tests (290–295)

#	File	Feature
290	290_usercommands_trivia_scores.t	W1: multi_total, Scores after round, Game over
291	291_external_claude_rate_config.t	W2: RATE_MAX, RATE_WINDOW, both used
292	292_partyline_who_chan.t	W4: _cmd_who_chan, gethChannelsNicksOnChan, levels
293	293_scheduler_health_check.t	W6: health_check, 21600, DB check, uptime
294	294_usercommands_note_search.t	W7: note search, _notes hash
295	295_usercommands_pollstatus.t	W8: mbPollStatus_ctx, live results, dispatch

Total test suite: 287 cases.

---

📦 Files Changed

File	Changes
UserCommands.pm	U3 live tally, U5 weighted choose, U6 karma cooldown, V1 trivia multi, V2 poll timeout, V3 karmareset, W1 final scores, W7 note search, W8 pollstatus
External.pm	U8 ai forget, W2 rate config
Partyline.pm	V4 .kick, V10 .flushcooldown, W4 .who chan
Mediabot.pm	Dispatchers + help for karmareset, pollstatus, updated trivia/note/poll
mediabot.pl	U7 weekly report, V6 KARMA_LOG purge, W6 health check
t/cases/279…295	17 test cases