add blue archive gacha simulator cog with live banners and wiki portraits

AGENTS.md

@@ -0,0 +1,69 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+```
+yuuka/
+├── main.py               # Bot entry point, cog loader, bridge initialization
+├── cogs/                  # Discord command modules (general, sysinfo, gifs, etc.)
+├── ai/                    # AI roleplay integration (DeepSeek API, per-channel personas)
+│   └── personalities/     # Character prompt files
+├── music/                 # Music playback subsystem (wavelink + yt-dlp + ffmpeg)
+│   ├── player/            # Playback commands, events, queue management
+│   ├── radio/             # Internet radio streaming
+│   └── shared/            # Constants, shared state, utilities
+├── tgbridge/              # Telegram ↔ Discord two-way message forwarding
+├── twitterbridge/         # Twitter/X RSS feed → Discord webhook relay
+├── rio/                   # SSH connection utilities
+├── data/                  # Runtime persistence files (gitignored)
+├── gifs/                  # GIF assets (gitignored)
+└── credentials_test.env   # Environment variable template
+```
+
+Each cog is a self-contained `commands.Cog` subclass loaded in `main.py`. Bridge components run as background `asyncio` tasks.
+
+## Build, Test, and Development Commands
+
+This is a personal bot with no formal build system. Run it directly:
+
+```bash
+python main.py
+```
+
+- Copy `credentials_test.env` → `credentials.env` and fill in your tokens.
+- There is no test suite. Test by running the bot locally and using `!`-prefixed commands in a Discord server.
+
+## Coding Style & Naming Conventions
+
+- **Language**: Python 3.12+
+- **Indentation**: 4 spaces
+- **Naming**: `snake_case` for files, variables, and functions; `PascalCase` for classes; `UPPER_CASE` for constants
+- **Cogs**: One class per file in `cogs/`, subclassing `commands.Cog`, loaded via `await bot.load_extension('cogs.<name>')`
+- **Music subpackage**: Uses mixin-based composition — `Music` inherits from several command/event mixins
+- **Async**: All I/O uses `async`/`await`; bridge tasks run with `asyncio.create_task()`
+- No linter or formatter is currently configured
+
+## Testing Guidelines
+
+No formal test framework is in place. When adding or changing features, validate manually:
+
+1. Start the bot locally with a test Discord token.
+2. Exercise each affected command in a private server.
+3. For music/radio, test with different stream types (YouTube, direct audio URLs, radio streams).
+4. For bridges, confirm messages flow correctly in both directions.
+5. Check the console for unhandled exceptions — the `logging` level is `INFO`.
+
+## Commit & Pull Request Guidelines
+
+This is a personal repository with informal conventions:
+
+- **Commit messages**: Short, lowercase, imperative mood (e.g., `fix radio race conditions`, `add radio mode`). No strict format is enforced.
+- **Branches**: Work directly on `master` or use short-lived feature branches.
+- **PRs**: Not used — the project is single-contributor.
+- **Before committing**: Ensure the bot starts without import errors and any changed cogs load successfully.
+
+## Environment & Secrets
+
+- Store secrets in `credentials.env` (gitignored). The template is `credentials_test.env`.
+- Required: `DISCORD_TOKEN`, `OWNER_ID`. Optional: `TELEGRAM_BOT_TOKEN`, `TWITTER_RSS_URL`, `DEEPSEEK_API`, and webhook URLs.
+- The bot is managed as a `systemd` service on Arch Linux and updated via `git pull` over SSH (the `!gitpull` cog handles remote updates).