Overview

No dramatic new commands — just the steady, necessary work of making the bot discoverable, reliable, and configurable. Thirty-one help entries written, eight crash-causing bugs silenced, and six quality-of-life improvements shipped across the Claude and YouTube stacks.

“Nox Lumos! The darkness of undocumented features is lifted. Every spell now has a name.” 📖✨

📖 D1 — 31 Missing Help Entries

!help now covers every command added since Wave IV. Previously, asking for help on !karma, !ai, !roll, or !trivia returned nothing.

<teuk> m help ai
<mediabotv3> ai <prompt> — Ask Claude (Anthropic) a question. Requires Claude
             chanset. ai reset clears history, ai history shows context.

<teuk> m help trivia
<mediabotv3> trivia — Start a trivia question from Open Trivia DB (30s to answer).

<teuk> m help karmatop
<mediabotv3> karmatop [n] — Show the top N karma scores on the channel (default 5).

New entries by category:

🐛 Bug — @{ $message->args } Crash on IRC Events

Severity: HIGH — The bot crashed on certain IRC server messages (RPL_WHOREPLY, RPL_LIST, KILL, SERVER, etc.) with:

Can't use string ("8") as an ARRAY ref while "strict refs" in use
at ./mediabot.pl line 1994.

Cause: $message->args returns a scalar on some message types rather than an array reference. @{ "8" } is illegal under strict refs.

Fix: All 8 occurrences wrapped in the defensive pattern already used by log_debug_args():

# Before — crashes if ->args returns a scalar
my ($chan, $users, $topic) = @{ $message->args };

# After — safe
my @list_args = eval { @{ $message->args // [] } } // ();
my ($chan, $users, $topic) = @list_args;

🤖 A1 — !ai History Depth Configurable

The conversation history cap was hardcoded at 6 messages (3 exchanges). Now configurable:

[anthropic]
MAX_HISTORY = 6     # default — 3 user+assistant exchanges
MAX_HISTORY = 10    # richer context — 5 exchanges
MAX_HISTORY = 2     # minimal — saves tokens

Range: 2–20 (always rounded to an even number). Applied at every !ai call — a .reload is enough to change it without restart.

🎬 A2 — !yt search Result Cache (5 min)

!yt search made two YouTube API calls per search (search + video metadata). Repeated searches on a busy channel hit rate limits quickly.

Results are now cached for 5 minutes under search:lc($query) in the same _yt_cache hash used by !yt <url>. A second identical search in the same window returns instantly from cache — zero API calls.

🖥️ A3 — Partyline .ai Now Has Full History

The Partyline .ai command now maintains a real conversation context — same mechanism as IRC !ai, keyed by login\x00channel.

.ai what is Net::Async::IRC?
[Claude] Net::Async::IRC is an asynchronous IRC client library for Perl...

.ai and how does Mediabot use it?
[Claude] Mediabot builds its entire event loop on top of it...

.ai history
  4 message(s) in context:
    [user] what is Net::Async::IRC?
    [assistant] Net::Async::IRC is an asynchronous IRC client library...
    [user] and how does Mediabot use it?
    [assistant] Mediabot builds its entire event loop on top of it...

.ai reset
Conversation history cleared.

Also fixed: the Claude chanset gate was blocking Partyline requests (already-authenticated operators don’t need a per-channel opt-in).

📊 A4 — !ai quota

<teuk> m ai quota
<mediabotv3> -teuk- AI quota: 3/5 request(s) remaining (window resets in 42s)

<teuk> m ai quota     ← before first use
<mediabotv3> -teuk- AI quota: 5/5 requests available (window not started).

Shows remaining requests in the current 60-second rate-limit window. No API call — reads directly from the in-memory _claude_ratelimit hash.

📖 A5 — !define Language Configurable

[main]
DEFINE_LANG = fr    # uses fr.wiktionary.org — default: en

<teuk> m define sérendipité
<mediabotv3> sérendipité [fr]: Faculté de faire par hasard des découvertes...

Language code is validated (/^[a-z]{2,5}$/). The [lang] tag is appended to the output when not English. Fallback to en if unset or invalid.

📦 Files Changed