================================================================================
BETTERBOT FRAMEWORK — DOCUMENTATION INDEX
================================================================================

Version   : 1.0.0
Author    : Rafli
License   : © 2026 Rafli. All rights reserved.
Language  : Python 3.8+
Platform  : Windows / Linux (TeamTalk 5 SDK required)

--------------------------------------------------------------------------------

DOCUMENT INDEX
==============

  00_overview.txt          Framework overview, philosophy, and architecture
  01_getting_started.txt   Installation, configuration, and first run
  02_configuration.txt     Full config.json field reference
  03_creating_modules.txt  Step-by-step guide to building a module
  04_base_module_api.txt   Complete BaseModule class API reference
  05_storage_system.txt    Persistent SQLite storage — API and patterns
  06_scheduler_system.txt  Task scheduler — recurring jobs and cron patterns
  07_eventbus_system.txt   Inter-module pub/sub event bus — API and patterns
  08_acl_and_security.txt  Access control, admin commands, and security model
  09_hot_reload.txt        Watchdog-powered hot-reload system
  10_builtin_commands.txt  Built-in admin commands reference
  11_advanced_patterns.txt Advanced usage: state machine, shared_data, tips
  12_context_object.txt    Rich command context, reply helpers, arg parsing
  13_metrics_system.txt     Telemetry, status report, and circuit breaker
  14_permissions_system.txt Advanced RBAC (7-tier roles), .role command
  15_conversations.txt     Multi-step interactive Wizards (Conversations)
  16_middleware.txt        Global before/after command interception

--------------------------------------------------------------------------------

QUICK REFERENCE — BUILT-IN COMMANDS
=====================================

  .help                    List all modules and their commands (public)
  .help <module_name>      Detailed info for a specific module (public)
  .status                  Show bot health, metrics, and errors (admin)
  .modules                 List active modules with versions (admin)
  .reload <module_name>    Hot-reload a specific module (admin)
  .reload all              Hot-reload all modules + scan for new ones (admin)
  .config reload           Reload config.json without restarting (admin)
  .role get/set/list       Manage user RBAC roles (admin)
  .shutdown                Gracefully shut down the bot (admin)

  NOTE: All commands also work with the "/" prefix (e.g. /reload all).

--------------------------------------------------------------------------------

QUICK REFERENCE — MODULE SHORTCUTS (in BaseModule subclasses)
==============================================================

  Messaging
  ---------
  self.reply(ctx, text)              Smart reply matching source context
  self.send_pm(user_id, text)        Send private message (rate-limited)
  self.send_channel_msg(ch_id, text) Send channel message (rate-limited)

  Storage (Persistent, SQLite)
  ----------------------------
  self.store(key, value)             Save a value to SQLite
  self.retrieve(key, default)        Load a value from SQLite
  self.delete_stored(key)            Remove a key from SQLite
  self.clear_storage()               Remove all keys for this module

  Scheduler (Recurring Tasks)
  ---------------------------
  self.schedule(name, func, interval)  Register a recurring task
  self.cancel(name)                    Remove a specific task
  self.cancel_all()                    Remove all tasks for this module

  Event Bus (Inter-Module Communication)
  --------------------------------------
  self.emit(event_name, data)          Publish an event
  self.subscribe(event_name, callback) Listen for an event
  self.unsubscribe(event_name, cb)     Stop listening for an event
  self.unsubscribe_all()               Remove all subscriptions

  Permissions (RBAC)
  ------------------
  self.get_role(ctx)                 Get Role object for the sender
  self.require_role(ctx, Role.DJ)    Check + deny if insufficient
  self.set_role(username, Role.DJ)   Assign a role

  Middleware & Conversations
  --------------------------
  self.add_middleware(fn, phase)     Add before/after command hook
  self.remove_all_middleware()       Clean up middleware
  self.bot.conversations.begin(...)  Start a multi-step Wizard

  Utilities
  ---------
  self.is_admin(user_id)             Check admin privilege
  self.bot.state                     Current BotState enum value
  self.shared_data                   In-memory cross-module dict
  self.log                           Module-scoped Python logger

================================================================================