# Lumi Bot

Discord bot + WebUI with role-based access, plugin management, and self-update support.

## Quick start

Requires Node.js 18+.

1. Install dependencies:
   ```
   npm install
   ```
2. Run with auto-restart:
   ```
   npm run run
   ```
3. Open `http://localhost:3000/setup` and enter your Discord app + bot settings.

You can also seed local configuration with a `.env` file. Use `.env.example`
as the template; `.env` is ignored by git.

## Discord app setup

- OAuth2 redirect URI: `http://localhost:3000/auth/discord/callback`
- OAuth2 scopes: `identify`, `guilds`, `guilds.members.read`
- Add the bot to your server and copy the Guild ID.

## WebUI roles

The WebUI maps Discord roles to access levels:
- `DISCORD_ADMIN_ROLE_ID`
- `DISCORD_MOD_ROLE_ID`

You can set these in `.env` or change role IDs in **Admin → Settings**.

## Plugins

Use **Admin → Plugins** to install, enable, update, or uninstall plugins.
You can also create a local plugin from the WebUI.

## Updates and recovery

Use **Admin → Updates** for version-aware core and plugin updates. Lumi reads
repo metadata from `main` by default, can explicitly target the newest
`experimental-*` branch, creates snapshots before updates, blocks unsafe major
jumps without compatibility bridge metadata, and keeps advanced ZIP updates
hidden behind manual reveal controls.

Recovery mode can be started with `LUMI_SAFE_MODE=1 npm run run`,
`node run.js --safe-mode`, or `data/recovery/safe-mode.flag`. See
[`docs/updates.md`](docs/updates.md) and
[`docs/recovery-mode.md`](docs/recovery-mode.md).

## Twitch bot

Configure Twitch chat settings in **Admin → Settings**:
- `twitch_bot_username`
- `twitch_bot_oauth` (OAuth token)
- `twitch_channels` (comma-separated)

Custom commands can target Discord, Twitch, or both from **Admin → Commands**.

## Users and linking

Users have an internal UUID and username. Link Twitch accounts in **Profile** and manage usernames in **Profile** or **Admin → Users**.

## Theming

Use **Admin → Theming** to select one of six read-only Lumi themes. Duplicate a
built-in or custom theme to edit colors, surfaces, controls, status colors,
focus states, radius, shadows, and spacing with a live light/dark preview.
Custom themes can be applied, renamed, duplicated, and deleted. Invalid or
incomplete values fall back safely to the selected built-in base theme.

Developer and modding conventions are documented in
[`docs/lumi-ui.md`](docs/lumi-ui.md).

## Notes

- Auto-update uses `git pull` from the configured remote + branch.
- Auto-restart uses `run.js` to respawn the process after updates or crashes.