Merge branch 'main' into feature/moderation-dashboard

Light up the moderation dashboard's previously-empty widgets by persisting the
event streams the bot only reacted to in-memory before.

Schema (bot-owned)
- member_events: join/leave, with invite_code/inviter_* for best-effort invite
  attribution on joins
- filter_hits: word / foreign-invite filter deletions (matched + action_taken)
- spam_hits: rate_limit / mass_mention / mass_emoji detections

Bot
- new models memberEvents/filterHits/spamHits
- guildMemberAdd records the join with invite attribution; new inviteTracker.js
  keeps an invite-use cache (GuildInvites intent + inviteCreate/inviteDelete) and
  diffs it on join to find which invite was used — best-effort, never blocks
  auto-role
- new guildMemberRemove records leaves
- messageFilter records filter/spam hits alongside the existing warn/mute;
  inviteFilter now returns the offending code; detectSpam identifies which spam
  rule tripped (preserving the rate-limit-first side-effect order)
- mod_actions still logs the resulting warn/mute — the new tables are additive

Server
- summary extended with joins/leaves/invite_joins/filter_hits/spam_hits per window
- new feeds: /api/v1/admin/moderation/{members,filter-hits,spam-hits}

Client
- overview now shows 8 tiles (mod actions + joins/leaves/filter/spam, joins tile
  notes "N via invite") plus an Events panel with Members/Filter/Spam tabs;
  removed the coming-soon note

Verified: 119 server unit tests, client build, 14-check DB-backed smoke, and a
browser click-through of every tile and events tab (incl. invite attribution).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rao86n5cXpwAyjdBFEshV

.claude/launch.json

@@ -0,0 +1,23 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "client",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "--prefix", "client"],
+      "port": 5173
+    },
+    {
+      "name": "server",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "--prefix", "server"],
+      "port": 3000
+    },
+    {
+      "name": "bot",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev", "--prefix", "bot"],
+      "port": 4100
+    }
+  ]
+}

.env.example

@@ -4,6 +4,10 @@
 # App
 NODE_ENV=production
 PORT=3000
+# Separate, UNPUBLISHED port for server<->bot internal traffic (the decrypted
+# bot-token route). Must match the port in the bot's SITE_INTERNAL_URL
+# (docker-compose.yml) and must NEVER be published/proxied. See issue #33.
+INTERNAL_PORT=3001
 UPLOAD_DIR=/app/uploads
 # Logging — written to BOTH the console and a log file.
 LOG_LEVEL=info          # console verbosity: error | warn | info | debug
@@ -12,7 +16,8 @@ LOG_TO_FILE=true        # set false for console-only
 LOG_DIR=/app/logs       # log directory inside the container (bind-mounted to ./logs)
 LOG_FILE=app.log
 
-# Database (the values here are shared by the `db` and `app` containers)
+# Database (the values here are shared by the `db`, `app`, and `bot` containers —
+# the bot only ever touches its own tables: guild_config, mod_actions, warnings)
 DB_HOST=db
 DB_PORT=3306
 DB_NAME=uomysticmoon
@@ -28,6 +33,21 @@ JWT_EXPIRES_IN=1d
 COOKIE_SECURE=auto
 COOKIE_NAME=uomm_token
 
+# Reverse-proxy trust (req.ip / req.secure for rate limiting, backoff, bot-ban).
+# Path: client -> Pangolin -> newt agent "ptero" (separate VM) -> app. Pin this
+# to ptero's LAN IP (e.g. 10.0.0.42) so XFF is only trusted from ptero. Requires
+# a static DHCP reservation for ptero in Omada, else a lease change breaks it.
+# Integer hop count or "false" also accepted; a blanket "true" is rejected
+# (coerced to 1) to prevent X-Forwarded-For spoofing.
+TRUST_PROXY=1
+# Set to 1 to log raw peer address + X-Forwarded-For + resolved req.ip per
+# request (to verify/refresh ptero's IP without redeploying). Noisy; keep off.
+DEBUG_TRUST_PROXY=0
+
+# Optional TOTP two-factor (opt-in per user).
+TOTP_ISSUER=UOMysticmoon
+TOTP_CHALLENGE_TTL=5m
+
 # First admin bootstrap — created only if no users exist yet.
 # Set, run once, then you can blank these out.
 ADMIN_USERNAME=
@@ -43,3 +63,19 @@ CONTACT_TO=UOMysticmoon@gmail.com
 
 # CORS — only needed for local dev when the Vite dev server is a different origin.
 CLIENT_ORIGIN=http://localhost:5173
+
+# Discord bot — internal API (server <-> bot/, see docker-compose.yml's `bot`
+# service). BOT_INTERNAL_KEY MUST be byte-for-byte identical to the same
+# variable in bot/.env.example — it is the only auth on both sides' /internal/*
+# routes, so a mismatch silently breaks every server<->bot call with 401s.
+# It also guards the server's /internal/bot-config route, which returns the
+# DECRYPTED Discord token; with NODE_ENV=production the app REFUSES TO START if
+# this is left blank, at this placeholder, or shorter than 16 chars. Generate a
+# long random string. The Discord bot TOKEN itself is not an env var — it's
+# entered in the admin panel (Discord Bot page) and stored encrypted in the DB.
+#
+# Defense in depth: even with a strong key, configure Pangolin/your reverse
+# proxy to DENY /api/v1/internal (and never forward INTERNAL_PORT). The route no
+# longer rides the public listener, but an explicit deny rule is belt-and-braces.
+BOT_INTERNAL_URL=http://bot:4100
+BOT_INTERNAL_KEY=change-me-to-a-long-random-string

.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 .claude/settings.local.json
 .vscode/
 .idea/
+
+# scratch / temp scripts
+_*.ps1

HERO_EDITOR.md

@@ -0,0 +1,134 @@
+# UOMysticmoon — Hero Canvas Editor Spec
+
+> Branch: **`hero-feature`**. Build contract for the WYSIWYG portal-hero editor.
+> Derived from the design doc *Hero Canvas Editor — Design Document*, **corrected
+> to match the current codebase** and with the open questions resolved.
+> Same workflow as the wiki upgrade: design → phased build → verify.
+
+## 1. Goal
+
+Let staff compose the portal hero (background image, overlay opacity, and floating
+elements — text, CTA buttons, moon, badge, image) in-browser, then preview and
+publish — no source edits. Layout persists as JSON in the existing `settings` table.
+
+## 2. Locked decisions
+
+| # | Decision |
+|---|---|
+| Scope | **Full v1** — background/overlay, all element types, drag/resize/z-order, draft→preview→publish (built in phases) |
+| CTA buttons | **First-class `buttons` element type** (independently positioned), not baked into a text block |
+| First run | **Pre-populate** the canvas with today's hero (headline, subtitle, teaser, CTAs) as editable elements so nothing changes visually until edited |
+| Drag | **Native Pointer Events** (mouse/touch/pen), zero dependencies |
+| Font size | Stored in **px** (fixed reference canvas) |
+| Image compression | **None** server-side; client warns when a file is > ~1 MB |
+| Preview | `?preview=1` renders the **draft** by reading it through the authenticated admin settings endpoint |
+| Other pages | Out of scope for v1 (design allows a per-page key later) |
+
+## 3. Corrections to the design doc (current-code reality)
+
+1. **Public settings is a whitelist, not `getAll()`.** `GET /api/v1/public/settings`
+   → `settings.getPublic()` → `PUBLIC_KEYS` in
+   [settings.model.js](server/src/model/settings/settings.model.js). The doc's
+   "no backend changes / picked up automatically" is wrong. **Fix:** add
+   `hero_layout` to `PUBLIC_KEYS` (one line). `hero_layout_draft` stays out
+   (admin-only) — which is why preview reads the draft via `api.admin.getSettings()`.
+2. **Moon is a reusable component** ([MoonDot.jsx](client/src/components/MoonDot.jsx),
+   props `size`/`glow`), used in logo/login/maintenance — not "only the header."
+   The `moon` element reuses it; it gains an optional `color`.
+3. **Route vs. nav live in different files.** `/admin/hero` route →
+   [App.jsx](client/src/App.jsx); sidebar link/title → `NAV`/`TITLES` in
+   [AdminLayout.jsx](client/src/routes/admin/AdminLayout.jsx).
+4. **Admin content area is `maxWidth: 1000px`** — the editor canvas renders
+   scaled-to-fit; percentage positions stay faithful.
+
+Everything else in the doc matches (hardcoded `HERO_BG` + CTAs + `homepage_teaser`
+in [Portal.jsx](client/src/routes/public/Portal.jsx); `updateSettings` accepts
+arbitrary keys; `/admin/uploads` exists; default hero asset present; TEXT settings
+columns — no schema change).
+
+## 4. Data model — no schema change
+
+Two `settings` keys (TEXT): `hero_layout` (live) and `hero_layout_draft` (admin).
+
+```jsonc
+{
+  "version": 1,
+  "background": { "image_url": null, "position_x": "left", "position_y": "center", "size": "cover" },
+  "overlay": { "opacity": 0.72 },
+  "elements": [
+    { "id": "uuid", "type": "text_block|buttons|moon|badge|image",
+      "x": 50, "y": 42, "z": 1, "anchor": "center", "props": { /* per type */ } }
+  ]
+}
+```
+
+Positions are **% of canvas** (reference width 1080, matching `.shell`), so the
+layout adapts across viewports without breakpoint data. `version` is validated
+(`=== 1`) before use; anything else falls back.
+
+### Element props
+
+| Type | Props |
+|---|---|
+| `text_block` | `lines: [{ text, tag(h1/h2/p/span), fontSize(px), color, weight }]`, `align` |
+| `buttons` | `items: [{ label, to, variant(primary/ghost) }]`, `align`, `gap` |
+| `moon` | `size`, `glow`, `color` |
+| `badge` | `text`, `bgColor`, `textColor`, `borderRadius` |
+| `image` | `src`, `width`(%), `alt` |
+
+## 5. Backend changes
+- **One line:** add `'hero_layout'` to `PUBLIC_KEYS`. No new routes/controllers —
+  layout saves through the existing `PUT /admin/settings`; images via `/admin/uploads`.
+
+## 6. Frontend changes
+- **New** `client/src/components/HeroElement.jsx` — renders one element by type
+  (shared by the live portal and the editor canvas).
+- **New** `client/src/routes/admin/views/HeroEditor.jsx` — canvas + element tray +
+  properties panel; native-pointer drag/resize; background/overlay panel; snap grid;
+  auto-save draft, preview, publish, revert.
+- **Edit** [Portal.jsx](client/src/routes/public/Portal.jsx) — parse `hero_layout`
+  (or draft when `?preview=1` + admin), render elements, fall back to a
+  `DEFAULT_LAYOUT` built from today's hero so the page is unchanged until edited.
+- **Edit** [AdminLayout.jsx](client/src/routes/admin/AdminLayout.jsx) (nav) +
+  [App.jsx](client/src/App.jsx) (route `/admin/hero`).
+- **Edit** [MoonDot.jsx](client/src/components/MoonDot.jsx) — optional `color`.
+- **No** `client/src/api/client.js` changes needed beyond what exists
+  (`admin.updateSettings`, `admin.getSettings`, `admin.upload`).
+
+## 7. Phased build (each phase: build → verify in preview → commit)
+
+- **Phase 0 — Spec** ✅ this document.
+- **Phase 1 — Data path & renderer** ✅ (verified 2026-06-28). `hero_layout`
+  whitelisted; `HeroElement.jsx`; Portal renders the layout with a `DEFAULT_LAYOUT`
+  fallback. Default render matches the old hero; publishing a layout re-renders;
+  draft key not exposed publicly. Shared helpers moved to `client/src/lib/heroLayout.js`.
+- **Phase 2 — Editor shell + background/overlay** ✅ (verified 2026-06-28).
+  `/admin/hero` view + sidebar nav; canvas live-preview; background upload + 3×3
+  position + overlay opacity; debounced draft auto-save; publish; `?preview=1`
+  reads the draft (admin) with a banner; revert. Verified: overlay/position update
+  the canvas, auto-save writes the draft, publish writes live, preview shows the
+  draft while the normal portal shows live.
+- **Phase 3 — Elements: select / drag / text_block / buttons** ✅ (verified
+  2026-06-28). Element tray (+ Text / + Buttons); click-to-select with outline;
+  native Pointer Events drag (% of canvas); Delete key + panel delete; z-order
+  (send back / bring forward); text_block line editor (text/tag/size/color/bold,
+  add/remove lines, align) and buttons editor (label/path/variant, add/remove).
+  Verified: select shows the line editor, editing a line updates the canvas live,
+  drag moved 50%→65%, add→3/delete→2 elements, empty-canvas click deselects.
+- **Phase 4 — moon + badge + image + resize + snap grid** ✅ (verified 2026-06-28).
+  Tray adds moon/badge/image; property panels (moon: size/glow/color; badge:
+  text/colors/radius; image: upload/width/alt); corner resize handle (image→width%,
+  moon→size, text→box width); 8px snap-grid toggle with overlay; image placeholder
+  until a file is chosen. Verified: each type adds + edits, resize moved a moon
+  64→104px, snap grid shows, and a published moon+badge render on the live portal.
+
+**Status: v1 feature-complete.** All phases verified end-to-end; ready for PR.
+Deferred (noted in the design doc as follow-ups): 8-point resize (only a corner
+handle for now), per-viewport layouts, server-side image compression.
+
+## 8. Edge cases (from the doc, carried forward)
+- `JSON.parse` wrapped in try/catch + `version` check → fall back to `DEFAULT_LAYOUT`.
+- Element ids via `crypto.randomUUID()` (never array index).
+- Empty `elements` → render `DEFAULT_LAYOUT` so the hero is never blank.
+- Last-write-wins on concurrent admin edits (acceptable for this shard).
+- Client-side warning for background files > ~1 MB (no hard block; 8 MB server cap).

README.md

@@ -1,63 +1,352 @@
 # UOMysticmoon Website
 
-Public site, wiki, and protected admin panel for the UOMysticmoon private Ultima Online
-shard. Built on the `serverlinkr` layered pattern: **Express + MariaDB + JWT** backend and a
-**React + Vite** frontend in the same repo, deployed with **Docker Compose** behind a
-**Pangolin** reverse proxy.
+Public site, wiki, and protected admin panel for the **UOMysticmoon** private Ultima Online
+shard — a full-stack app in one repo:
 
-> Build order: **(1) backend** (this phase) → (2) frontend design (Claude Design) →
-> (3) frontend coding. See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) for the full design.
+- **Backend** — Node.js + Express REST API (layered `router → controller → model → db`), MariaDB, a provider-agnostic session layer (JWT cookie for web, bearer tokens for mobile, pluggable SSO).
+- **Frontend** — React + Vite single-page app (public site, wiki, and the admin panel), dark "gothic" theme (Cinzel + Georgia).
+- **Deploy** — Docker Compose (app + MariaDB) behind a Pangolin reverse proxy. Express serves the built SPA in production.
 
-## Layout
+The design reference is [BACKEND_DESIGN.md](BACKEND_DESIGN.md) (API contract, schema, security).
+
+---
+
+## Contents
+
+- [Tech stack](#tech-stack)
+- [Project structure](#project-structure)
+- [Prerequisites](#prerequisites)
+- [Setup & run](#setup--run)
+  - [Option A — Docker Compose (full stack)](#option-a--docker-compose-full-stack)
+  - [Option B — Local development (hot reload)](#option-b--local-development-hot-reload)
+  - [Option C — Production build without Docker](#option-c--production-build-without-docker)
+- [First admin & site mode](#first-admin--site-mode)
+- [Pages & routes](#pages--routes)
+- [API endpoints](#api-endpoints)
+- [API documentation (Swagger)](#api-documentation-swagger)
+- [Environment variables](#environment-variables)
+- [Security](#security)
+- [Logging](#logging)
+- [Deployment behind Pangolin](#deployment-behind-pangolin)
+
+---
+
+## Tech stack
+
+| Layer | Tech |
+|---|---|
+| Backend | Node.js 20+, Express 4, `mariadb` driver (parameterized SQL, no ORM) |
+| Auth | Session service over JWT: httpOnly cookie (web) + bearer access/refresh tokens (mobile), bcrypt hashing, optional TOTP 2FA (`speakeasy` + `qrcode`), pluggable OAuth2/OIDC SSO (built-in Google & Discord + generic) |
+| Database | MariaDB 11 (own container) |
+| Frontend | React 18, Vite 5, React Router 6 |
+| Email | Nodemailer (SMTP) with a `mailto:` fallback |
+| API docs | OpenAPI 3.0 via `swagger-autogen`, served with `swagger-ui-express` at `/api/docs` |
+| Deploy | Docker Compose, Pangolin reverse proxy |
+
+---
+
+## Project structure
 
 ```
-server/   Express API (router → controller → model → db), MariaDB schema + seed
-client/   React + Vite SPA  (added in the frontend phase)
-Dockerfile, docker-compose.yml, .env.example
+UOMSITE/
+├─ server/                     Express API
+│  ├─ src/
+│  │  ├─ server.js             bootstrap: ensure schema → seed → listen (0.0.0.0)
+│  │  ├─ app.js                middleware + static SPA + routes
+│  │  ├─ auth/                 session layer: session.service · token (JWT/cookies) · session.middleware · ssoState (PKCE/CSRF) · providers/ (base · oauth2 · google · discord · genericOidc · registry)
+│  │  ├─ router/v1/            auth (web · mobile · sso) / public / admin route groups
+│  │  ├─ model/                users · posts · wiki · settings · activity · mobileSessions · authProviders · userIdentities (.model + .db)
+│  │  ├─ middleware/           siteMode · noindex · rateLimit · loginProtection · botScore · validate
+│  │  └─ utils/                auth (compat facade) · totp (2FA) · secretBox (AES-GCM secrets) · db (pool) · mailer · logger
+│  ├─ db/                      schema.sql + seed.js
+│  ├─ swagger/                 swagger.js (OpenAPI generator config) + swagger-output.json (generated spec)
+│  └─ .env.example
+├─ client/                     React + Vite SPA
+│  ├─ src/
+│  │  ├─ routes/public/        Portal, Website, News, Screenshots, FiveOnFriday, Newsletter(+Issue), Status, About, Maintenance
+│  │  ├─ routes/wiki/          Wiki landing + WikiArticle
+│  │  ├─ routes/admin/         AdminLogin (password + TOTP + SSO buttons), AdminLayout, views/ (Dashboard, Posts, Wiki, Settings, Activity, Bot Activity, Authentication, Users, Account) + editors
+│  │  ├─ components/           SiteHeader, SiteFooter, layout, guards, Modal, ProviderIcon (inline SSO SVGs), …
+│  │  ├─ contexts/             AuthContext, SiteContext
+│  │  ├─ api/client.js         fetch wrapper (sends cookies)
+│  │  └─ styles/theme.css      design tokens
+│  └─ public/assets/img/       hero image
+├─ Dockerfile                  builds client → serves via Express
+├─ docker-compose.yml          app + MariaDB
+├─ .env.example                root env (used by Compose)
+└─ package.json                workspace scripts
 ```
 
-## Quick start (local dev)
+---
+
+## Prerequisites
+
+- **Node.js 20+** and npm (Node 22/24 are fine).
+- **Docker Desktop** (for MariaDB, and for the full Compose deploy).
+
+---
+
+## Setup & run
+
+### Option A — Docker Compose (full stack)
+
+The simplest way to run everything. The image installs server deps, **builds the React client**,
+and Express serves it; MariaDB runs in its own container; tables + defaults + the first admin are
+created automatically on first boot.
 
 ```bash
-# 1. Start a MariaDB (or use your own and set DB_* in server/.env)
-docker compose up -d db
+cp .env.example .env
+# Edit .env and set at least:
+#   DB_PASSWORD, DB_ROOT_PASSWORD   (any strong values)
+#   JWT_SECRET                      (a long random string)
+#   ADMIN_USERNAME, ADMIN_PASSWORD  (your first admin login)
 
-# 2. Configure + install
-cp server/.env.example server/.env      # edit DB_*, JWT_SECRET, ADMIN_USERNAME/PASSWORD
+docker compose up -d --build
+```
+
+- App: **http://localhost:3000** (binds `0.0.0.0`)
+- Health check: `GET http://localhost:3000/api/health` → `{ "status": "ok" }`
+- Logs: `docker compose logs -f app` (and `./logs/app.log` on the host)
+- Stop: `docker compose down` (add `-v` to also wipe the database + uploads volumes)
+
+### Option B — Local development (hot reload)
+
+Run the API and the Vite dev server separately. The Vite server proxies `/api` and `/uploads`
+to the backend, so the SPA stays same-origin (cookies work).
+
+**1. Start a MariaDB the backend can reach** (published on `localhost:3306`):
+
+```bash
+docker run -d --name uomm-db -p 3306:3306 -e MARIADB_DATABASE=uomysticmoon -e MARIADB_USER=uomm -e MARIADB_PASSWORD=devpass -e MARIADB_ROOT_PASSWORD=rootpass mariadb:11
+```
+
+**2. Configure + start the backend** (terminal 1):
+
+```bash
+cp server/.env.example server/.env
+# Set DB_HOST=127.0.0.1, DB_PORT=3306, DB_USER=uomm, DB_PASSWORD=devpass,
+#     JWT_SECRET=<anything>, ADMIN_USERNAME=admin, ADMIN_PASSWORD=<your password>
 npm run install-server
-
-# 3. Run the API (creates tables, seeds defaults + first admin on boot)
-npm run server                           # http://localhost:3000  (API at /api/v1)
+npm run server          # nodemon → http://localhost:3000
 ```
 
-`GET /api/health` → `{ "status": "ok" }` confirms it's up.
-
-## Deploy (Docker Compose)
+**3. Start the frontend** (terminal 2):
 
 ```bash
-cp .env.example .env                      # fill in DB creds, JWT_SECRET, admin, SMTP
-docker compose up -d --build              # app on 0.0.0.0:3000, MariaDB on the internal network
+npm run install-client
+npm run client          # Vite → http://localhost:5173
 ```
 
-Point Pangolin at the `app` container on port 3000. The auth cookie auto-detects HTTPS, so
-the admin panel works both via the LAN IP (HTTP) and through the proxy (HTTPS). The full app
-image build requires `client/` (frontend phase); until then the server runs API-only.
+Develop at **http://localhost:5173** (hot reload). On Windows, the Vite proxy targets
+`127.0.0.1:3000` to avoid the IPv6-`localhost` pitfall.
 
-## Key endpoints
+> Tip: `npm run install-all` installs both server and client deps in one go.
+
+### Option C — Production build without Docker
+
+Build the SPA and let Express serve it on a single port (still needs a MariaDB + `server/.env`):
+
+```bash
+npm run install-all
+npm run build           # → client/dist
+npm start               # node server → serves API + SPA at http://localhost:3000
+```
+
+---
+
+## First admin & site mode
+
+- On first boot, if the `users` table is empty and `ADMIN_USERNAME` / `ADMIN_PASSWORD` are set,
+  the first admin is created automatically. You can also run `npm run seed`. After it exists you
+  may blank those env vars.
+- The site **starts in `maintenance` mode**: public visitors see the polished "coming soon" page;
+  the admin login and panel are always reachable.
+- Sign in at **`/admin/login`**, then flip **Maintenance → Live** from the Dashboard. A logged-in
+  admin can preview the live site even while it's in maintenance.
+
+---
+
+## Pages & routes
+
+**Public** (gated by site mode):
+
+| Route | Page |
+|---|---|
+| `/` | Portal landing (hero + destinations) |
+| `/site` | Website index (section cards) |
+| `/site/news` | News feed |
+| `/site/screenshots` | Screenshot gallery |
+| `/site/five-on-friday` | Five on Friday |
+| `/site/newsletter` · `/site/newsletter/:id` | Newsletter list + issue |
+| `/site/about` · `/site/status` | About · Shard status |
+| `/wiki` · `/wiki/:slug` | Wiki landing + article (auto table-of-contents) |
+
+**Admin** (cookie auth, `noindex`):
+
+| Route | View |
+|---|---|
+| `/admin/login` | Sign in |
+| `/admin` | Dashboard (mode toggle, stats, recent activity) |
+| `/admin/posts` | Posts CRUD + publish + image upload |
+| `/admin/wiki` | Wiki pages CRUD |
+| `/admin/settings` | Site settings |
+| `/admin/activity` | Activity log |
+| `/admin/bot-activity` | Bot activity — banned IPs + recent scoring events, emergency unban (admin only) |
+| `/admin/auth-providers` | Authentication — enable/configure SSO providers: built-in Google & Discord + custom OIDC/OAuth2 (admin only) |
+| `/admin/users` | User management |
+| `/admin/account` | Account security (self-service TOTP two-factor + linked SSO accounts) |
+
+---
+
+## API endpoints
 
 | Group | Base | Auth |
 |---|---|---|
-| Auth | `/api/v1/auth` (`login`, `logout`, `me`) | cookie |
-| Public | `/api/v1/public` (`settings`, `status`, `posts/:category`, `wiki`, `contact`) | none |
-| Admin | `/api/v1/admin` (dashboard, site-mode, posts, wiki, settings, activity, users) | cookie (admin) |
+| Auth (web) | `/api/v1/auth` (`login`, `login/totp`, `logout`, `me`) | cookie |
+| Auth (mobile) | `/api/v1/auth/mobile` (`login`, `refresh`, `logout`) | bearer (access + refresh tokens) |
+| SSO | `/api/v1/auth` (`providers` — public discovery; `sso/:provider/start`, `sso/:provider/link`, `sso/:provider/callback`) | redirect flow |
+| Public | `/api/v1/public` (`settings`, `status`, `posts/:category`, `posts/:category/:idOrSlug`, `wiki`, `wiki/:slug`, `contact`) | none |
+| Admin | `/api/v1/admin` (`dashboard`, `site-mode`, `posts`, `posts/upload`, `wiki`, `settings`, `activity`, `bot-activity`, `bot-activity/unban`, `auth/providers` (CRUD), `users`, `account`, `account/totp/*`, `account/identities`) | cookie (admin) |
 
-See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) §4 for the complete contract.
+Post categories (URL form): `news`, `five-on-friday`, `newsletter`, `screenshots`.
+`authMethod` on a session ∈ `local · totp · mobile · google · discord · oidc`.
+See [BACKEND_DESIGN.md](BACKEND_DESIGN.md) §4 for the full contract, or the interactive Swagger
+docs below for a per-endpoint reference (parameters, request bodies, response codes).
 
-## Security notes
+---
 
-JWT in an httpOnly cookie · bcrypt hashing · login rate limiting · admin routes `noindex` ·
-first admin seeded from env (no hardcoded credentials) · `.env` is git-ignored. SMTP is
-optional — the contact form falls back to a `mailto:` link when SMTP is not configured.
+## API documentation (Swagger)
+
+The full API is documented as an **OpenAPI 3.0** spec and served with **Swagger UI**:
+
+| URL | What |
+|---|---|
+| `http://localhost:3000/api/docs` | Interactive Swagger UI (try-it-out, auth) |
+| `http://localhost:3000/api/docs.json` | Raw OpenAPI 3.0 spec (JSON) |
+
+Every endpoint is tagged and grouped (Auth, Auth · Mobile, Auth · SSO, Public, and the Admin
+groups) with its summary, parameters, request body, security requirement, and the response codes it
+actually returns (`400` validation, `401`/`403` auth, `404`, `409` conflicts, `429` rate limits, …).
+
+**Authentication in the UI** — click **Authorize** and provide either:
+
+- `cookieAuth` — the `uomm_token` session cookie (set automatically in the browser after
+  `POST /api/v1/auth/login`), or
+- `bearerAuth` — a mobile access token from `POST /api/v1/auth/mobile/login` (sent as
+  `Authorization: Bearer <token>`).
+
+**Regenerating the spec** — the spec is generated from `#swagger.*` annotations next to each route
+(`server/src/router/**`) plus the shared definitions in `server/swagger/swagger.js`
+([swagger-autogen](https://github.com/davibaltar/swagger-autogen)). The output
+`server/swagger/swagger-output.json` is committed so the docs work with no build step. After adding
+or changing a route, regenerate it:
+
+```bash
+cd server
+npm run swagger        # → server/swagger/swagger-output.json
+```
+
+If the generated spec is missing, the server logs a warning and simply disables `/api/docs` (it does
+not crash).
+
+---
+
+## Environment variables
+
+Copy `.env.example` (Compose) or `server/.env.example` (local) and fill in. **`.env` is git-ignored.**
+
+| Var | Default | Notes |
+|---|---|---|
+| `NODE_ENV` | `production` | |
+| `PORT` | `3000` | server listens on `0.0.0.0:PORT` |
+| `UPLOAD_DIR` | `<server>/uploads` | where post images are written (`/app/uploads`, volume-mounted, in Compose) |
+| `DB_HOST` / `DB_PORT` | `db` / `3306` | `db` in Compose; `127.0.0.1` for local dev |
+| `DB_NAME` / `DB_USER` / `DB_PASSWORD` | `uomysticmoon` / `uomm` / — | app database credentials |
+| `DB_ROOT_PASSWORD` | — | MariaDB root (Compose only) |
+| `JWT_SECRET` | — | **required** — long random string; signs session, mobile, and SSO-flow tokens |
+| `JWT_EXPIRES_IN` | `1d` | web session token + cookie lifetime |
+| `COOKIE_SECURE` | `auto` | `auto` = Secure only over HTTPS (works on LAN HTTP + Pangolin HTTPS) |
+| `COOKIE_NAME` | `uomm_token` | |
+| `SECRET_ENC_KEY` | — | **required in prod** — key for AES-256-GCM encryption of stored OAuth client secrets. Dev falls back to a key derived from `JWT_SECRET` (with a warning) |
+| `APP_BASE_URL` | — | public base URL, used to build the SSO OAuth `redirect_uri` (`${APP_BASE_URL}/api/v1/auth/sso/:provider/callback`). Set in prod to match what you register with Google/Discord; if unset it is derived from the request (fine for local dev) |
+| `MOBILE_ACCESS_TTL` | `15m` | mobile bearer **access** token lifetime (short-lived) |
+| `MOBILE_REFRESH_TTL_DAYS` | `30` | mobile **refresh** token lifetime (long-lived, rotated on use) |
+| `TRUST_PROXY` | `1` | reverse-proxy trust for correct `req.ip` / `req.secure` (rate limiting, backoff, bot-ban). Pin to the proxy hop's LAN IP in prod. A blanket `true` is rejected (coerced to `1`) to block `X-Forwarded-For` spoofing |
+| `DEBUG_TRUST_PROXY` | `0` | `1` logs raw peer address + `X-Forwarded-For` + resolved `req.ip` per request (to verify/refresh the proxy IP). Noisy — leave off |
+| `TOTP_ISSUER` | `UOMysticmoon` | label shown in authenticator apps for optional per-user 2FA |
+| `TOTP_CHALLENGE_TTL` | `5m` | lifetime of the short-lived post-password "awaiting code" step |
+| `ADMIN_USERNAME` / `ADMIN_PASSWORD` | — | first-admin bootstrap (first boot only) |
+| `SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` | — | optional; blank → contact form uses `mailto:` |
+| `CONTACT_TO` | `UOMysticmoon@gmail.com` | contact recipient |
+| `CLIENT_ORIGIN` | `http://localhost:5173` | enables CORS in dev only |
+| `LOG_LEVEL` / `FILE_LOG_LEVEL` | `info` / `debug` | console / file verbosity |
+| `LOG_TO_FILE` / `LOG_DIR` / `LOG_FILE` | `true` / `<server>/logs` / `app.log` | log file (bind-mounted to `./logs` in Docker) |
+
+---
+
+## Security
+
+**Session & authorization**
+
+- All auth flows go through one **session service** (`server/src/auth/`): controllers call
+  `sessionService.createSession(user, authMethod)` and middleware calls `validateSession()`, so web
+  cookies, mobile bearer tokens, and SSO all produce the *same* authenticated session model.
+  `utils/auth.js` remains a thin backward-compat facade.
+- JWT in an httpOnly, `SameSite=Lax` cookie (`Secure` auto-detected), bcrypt password hashing.
+- Admin routes are **re-validated against the database on every request**, so a demoted or deleted
+  user loses access immediately instead of keeping their old role until the token expires.
+- **Role-based authorization** — admin-only endpoints (users, site mode, settings, auth providers)
+  are gated by a `requireRole` check, so a lower-privilege editor can't reach them.
+
+**Mobile bearer auth**
+
+- Native clients use `/api/v1/auth/mobile/*`: a short-lived **access token** (bearer JWT, validated
+  by the same middleware as the cookie) plus a long-lived, **server-stored, revocable refresh
+  token** that is **rotated on every refresh** (a replayed refresh token is single-use). Refresh
+  tokens are stored **hashed** (never in the clear); logout revokes one or all. Mobile login reuses
+  the same bot-scoring + backoff defenses as web, with single-request TOTP.
+
+**Single sign-on (OAuth2 / OIDC)**
+
+- Pluggable providers — built-in **Google** and **Discord** (endpoints fixed in code; admins supply
+  only client id/secret) plus fully-configurable **custom OIDC/OAuth2** providers, managed from the
+  **Authentication** admin panel. Only `enabled` + fully-configured providers are shown to users.
+- **Link-only** by policy: an SSO login succeeds *only* if the external identity is already linked to
+  an existing account (linked by the user from **Account**). External identities are **never
+  auto-provisioned** — no one gains access without an account you created.
+- The redirect flow is CSRF-protected with a signed, httpOnly, short-lived transaction cookie plus
+  **PKCE**; OAuth client secrets are **encrypted at rest** (AES-256-GCM) and never returned to any
+  client. SSO logins go through the same `sessionService`, so login/activity logging, RBAC, and bot
+  protection are identical to a local login.
+
+**Login hardening**
+
+- **Optional per-user TOTP two-factor** (opt-in, self-service on `/admin/account`). When enabled,
+  the password step issues only a short-lived, non-session `stage:'totp'` challenge; a session
+  cookie is granted only after the second factor verifies.
+- **Login throttling** — `express-slow-down` + a hard rate cap + a separate per-IP exponential
+  backoff, with generic error messages that don't reveal whether the username exists.
+- **Honeypot** field on the login form; submissions that fill it are treated as bots.
+- **Bot-scoring + automatic IP ban** — weighted scoring of CMS-scanner paths and junk 404s (with a
+  periodic sweep of stale entries) bans hostile scanners; failed logins and honeypot hits feed the
+  score. Admins get visibility into this on the **Bot Activity** panel: currently banned IPs and a
+  recent-events feed (in-memory, most-recent-first), plus a logged emergency **unban** for false
+  positives — read + unban only, not a scoring-config surface.
+
+**Uploads & input**
+
+- Uploaded file extensions are derived from the **validated mimetype**, not the client-supplied
+  filename (prevents a disguised-extension upload).
+- `express-validator` on all writes; usernames are validated **and** uniqueness-checked on update.
+
+**Platform**
+
+- `helmet`, admin routes `noindex` + `robots.txt` disallow, `trust proxy` for correct client IPs
+  behind Pangolin (see `TRUST_PROXY`), first admin seeded from env (no hardcoded credentials),
+  `.env` git-ignored. Passwords and request bodies are never logged. SMTP is optional — the contact
+  form falls back to a `mailto:` link when unconfigured.
+
+---
 
 ## Logging
 
@@ -71,18 +360,18 @@ Every log line goes to **both the console and a log file**, timestamped and leve
 2026-06-26T18:55:20.110Z ERROR [error] GET /api/v1/public/wiki -> 500 ... {"stack":"..."}
 ```
 
-What's captured: startup config banner, schema/seed steps, **HTTP access logs** (real client
-IP via `trust proxy`, the authenticated admin, method/URL/status/time/size), login
-success/failure, rate-limit hits, site-mode changes, all errors with stack traces, and
-graceful shutdown. Passwords and request bodies are never logged.
+Captured: startup config banner, schema/seed steps, **HTTP access logs** (real client IP via
+`trust proxy`, the authenticated admin, method/URL/status/time/size), login success/failure,
+rate-limit hits, site-mode changes, all errors with stack traces, and graceful shutdown. Console
+verbosity is `LOG_LEVEL`; the file keeps the fuller `FILE_LOG_LEVEL` record. In Docker the file is
+bind-mounted to `./logs/app.log` and `docker compose logs -f app` shows the console stream.
 
-| Env | Default | Meaning |
-|---|---|---|
-| `LOG_LEVEL` | `info` | console verbosity |
-| `FILE_LOG_LEVEL` | `debug` | file verbosity (keeps a full record) |
-| `LOG_TO_FILE` | `true` | set `false` for console-only |
-| `LOG_DIR` | `<server>/logs` (`/app/logs` in Docker) | log directory |
-| `LOG_FILE` | `app.log` | log file name |
+---
 
-In Docker the log file is bind-mounted to `./logs/app.log` on the host; `docker compose logs -f app`
-also shows the console stream.
+## Deployment behind Pangolin
+
+`docker compose up -d --build` exposes the `app` container on `0.0.0.0:3000` (no `127.0.0.1`
+binding) so Pangolin can reach it. Point a Pangolin resource at `app:3000`. Because `COOKIE_SECURE`
+defaults to `auto`, the admin login works both directly via the LAN IP over HTTP **and** through
+Pangolin over HTTPS — no config change needed. MariaDB stays on the private Compose network
+(no published port by default); data persists in the `dbdata` volume, uploads in `uploads`.

WIKI_UPGRADE.md

@@ -0,0 +1,366 @@
+# UOMysticmoon Website — Wiki Upgrade Spec
+
+> Branch: **`wiki-upgrade`**. This document is the contract for upgrading the CMS
+> wiki from a flat single-table page store into a feature-complete wiki.
+> It follows the project workflow: **design (this doc) → build in phases → verify**.
+>
+> Companion to [`BACKEND_DESIGN.md`](BACKEND_DESIGN.md); reuses its stack, auth,
+> logging, and Docker decisions unchanged.
+
+---
+
+## 1. Goal & scope
+
+Turn the wiki into something that behaves like a typical wiki, while staying inside
+the existing Node/Express + MariaDB + React/Vite architecture and the **staff-only**
+auth model (admin/editor — no new roles, no public contributions).
+
+**In scope**
+
+| Feature | Summary |
+|---|---|
+| Rich-text editing | TipTap (ProseMirror) WYSIWYG in the admin; outputs HTML |
+| Sanitization | Server-side allowlist on save **and** client-side on render (fixes today's stored-XSS gap) |
+| Categories / sections | First-class `wiki_categories` table; replaces hardcoded frontend blurbs |
+| Drafts & publish | `published` + `published_at`, mirroring the `posts` pattern |
+| Tags | Many-to-many tags with filtering |
+| Internal links | `[[slug]]`-style links authored in the editor; red-link detection |
+| Backlinks | "Linked from" list, maintained on save |
+| Inline images | Reuse/generalize the existing multer upload for in-body images |
+| Search | MariaDB `FULLTEXT` over title + body |
+| Revision history | Per-save snapshots with view / diff / restore |
+
+**Out of scope (this branch)**
+
+- Public/player editing or suggestion workflow, moderation/review queues.
+- New roles or per-page ACLs (all staff with a login can edit all pages).
+- Real-time collaborative editing, comments/discussion pages, file attachments
+  other than images, page templates/transclusion, multilingual pages.
+
+**Decisions locked from planning**
+
+- Editor: **TipTap**, storing **HTML** (not Markdown, not JSON).
+- Search: **MariaDB FULLTEXT** (no new infrastructure).
+- Revision history and search are **included** (recommended additions beyond the
+  minimum requested set).
+- Authoring is **admin + editor** (`isLoggedIn`); no anonymous edits.
+
+---
+
+## 2. Current state (baseline being replaced)
+
+| Layer | Today | File |
+|---|---|---|
+| Schema | flat `wiki_pages(slug,title,body,updated_by,timestamps)` | [server/db/schema.sql:31](server/db/schema.sql) |
+| Model | thin CRUD by slug | [server/src/model/wiki/wiki.db.js](server/src/model/wiki/wiki.db.js), [wiki.model.js](server/src/model/wiki/wiki.model.js) |
+| Public API | `GET /public/wiki`, `GET /public/wiki/:slug` | [public.controller.js:53](server/src/router/v1/public/public.controller.js) |
+| Admin API | `GET/POST/PUT/DELETE /admin/wiki[...]` | [admin.controller.js:163](server/src/router/v1/admin/admin.controller.js), [admin.routes.js:68](server/src/router/v1/admin/admin.routes.js) |
+| Public UI | card grid (hardcoded blurbs + Roman numerals), article w/ auto-TOC | [Wiki.jsx](client/src/routes/wiki/Wiki.jsx), [WikiArticle.jsx](client/src/routes/wiki/WikiArticle.jsx) |
+| Admin UI | raw-HTML `<textarea>` modal | [WikiAdmin.jsx](client/src/routes/admin/views/WikiAdmin.jsx), [WikiEditor.jsx](client/src/routes/admin/views/WikiEditor.jsx) |
+| API client | `api.wiki`, `api.admin.*Wiki` | [client/src/api/client.js:52](client/src/api/client.js) |
+
+**Known issues this upgrade resolves**
+
+- **Stored XSS**: body is raw HTML rendered with `dangerouslySetInnerHTML` and never
+  sanitized ([WikiArticle.jsx:91](client/src/routes/wiki/WikiArticle.jsx)).
+- Category blurbs and ordering are **faked in the component** ([Wiki.jsx:11](client/src/routes/wiki/Wiki.jsx)), not data.
+- No drafts (every save is instantly public), no history, no search, no tags, no links.
+
+---
+
+## 3. Data model
+
+`utf8mb4`, InnoDB throughout. All changes are **additive and idempotent** so
+`ensureSchema()` upgrades existing databases on boot with no data loss. New columns
+are nullable or have safe defaults; **existing pages default to `published = 1`** so
+nothing disappears on deploy.
+
+### 3.1 `wiki_categories` (new)
+
+| col | type | notes |
+|---|---|---|
+| id | INT PK AI | |
+| slug | VARCHAR(120) UNIQUE NOT NULL | e.g. `guides` |
+| title | VARCHAR(200) NOT NULL | |
+| description | VARCHAR(400) NULL | card teaser on the wiki index |
+| sort_order | INT NOT NULL DEFAULT 0 | manual ordering |
+| created_at / updated_at | DATETIME | standard stamps |
+
+### 3.2 `wiki_pages` (altered)
+
+Add to the existing table:
+
+| col | type | notes |
+|---|---|---|
+| category_id | INT NULL FK→wiki_categories(id) ON DELETE SET NULL | |
+| excerpt | VARCHAR(400) NULL | card/search teaser (replaces hardcoded blurbs) |
+| published | TINYINT(1) NOT NULL DEFAULT 1 | draft/publish toggle |
+| published_at | DATETIME NULL | set on first publish |
+| sort_order | INT NOT NULL DEFAULT 0 | ordering within a category |
+| FULLTEXT idx_wiki_search (title, body) | | search |
+
+### 3.3 `wiki_tags` + `wiki_page_tags` (new)
+
+```
+wiki_tags( id PK, slug VARCHAR(120) UNIQUE, label VARCHAR(120) )
+wiki_page_tags( page_id FK→wiki_pages ON DELETE CASCADE,
+                tag_id  FK→wiki_tags  ON DELETE CASCADE,
+                PRIMARY KEY(page_id, tag_id) )
+```
+
+### 3.4 `wiki_links` (new) — backlinks index
+
+Rebuilt for a page on every save by parsing its body for internal links.
+
+| col | type | notes |
+|---|---|---|
+| source_page_id | INT FK→wiki_pages ON DELETE CASCADE | |
+| target_slug | VARCHAR(120) NOT NULL | may point at a not-yet-created page (red link) |
+| INDEX idx_wiki_links_target (target_slug) | | backlink lookups |
+
+Backlinks for page X = `SELECT source pages WHERE target_slug = X.slug AND source is published`.
+
+### 3.5 `wiki_revisions` (new) — history
+
+| col | type | notes |
+|---|---|---|
+| id | INT PK AI | |
+| page_id | INT FK→wiki_pages ON DELETE CASCADE | |
+| title / body / excerpt | snapshot of content at save time | |
+| category_id | INT NULL | snapshot |
+| editor_id | INT NULL FK→users(id) | who saved |
+| change_note | VARCHAR(280) NULL | optional summary |
+| created_at | DATETIME DEFAULT CURRENT_TIMESTAMP | |
+
+A revision is written **inside the same transaction** as each page create/update.
+
+### 3.6 Seed changes
+
+Rework [seed.js](server/db/seed.js): the current 8 hardcoded pages become **categories**
+(title + the blurb currently living in the frontend), each seeded idempotently via a new
+`seedDefaultCategory`. Existing seeded pages are migrated/attached where applicable.
+`seedDefault` for pages stays `INSERT IGNORE` so reseeding is safe.
+
+---
+
+## 4. Backend changes
+
+Keep the `model` (entity) / `db` (SQL) split and the route grouping by access level.
+
+### 4.1 Models (`server/src/model/wiki/`)
+
+- `wiki.db.js` — add SQL for: category CRUD; page list with `category`, `published`,
+  `q` (FULLTEXT) filters and ordering; tag upsert + attach/detach; `wiki_links` rebuild;
+  revision insert/list/get; backlink query.
+- `wiki.model.js` — orchestration. On **create/update** (single transaction):
+  1. sanitize `body` with the allowlist (§6),
+  2. upsert the page,
+  3. insert a `wiki_revisions` snapshot,
+  4. parse body for internal links → rebuild `wiki_links` for the page,
+  5. sync tags.
+- A small `wiki.links.js` helper: parse internal links out of the saved HTML
+  (anchors written by the editor as `href="/wiki/<slug>"` / a `data-wiki-slug` attr),
+  return the set of target slugs.
+
+### 4.2 Public API (`/api/v1/public`)
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/wiki/categories` | ordered categories with page counts |
+| GET | `/wiki?category=&tag=&q=` | **published only**; list/filter/search summaries |
+| GET | `/wiki/:slug` | page + category + tags + backlinks (published only) |
+
+Still passes through the `siteMode` maintenance gate like other public content.
+
+### 4.3 Admin API (`/api/v1/admin`, behind `isLoggedIn` + `noindex`)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/wiki` | all pages incl. drafts (filters: category, tag, q, status) |
+| GET | `/wiki/:slug` | one page incl. draft, tags, category |
+| POST | `/wiki` | create (slug, title, body, excerpt, category_id, tags, published) |
+| PUT | `/wiki/:slug` | update (allows slug rename — see §7) |
+| PATCH | `/wiki/:slug/publish` | `{published}` toggle, stamps `published_at` |
+| DELETE | `/wiki/:slug` | delete (cascades revisions/links/tags) |
+| GET | `/wiki/:slug/revisions` | list snapshots |
+| GET | `/wiki/:slug/revisions/:id` | one snapshot (for diff/preview) |
+| POST | `/wiki/:slug/revisions/:id/restore` | restore (writes a new revision) |
+| GET/POST/PUT/DELETE | `/wiki/categories[...]` | category CRUD + reorder |
+| GET/POST | `/wiki/tags` | list/create tags |
+| POST | `/uploads` | generalized image upload (see §4.4) → `{url}` |
+
+Validation via `express-validator` (slug regex `^[a-z0-9-]+$`, title required, etc.),
+centralized error handler unchanged. **Every write logs to `activity_log`**
+(`wiki.create`, `wiki.update`, `wiki.publish`, `wiki.delete`, `wiki.revision.restore`,
+`wiki.category.*`) following the existing convention.
+
+### 4.4 Image uploads
+
+Generalize the existing screenshot upload (multer config in [admin.routes.js:17](server/src/router/v1/admin/admin.routes.js))
+into a shared `POST /admin/uploads` returning `{ url: "/uploads/<file>" }`, reused by both
+the post editor and the wiki editor. Same size/mime limits. No new storage —
+served from the existing `uploads/` volume.
+
+---
+
+## 5. Frontend changes
+
+### 5.1 Admin
+
+- **`WikiEditor.jsx`** — replace the raw-HTML `<textarea>` with a **TipTap** editor:
+  bold/italic/headings (H2 for TOC)/lists/quote/code, link tool, **image insert**
+  (uploads via `/admin/uploads`), and an **internal-link picker** (`[[`-triggered
+  autocomplete over existing slugs; flags red links). Adds: category dropdown, tag
+  input (create-on-type), excerpt field, **Save draft / Publish** actions, and a
+  **History** tab (revision list → preview → diff → restore).
+- **`WikiAdmin.jsx`** — list gains status (draft/published), category column, and
+  filters; plus a **Categories** manager (CRUD + drag-to-reorder).
+
+### 5.2 Public
+
+- **`Wiki.jsx`** — fully data-driven: categories + real excerpts from the API
+  (delete the hardcoded `BLURBS`/`ROMAN` constants), a **search box**, optional
+  tag filter.
+- **`WikiArticle.jsx`** — keep auto-TOC; add category breadcrumb, tag chips, a
+  **"Linked from"** backlinks section, "last updated by", and **render via DOMPurify**
+  (`dangerouslySetInnerHTML` only after sanitize).
+
+### 5.3 API client & routes
+
+- Extend [client/src/api/client.js](client/src/api/client.js) with the new public/admin
+  wiki calls (categories, search params, revisions, tags, uploads).
+- Add a public search/category route if needed; admin categories view registered in
+  [App.jsx](client/src/App.jsx) under `/admin/wiki` (sub-tab, no new top-level route required).
+
+### 5.4 Dependencies (new)
+
+- **client**: `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-link`,
+  `@tiptap/extension-image` (+ a small diff lib for history, e.g. `diff`); `dompurify`.
+- **server**: `sanitize-html`.
+
+(The client currently ships only React + react-router, so this is the first feature
+dependency addition — keep the bundle lean, import only the extensions used.)
+
+---
+
+## 6. Security
+
+- **Two-layer sanitization.** Server sanitizes on save with a strict `sanitize-html`
+  allowlist (headings, p, lists, blockquote, code/pre, a[href], img[src,alt],
+  strong/em, hr, table basics); strips scripts, event handlers, `javascript:` URLs,
+  styles. Client re-sanitizes with DOMPurify before render. The stored value is already
+  clean, so even direct DB edits or future API clients can't inject script.
+- **Upload safety** unchanged from posts: mime allowlist (png/jpe/gif/webp/avif),
+  8 MB cap, random filenames, served as static files (no execution).
+- **Authorization**: all mutating wiki/category/tag/upload routes stay behind
+  `isLoggedIn` (admin or editor). Public routes are read-only and published-only.
+- **No secrets/logging changes**; reuse existing rate-limit, helmet/CSP, noindex.
+  CSP `img-src` already covers `/uploads`.
+
+---
+
+## 7. Migration & backward compatibility
+
+- Schema migration is additive; run by `ensureSchema()` on boot and shipped in
+  `schema.sql` for fresh containers. Use `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`
+  / `ADD INDEX` guarded for idempotency (MariaDB 11 supports `IF NOT EXISTS`).
+- Existing pages: `published` backfills to `1`, `published_at` to `updated_at`,
+  `category_id` left NULL (surface as "Uncategorized" until assigned).
+- **Slug rename** (new capability): on `PUT` slug change, update the page slug and
+  best-effort rewrite known internal links pointing at the old slug; old slug is not
+  auto-redirected (acceptable for a staff-curated wiki) — note in release notes.
+- Public API response shape is **extended, not broken**: existing fields
+  (`slug`, `title`, `body`, `updated_at`) remain; new fields are additive, so the
+  current frontend keeps working between phases.
+
+---
+
+## 8. Implementation process (phased)
+
+Each phase is a self-contained, shippable unit: build → run locally → verify in the
+browser preview → commit on `wiki-upgrade`. Open a PR into `main` at the end (or per
+phase if preferred). Do not merge a phase that hasn't been verified.
+
+### Phase 0 — Branch & scaffolding ✅ (this doc)
+- `wiki-upgrade` branch created; this spec committed.
+
+### Phase 1 — Foundation & safety (highest value) ✅
+- Schema: add `wiki_categories`, alter `wiki_pages` (category_id, excerpt, published,
+  published_at, sort_order, FULLTEXT), update `seed.js`.
+- Server: server-side sanitization on save; drafts/publish endpoints; categories CRUD;
+  public list filtered to published + categories endpoint.
+- Client: data-driven `Wiki.jsx` (remove hardcoded blurbs); DOMPurify render in
+  `WikiArticle.jsx`; draft/publish + category in the (still-textarea) admin editor.
+- **Exit check**: existing pages still render; XSS payload in body is neutralized;
+  draft pages hidden from the public list/article.
+- **Verified** (2026-06-27): schema migration ran clean on MariaDB 11; XSS payload
+  (`<script>`, `onerror=`, `javascript:`) stripped server-side; drafts return 404 on
+  the public API and are absent from the public list while visible in admin; public
+  index is data-driven (categories + sections); article shows category breadcrumb;
+  client builds and server boots with no errors.
+
+### Phase 2 — Authoring UX ✅
+- TipTap editor replaces the textarea; generalized `/admin/uploads`; inline images.
+- **Exit check**: create/edit a page with headings, a list, a link, and an inline
+  image; verify it renders sanitized on the public page.
+- **Verified** (2026-06-27): `/admin/uploads` returns `{url}` and the file serves as
+  an image; a page authored with H2/H3, lists, a link, and an uploaded inline image
+  round-trips through the WYSIWYG and renders sanitized publicly (link `rel` forced,
+  `<script>` stripped); a toolbar edit (insert divider) saved and persisted. TipTap
+  is code-split into its own chunk (lazy-loaded), keeping it off the public bundle.
+
+### Phase 3 — Connectivity ✅
+- Internal `[[slug]]` links + red-link detection; `wiki_links` rebuild on save;
+  backlinks on the article; tags + tag/category filtering.
+- **Exit check**: link page A→B, confirm B shows A under "Linked from"; tag filter works.
+- **Verified** (2026-06-27): internal links authored via an in-editor page picker
+  (links to `/wiki/<slug>`); A→B made B list A under "Linked from"; a link to a
+  non-existent page renders as a red link; removing the link on save cleared the
+  backlink (link index rebuilt). Tags upsert on save, filter via `?tag=` (chips +
+  flat index view), list with published counts, and orphan tags are auto-pruned.
+- Implementation note: links are plain anchors to `/wiki/<slug>` (the WYSIWYG fits
+  this better than `[[ ]]` syntax); the sanitizer also allows `data-wiki-slug`.
+
+### Phase 4 — Discovery & trust ✅
+- FULLTEXT search (public search box + admin filter); revision history list /
+  diff / restore.
+- **Exit check**: search returns expected pages; edit a page twice, diff the
+  revisions, restore an older one, confirm a new revision is recorded.
+- **Verified** (2026-06-27): `?q=` natural-language search matches on both body
+  (`recipes`→crafting) and title (`monsters`); the public search box and admin
+  filter both work. A page edited twice produced 3 revisions; the History modal
+  shows a word-level diff (added vs removed) of an old revision against current;
+  restoring reverted the page and appended a "Restored from revision #N" entry.
+
+### Verification (every phase)
+Use the preview workflow, not manual hand-off: start the dev server, exercise the
+public wiki and the admin editor, check console/network for errors, and capture a
+screenshot of the changed surface. Confirm `npm run` lint/build passes for the client
+and the server boots cleanly with `ensureSchema()` applying the migration.
+
+---
+
+## 9. File-change map (reference)
+
+| Area | Files |
+|---|---|
+| Schema/seed | `server/db/schema.sql`, `server/db/seed.js`, `server/src/utils/db.js` (ensureSchema) |
+| Models | `server/src/model/wiki/wiki.db.js`, `wiki.model.js`, **new** `wiki.links.js` |
+| API | `server/src/router/v1/public/public.{routes,controller}.js`, `server/src/router/v1/admin/admin.{routes,controller}.js` |
+| Sanitize | **new** `server/src/utils/sanitizeHtml.js` |
+| Client API | `client/src/api/client.js` |
+| Public UI | `client/src/routes/wiki/Wiki.jsx`, `WikiArticle.jsx` |
+| Admin UI | `client/src/routes/admin/views/WikiAdmin.jsx`, `WikiEditor.jsx`, **new** category manager + revisions view |
+| Deps | `client/package.json`, `server/package.json` |
+
+---
+
+## 10. Open questions / assumptions
+
+1. **Slug redirects**: assumed not needed on rename (staff wiki). Revisit if pages get
+   external inbound links.
+2. **Search ranking**: FULLTEXT natural-language mode assumed; can switch to BOOLEAN
+   mode if operators are wanted later.
+3. **Diff granularity**: line/word diff of the HTML source is assumed sufficient for
+   revision compare; a rendered visual diff is a later nice-to-have.
+4. **Editor scope**: tables and embeds beyond images are deferred unless requested.

bot/.env.example

@@ -0,0 +1,45 @@
+# ─── UOMysticmoon Discord bot — local dev environment ───
+# Copy to bot/.env for running `npm run dev` outside Docker.
+# (In Docker, the root .env / docker-compose provides these instead.)
+#
+# NOTE: there is no Discord bot token here on purpose. The token is entered
+# in the admin panel (Discord Bot page), stored encrypted in the main site's
+# DB, and pushed to this process in-memory over the internal API. It is
+# never read from an env var and never written to this process's disk.
+
+PORT=4100
+
+# Logging — written to BOTH the console and a log file (default <bot>/logs/bot.log).
+LOG_LEVEL=debug         # console verbosity: error | warn | info | debug
+FILE_LOG_LEVEL=debug    # file verbosity
+LOG_TO_FILE=true        # set false for console-only
+# LOG_DIR=              # defaults to bot/logs
+# LOG_FILE=bot.log
+
+# Shared secret for the internal API between this bot and the main site
+# (server/). MUST be byte-for-byte identical to BOT_INTERNAL_KEY in
+# server/.env.example / the root .env.example — it is the only auth on both
+# sides' /internal/* routes, so a mismatch silently breaks every server<->bot
+# call with 401s. Generate one long random string and copy it to both places.
+BOT_INTERNAL_KEY=dev-only-change-me-bot-key
+
+# Where this bot calls back to the main site to fetch its config on boot
+# (GET .../internal/bot-config), so a restart self-reconnects without needing
+# the admin panel to push config again. This targets the site's UNPUBLISHED
+# internal port (INTERNAL_PORT, default 3001) — NOT the public 3000. See #33.
+SITE_INTERNAL_URL=http://localhost:3001/internal/bot-config
+
+# Read-only PUBLIC API base (Phase 7) — no shared secret, same data any
+# visitor's browser can fetch. Used by /wiki (search) and /announce
+# (re-post an existing news item).
+SITE_PUBLIC_URL=http://localhost:3000/api/v1/public
+
+# Database (Phase 2+) — same physical DB as the main site, but the bot only
+# ever reads/writes its OWN tables (guild_config, mod_actions, warnings, and
+# more in later phases). It never touches site tables (users, bot_config,
+# etc.) directly. Point this at the same DB the server/ uses.
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=uomysticmoon
+DB_USER=uomm
+DB_PASSWORD=change-me-db-password

bot/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.env
+logs/

bot/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-alpine
+
+WORKDIR /app/bot
+
+COPY bot/package*.json ./
+RUN npm install --omit=dev
+
+COPY bot/ .
+
+RUN mkdir -p /app/bot/logs && chown -R node:node /app/bot/logs
+
+USER node
+
+EXPOSE 4100
+
+CMD ["node", "src/server.js"]

bot/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "uomysticmoon-bot",
+  "version": "1.0.0",
+  "description": "Discord bot for the UOMysticmoon community server",
+  "private": true,
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js"
+  },
+  "keywords": ["discord", "discord.js"],
+  "author": "whitlocktech",
+  "license": "ISC",
+  "dependencies": {
+    "discord.js": "^14.16.3",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "mariadb": "^3.3.1",
+    "node-cron": "^3.0.3"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.4"
+  }
+}

bot/src/app.js

@@ -0,0 +1,12 @@
+const express = require('express')
+
+const internalRouter = require('./internal/internal.routes')
+
+const app = express()
+
+app.use(express.json())
+
+app.get('/health', (req, res) => res.json({ status: 'ok' }))
+app.use('/internal', internalRouter)
+
+module.exports = app

bot/src/bootstrap.js

@@ -0,0 +1,38 @@
+// Runs once at process start, before the internal Express server is
+// considered ready. Fetches current config from the main site (token,
+// guildId, enabled) and reconnects immediately if enabled — so a bot
+// container restart (crash, `docker compose restart`, host reboot) self-heals
+// without any admin-panel interaction. Node 20's built-in fetch is used; no
+// extra HTTP client dependency needed for a single startup call.
+const discordManager = require('./discord/discordManager')
+const createLogger = require('./utils/logger')
+
+const log = createLogger('bootstrap')
+
+async function bootstrap() {
+  const siteUrl = process.env.SITE_INTERNAL_URL
+  const key = process.env.BOT_INTERNAL_KEY
+  if (!siteUrl || !key) {
+    log.warn('SITE_INTERNAL_URL or BOT_INTERNAL_KEY not set — skipping boot-time config fetch, staying disconnected until the admin panel pushes config')
+    return
+  }
+
+  try {
+    const res = await fetch(siteUrl, { headers: { 'X-Internal-Key': key } })
+    if (!res.ok) {
+      log.error('boot-time config fetch failed', { status: res.status })
+      return
+    }
+    const config = await res.json()
+    if (config.enabled) {
+      log.info('boot-time config says enabled — reconnecting', { guildId: config.guildId })
+      await discordManager.start({ token: config.token, guildId: config.guildId })
+    } else {
+      log.info('boot-time config says disabled — staying disconnected')
+    }
+  } catch (err) {
+    log.error('boot-time config fetch errored', { message: err.message })
+  }
+}
+
+module.exports = bootstrap

bot/src/db.js

@@ -0,0 +1,41 @@
+// DB pool for the bot's OWN tables (guild_config, mod_actions, warnings) —
+// mirrors server/src/utils/db.js. The bot never reads/writes any table it
+// doesn't own; site-owned tables (users, bot_config, etc.) are reached only
+// through the internal API, never directly. Schema for these tables lives in
+// server/db/schema.sql (same physical database, ensured by the main server on
+// boot) — there's no separate migration tool to justify a second database for
+// a single-guild v1 bot.
+const mariadb = require('mariadb')
+
+const pool = mariadb.createPool({
+  host: process.env.DB_HOST || '127.0.0.1',
+  port: Number(process.env.DB_PORT) || 3306,
+  user: process.env.DB_USER || 'root',
+  password: process.env.DB_PASSWORD || '',
+  database: process.env.DB_NAME || 'uomysticmoon',
+  connectionLimit: 5,
+  insertIdAsNumber: true,
+  bigIntAsNumber: true,
+  decimalAsNumber: true,
+  // The driver defaults to 'local' — silently serializing bound JS Date
+  // params using the HOST MACHINE's local offset instead of the DB session's
+  // timezone (discovered via temp_roles.expires_at coming back hours off in
+  // dev, CDT vs the container's UTC). 'auto' negotiates the actual session
+  // timezone so Date round-trips correctly regardless of host TZ.
+  timezone: 'auto',
+})
+
+async function query(sql, params) {
+  const conn = await pool.getConnection()
+  try {
+    return await conn.query(sql, params)
+  } finally {
+    conn.release()
+  }
+}
+
+async function close() {
+  await pool.end()
+}
+
+module.exports = { query, close }

bot/src/discord/commands/announce.command.js

@@ -0,0 +1,49 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const siteApiClient = require('../../site/siteApiClient')
+const newsAnnounce = require('../newsAnnounce')
+
+function siteOrigin() {
+  const base = process.env.SITE_PUBLIC_URL || 'http://localhost:3000/api/v1/public'
+  return new URL(base).origin
+}
+
+module.exports = {
+  data: {
+    name: 'announce',
+    description: 'Re-post or boost an existing news item.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      { name: 'post', description: 'News post id or slug', type: ApplicationCommandOptionType.String, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const idOrSlug = interaction.options.getString('post', true)
+    await interaction.deferReply({ ephemeral: true })
+
+    const result = await siteApiClient.getNewsPost(idOrSlug)
+    if (result.maintenance) {
+      await interaction.editReply({ content: `Can't reach the site right now: ${result.message || 'maintenance mode'}` })
+      return
+    }
+    if (!result.ok) {
+      await interaction.editReply({ content: `Couldn't find that news post ("${idOrSlug}").` })
+      return
+    }
+
+    const post = result.data
+    const origin = siteOrigin()
+    try {
+      await newsAnnounce.postAnnounce(interaction.client, interaction.guildId, {
+        title: post.title,
+        excerpt: post.excerpt,
+        url: `${origin}/site/news`,
+        // image_url is stored relative — Discord embeds require an absolute URL.
+        imageUrl: post.image_url ? new URL(post.image_url, origin).toString() : null,
+      })
+      await interaction.editReply({ content: `Posted "${post.title}" to the news channel.` })
+    } catch (err) {
+      await interaction.editReply({ content: `Couldn't post: ${err.message}` })
+    }
+  },
+}

bot/src/discord/commands/autorole.command.js

@@ -0,0 +1,30 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const guildConfig = require('../../model/guildConfig')
+
+module.exports = {
+  data: {
+    name: 'autorole',
+    description: 'View or set the role automatically assigned to new members on join.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'role',
+        description: 'Role to auto-assign on join. Omit to view the current setting.',
+        type: ApplicationCommandOptionType.Role,
+        required: false,
+      },
+    ],
+  },
+  async execute(interaction) {
+    const role = interaction.options.getRole('role')
+    if (!role) {
+      const currentId = await guildConfig.getAutoRoleId(interaction.guildId)
+      const content = currentId ? `Auto-role is set to <@&${currentId}>.` : 'No auto-role is set yet.'
+      await interaction.reply({ content, ephemeral: true })
+      return
+    }
+    await guildConfig.setAutoRoleId(interaction.guildId, role.id)
+    await interaction.reply({ content: `Auto-role set to ${role}. New members will get this automatically.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/ban.command.js

@@ -0,0 +1,34 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const modLog = require('../modLog')
+
+module.exports = {
+  data: {
+    name: 'ban',
+    description: 'Ban a member from the server.',
+    default_member_permissions: PermissionFlagsBits.BanMembers.toString(),
+    options: [
+      { name: 'user', description: 'Member to ban', type: ApplicationCommandOptionType.User, required: true },
+      { name: 'reason', description: 'Reason for the ban', type: ApplicationCommandOptionType.String, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const user = interaction.options.getUser('user', true)
+    const reason = interaction.options.getString('reason', true)
+
+    if (user.id === interaction.user.id) {
+      await interaction.reply({ content: "You can't ban yourself.", ephemeral: true })
+      return
+    }
+
+    const member = interaction.guild.members.cache.get(user.id)
+    if (member && !member.bannable) {
+      await interaction.reply({ content: "I don't have permission to ban that member (role hierarchy).", ephemeral: true })
+      return
+    }
+
+    await interaction.guild.members.ban(user, { reason })
+    await modLog.record({ client: interaction.client, guildId: interaction.guildId, actionType: 'ban', target: user, staffUser: interaction.user, reason })
+    await interaction.reply({ content: `Banned ${user.tag}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/filter.command.js

@@ -0,0 +1,73 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const filterWords = require('../../model/filterWords')
+const filterCache = require('../../filter/filterCache')
+
+module.exports = {
+  data: {
+    name: 'filter',
+    description: 'Manage the banned-word filter.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'add',
+        description: 'Add a word to the filter.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'word', description: 'Word or phrase to ban', type: ApplicationCommandOptionType.String, required: true },
+          {
+            name: 'severity',
+            description: 'Auto-action when triggered (default: delete)',
+            type: ApplicationCommandOptionType.String,
+            required: false,
+            choices: [
+              { name: 'Delete only', value: 'delete' },
+              { name: 'Delete + warn', value: 'warn' },
+              { name: 'Delete + mute (10m)', value: 'mute' },
+            ],
+          },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a word from the filter.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'word', description: 'Word or phrase to remove', type: ApplicationCommandOptionType.String, required: true },
+        ],
+      },
+      {
+        name: 'list',
+        description: 'List all filtered words.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+
+    if (sub === 'add') {
+      const word = interaction.options.getString('word', true)
+      const severity = interaction.options.getString('severity') || 'delete'
+      await filterWords.add({ guildId: interaction.guildId, word, severity, addedBy: interaction.user.id, addedByTag: interaction.user.tag })
+      await filterCache.refresh(interaction.guildId)
+      await interaction.reply({ content: `Added "${word}" to the filter (${severity}).`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'remove') {
+      const word = interaction.options.getString('word', true)
+      const removed = await filterWords.remove(interaction.guildId, word)
+      await filterCache.refresh(interaction.guildId)
+      await interaction.reply({ content: removed ? `Removed "${word}" from the filter.` : `"${word}" wasn't in the filter.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'list') {
+      const words = await filterWords.list(interaction.guildId)
+      const content = words.length === 0 ? 'The filter list is empty.' : words.map((w) => `${w.word} (${w.severity})`).join('\n')
+      await interaction.reply({ content, ephemeral: true })
+    }
+  },
+}

bot/src/discord/commands/filterallow.command.js

@@ -0,0 +1,61 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const filterAllowlist = require('../../model/filterAllowlist')
+const filterCache = require('../../filter/filterCache')
+
+module.exports = {
+  data: {
+    name: 'filterallow',
+    description: 'Manage roles/channels that bypass the filter entirely.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'role',
+        description: 'Toggle a role in/out of the filter bypass list.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [{ name: 'role', description: 'Role to toggle', type: ApplicationCommandOptionType.Role, required: true }],
+      },
+      {
+        name: 'channel',
+        description: 'Toggle a channel in/out of the filter bypass list.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [{ name: 'channel', description: 'Channel to toggle', type: ApplicationCommandOptionType.Channel, required: true }],
+      },
+      {
+        name: 'list',
+        description: 'Show current filter bypass roles/channels.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+
+    if (sub === 'role') {
+      const role = interaction.options.getRole('role', true)
+      const nowAllowed = await filterAllowlist.toggleRole(interaction.guildId, role.id)
+      await filterCache.refresh(interaction.guildId)
+      await interaction.reply({ content: `${role} is ${nowAllowed ? 'now' : 'no longer'} bypassing the filter.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'channel') {
+      const channel = interaction.options.getChannel('channel', true)
+      const nowAllowed = await filterAllowlist.toggleChannel(interaction.guildId, channel.id)
+      await filterCache.refresh(interaction.guildId)
+      await interaction.reply({ content: `${channel} is ${nowAllowed ? 'now' : 'no longer'} bypassing the filter.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'list') {
+      const [roles, channels] = await Promise.all([
+        filterAllowlist.getRoles(interaction.guildId),
+        filterAllowlist.getChannels(interaction.guildId),
+      ])
+      const roleText = roles.length ? roles.map((id) => `<@&${id}>`).join(', ') : 'none'
+      const channelText = channels.length ? channels.map((id) => `<#${id}>`).join(', ') : 'none'
+      await interaction.reply({ content: `Bypass roles: ${roleText}\nBypass channels: ${channelText}`, ephemeral: true })
+    }
+  },
+}

bot/src/discord/commands/index.js

@@ -0,0 +1,31 @@
+// Command registry. Each module exports { data, execute } — `data` is the
+// slash-command definition pushed to Discord (registerCommands), `execute` is
+// the interactionCreate handler (dispatch). Adding a new command is just
+// adding a file here — discordManager.js never needs to change.
+const commands = [
+  require('./ping.command'),
+  require('./modlog.command'),
+  require('./ban.command'),
+  require('./kick.command'),
+  require('./mute.command'),
+  require('./warn.command'),
+  require('./warnings.command'),
+  require('./filter.command'),
+  require('./filterallow.command'),
+  require('./schedule.command'),
+  require('./rolemenu.command'),
+  require('./autorole.command'),
+  require('./role.command'),
+  require('./roles.command'),
+  require('./invite.command'),
+  require('./news.command'),
+  require('./announce.command'),
+  require('./wiki.command'),
+]
+
+const byName = new Map(commands.map((c) => [c.data.name, c]))
+
+module.exports = {
+  all: commands,
+  get: (name) => byName.get(name),
+}

bot/src/discord/commands/invite.command.js

@@ -0,0 +1,85 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType, ChannelType } = require('discord.js')
+
+const guildConfig = require('../../model/guildConfig')
+const inviteLog = require('../../model/inviteLog')
+const inviteRotator = require('../../invites/inviteRotator')
+
+module.exports = {
+  data: {
+    name: 'invite',
+    description: 'Manage the auto-rotating primary server invite.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'channel',
+        description: 'View or set the channel new invites are created in.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          {
+            name: 'channel',
+            description: 'Channel to create invites in. Omit to view the current setting.',
+            type: ApplicationCommandOptionType.Channel,
+            channel_types: [ChannelType.GuildText],
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'rotate',
+        description: 'Revoke the current invite and generate a new one now.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [],
+      },
+      {
+        name: 'log',
+        description: 'Show recent invite rotation history.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+
+    if (sub === 'channel') {
+      const channel = interaction.options.getChannel('channel')
+      if (!channel) {
+        const currentId = await guildConfig.getInviteChannelId(interaction.guildId)
+        const content = currentId ? `Invites are created in <#${currentId}>.` : 'No invite channel is set yet.'
+        await interaction.reply({ content, ephemeral: true })
+        return
+      }
+      await guildConfig.setInviteChannelId(interaction.guildId, channel.id)
+      await interaction.reply({ content: `Invite channel set to ${channel}.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'rotate') {
+      await interaction.deferReply({ ephemeral: true })
+      try {
+        const invite = await inviteRotator.rotate(interaction.client, interaction.guildId, {
+          triggeredBy: interaction.user.id,
+          triggeredByTag: interaction.user.tag,
+        })
+        await interaction.editReply({ content: `New invite: https://discord.gg/${invite.code}` })
+      } catch (err) {
+        await interaction.editReply({ content: `Couldn't rotate the invite: ${err.message}` })
+      }
+      return
+    }
+
+    if (sub === 'log') {
+      const rows = await inviteLog.list(interaction.guildId, 10)
+      if (rows.length === 0) {
+        await interaction.reply({ content: 'No invite rotations logged yet.', ephemeral: true })
+        return
+      }
+      const lines = rows.map((r) => {
+        const who = r.triggered_by_tag || 'automatic (scheduled)'
+        const status = r.revoked_at ? `revoked ${new Date(r.revoked_at).toLocaleString()}` : 'active'
+        return `\`${r.invite_code}\` — by ${who} on ${new Date(r.created_at).toLocaleString()} (${status})`
+      })
+      await interaction.reply({ content: lines.join('\n'), ephemeral: true })
+    }
+  },
+}

bot/src/discord/commands/kick.command.js

@@ -0,0 +1,38 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const modLog = require('../modLog')
+
+module.exports = {
+  data: {
+    name: 'kick',
+    description: 'Kick a member from the server.',
+    default_member_permissions: PermissionFlagsBits.KickMembers.toString(),
+    options: [
+      { name: 'user', description: 'Member to kick', type: ApplicationCommandOptionType.User, required: true },
+      { name: 'reason', description: 'Reason for the kick', type: ApplicationCommandOptionType.String, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const user = interaction.options.getUser('user', true)
+    const reason = interaction.options.getString('reason', true)
+
+    if (user.id === interaction.user.id) {
+      await interaction.reply({ content: "You can't kick yourself.", ephemeral: true })
+      return
+    }
+
+    const member = interaction.guild.members.cache.get(user.id)
+    if (!member) {
+      await interaction.reply({ content: 'That user is not a member of this server.', ephemeral: true })
+      return
+    }
+    if (!member.kickable) {
+      await interaction.reply({ content: "I don't have permission to kick that member (role hierarchy).", ephemeral: true })
+      return
+    }
+
+    await member.kick(reason)
+    await modLog.record({ client: interaction.client, guildId: interaction.guildId, actionType: 'kick', target: user, staffUser: interaction.user, reason })
+    await interaction.reply({ content: `Kicked ${user.tag}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/modlog.command.js

@@ -0,0 +1,33 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType, ChannelType } = require('discord.js')
+
+const guildConfig = require('../../model/guildConfig')
+
+module.exports = {
+  data: {
+    name: 'modlog',
+    description: 'View or set the mod-log channel (ban/kick/mute/warn actions post here).',
+    // Configuration, not a moderation action — gated to Manage Server rather
+    // than the ModerateMembers bit the action commands use.
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'channel',
+        description: 'Channel to post mod-log entries to. Omit to view the current setting.',
+        type: ApplicationCommandOptionType.Channel,
+        channel_types: [ChannelType.GuildText],
+        required: false,
+      },
+    ],
+  },
+  async execute(interaction) {
+    const channel = interaction.options.getChannel('channel')
+    if (!channel) {
+      const currentId = await guildConfig.getModLogChannelId(interaction.guildId)
+      const content = currentId ? `Mod-log channel is set to <#${currentId}>.` : 'No mod-log channel is set yet.'
+      await interaction.reply({ content, ephemeral: true })
+      return
+    }
+    await guildConfig.setModLogChannelId(interaction.guildId, channel.id)
+    await interaction.reply({ content: `Mod-log channel set to ${channel}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/mute.command.js

@@ -0,0 +1,49 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const modLog = require('../modLog')
+const { parseDuration, MAX_TIMEOUT_MS } = require('../../utils/duration')
+
+module.exports = {
+  data: {
+    name: 'mute',
+    description: 'Timeout a member for a duration (e.g. 10m, 2h, 1d).',
+    default_member_permissions: PermissionFlagsBits.ModerateMembers.toString(),
+    options: [
+      { name: 'user', description: 'Member to mute', type: ApplicationCommandOptionType.User, required: true },
+      { name: 'duration', description: 'e.g. 30s, 10m, 2h, 1d (max 28d)', type: ApplicationCommandOptionType.String, required: true },
+      { name: 'reason', description: 'Reason for the mute', type: ApplicationCommandOptionType.String, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const user = interaction.options.getUser('user', true)
+    const durationInput = interaction.options.getString('duration', true)
+    const reason = interaction.options.getString('reason', true)
+
+    if (user.id === interaction.user.id) {
+      await interaction.reply({ content: "You can't mute yourself.", ephemeral: true })
+      return
+    }
+
+    const ms = parseDuration(durationInput)
+    if (!ms) {
+      await interaction.reply({ content: 'Invalid duration — use a number plus s/m/h/d, e.g. `10m`, `2h`, `1d`.', ephemeral: true })
+      return
+    }
+    const clampedMs = Math.min(ms, MAX_TIMEOUT_MS)
+
+    const member = interaction.guild.members.cache.get(user.id)
+    if (!member) {
+      await interaction.reply({ content: 'That user is not a member of this server.', ephemeral: true })
+      return
+    }
+    if (!member.moderatable) {
+      await interaction.reply({ content: "I don't have permission to timeout that member (role hierarchy).", ephemeral: true })
+      return
+    }
+
+    await member.timeout(clampedMs, reason)
+    const durationSeconds = Math.round(clampedMs / 1000)
+    await modLog.record({ client: interaction.client, guildId: interaction.guildId, actionType: 'mute', target: user, staffUser: interaction.user, reason, durationSeconds })
+    await interaction.reply({ content: `Muted ${user.tag} for ${durationInput}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/news.command.js

@@ -0,0 +1,31 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType, ChannelType } = require('discord.js')
+
+const guildConfig = require('../../model/guildConfig')
+
+module.exports = {
+  data: {
+    name: 'news',
+    description: 'View or set the channel news posts are announced to.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'channel',
+        description: 'Channel for news announcements. Omit to view the current setting.',
+        type: ApplicationCommandOptionType.Channel,
+        channel_types: [ChannelType.GuildText],
+        required: false,
+      },
+    ],
+  },
+  async execute(interaction) {
+    const channel = interaction.options.getChannel('channel')
+    if (!channel) {
+      const currentId = await guildConfig.getNewsChannelId(interaction.guildId)
+      const content = currentId ? `News channel is set to <#${currentId}>.` : 'No news channel is set yet.'
+      await interaction.reply({ content, ephemeral: true })
+      return
+    }
+    await guildConfig.setNewsChannelId(interaction.guildId, channel.id)
+    await interaction.reply({ content: `News channel set to ${channel}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/ping.command.js

@@ -0,0 +1,15 @@
+const { PermissionFlagsBits } = require('discord.js')
+
+module.exports = {
+  data: {
+    name: 'ping',
+    description: 'Health-check — replies pong if the bot is alive and staff-permitted.',
+    // Restricted by default to members with Moderate Members — proves slash
+    // commands can be permission-gated via Discord's own permission model,
+    // per the spec's "restrict staff commands via Discord's permission system".
+    default_member_permissions: PermissionFlagsBits.ModerateMembers.toString(),
+  },
+  async execute(interaction) {
+    await interaction.reply({ content: 'pong', ephemeral: true })
+  },
+}

bot/src/discord/commands/role.command.js

@@ -0,0 +1,71 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const tempRoles = require('../../model/tempRoles')
+const { parseDuration } = require('../../utils/duration')
+
+module.exports = {
+  data: {
+    name: 'role',
+    description: 'Assign or remove a role for a single member.',
+    default_member_permissions: PermissionFlagsBits.ManageRoles.toString(),
+    options: [
+      {
+        name: 'add',
+        description: 'Add a role to a member, optionally temporary.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'user', description: 'Member', type: ApplicationCommandOptionType.User, required: true },
+          { name: 'role', description: 'Role to add', type: ApplicationCommandOptionType.Role, required: true },
+          { name: 'duration', description: 'Optional — makes this temporary, e.g. 1h, 2d, 7d', type: ApplicationCommandOptionType.String, required: false },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a role from a member.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'user', description: 'Member', type: ApplicationCommandOptionType.User, required: true },
+          { name: 'role', description: 'Role to remove', type: ApplicationCommandOptionType.Role, required: true },
+        ],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+    const user = interaction.options.getUser('user', true)
+    const role = interaction.options.getRole('role', true)
+    const member = interaction.guild.members.cache.get(user.id)
+
+    if (!member) {
+      await interaction.reply({ content: 'That user is not a member of this server.', ephemeral: true })
+      return
+    }
+
+    if (sub === 'add') {
+      await member.roles.add(role.id)
+      const durationInput = interaction.options.getString('duration')
+      if (!durationInput) {
+        await interaction.reply({ content: `Added ${role} to ${user.tag}.`, ephemeral: true })
+        return
+      }
+      const ms = parseDuration(durationInput)
+      if (!ms) {
+        await interaction.reply({
+          content: `Added ${role}, but "${durationInput}" isn't a valid duration so it won't expire automatically. Use e.g. 1h, 2d, 7d.`,
+          ephemeral: true,
+        })
+        return
+      }
+      const expiresAt = new Date(Date.now() + ms)
+      await tempRoles.add({ guildId: interaction.guildId, userId: user.id, roleId: role.id, expiresAt, createdBy: interaction.user.id })
+      await interaction.reply({ content: `Added ${role} to ${user.tag} until ${expiresAt.toLocaleString()}.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'remove') {
+      await member.roles.remove(role.id)
+      await tempRoles.remove(interaction.guildId, user.id, role.id)
+      await interaction.reply({ content: `Removed ${role} from ${user.tag}.`, ephemeral: true })
+    }
+  },
+}

bot/src/discord/commands/rolemenu.command.js

@@ -0,0 +1,85 @@
+const {
+  PermissionFlagsBits,
+  ApplicationCommandOptionType,
+  ChannelType,
+  EmbedBuilder,
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+} = require('discord.js')
+
+const roleMenus = require('../../model/roleMenus')
+
+// Capped at 5 roles per menu — a single Discord action row holds at most 5
+// buttons, and one row keeps this a single simple slash command instead of
+// needing a multi-step builder/modal flow.
+const MAX_ROLES = 5
+
+// role1/label1 are declared inline in `data` (ahead of the optional
+// `description` option, per Discord's required-before-optional rule) — this
+// generates the rest, all optional.
+function roleOptions(from, to) {
+  const opts = []
+  for (let i = from; i <= to; i++) {
+    opts.push({ name: `role${i}`, description: `Role #${i}`, type: ApplicationCommandOptionType.Role, required: false })
+    opts.push({ name: `label${i}`, description: `Button label for role #${i} (default: role name)`, type: ApplicationCommandOptionType.String, required: false })
+  }
+  return opts
+}
+
+module.exports = {
+  data: {
+    name: 'rolemenu',
+    description: 'Post a button menu for self-assignable roles (up to 5).',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    // Discord requires all required options before any optional ones across
+    // the whole array — role1 (required) must come before description
+    // (optional), even though they read more naturally in the other order.
+    options: [
+      { name: 'channel', description: 'Channel to post the menu in', type: ApplicationCommandOptionType.Channel, channel_types: [ChannelType.GuildText], required: true },
+      { name: 'title', description: 'Menu title', type: ApplicationCommandOptionType.String, required: true },
+      { name: 'role1', description: 'Role #1', type: ApplicationCommandOptionType.Role, required: true },
+      { name: 'description', description: 'Menu description', type: ApplicationCommandOptionType.String, required: false },
+      { name: 'label1', description: 'Button label for role #1 (default: role name)', type: ApplicationCommandOptionType.String, required: false },
+      ...roleOptions(2, MAX_ROLES),
+    ],
+  },
+  async execute(interaction) {
+    const channel = interaction.options.getChannel('channel', true)
+    const title = interaction.options.getString('title', true)
+    const description = interaction.options.getString('description') || undefined
+
+    const entries = []
+    for (let i = 1; i <= MAX_ROLES; i++) {
+      const role = interaction.options.getRole(`role${i}`)
+      if (!role) continue
+      const label = interaction.options.getString(`label${i}`) || role.name
+      entries.push({ roleId: role.id, label })
+    }
+
+    if (entries.length === 0) {
+      await interaction.reply({ content: 'Provide at least one role (role1).', ephemeral: true })
+      return
+    }
+
+    const embed = new EmbedBuilder().setTitle(title).setColor(0x6a8fc2)
+    if (description) embed.setDescription(description)
+
+    const row = new ActionRowBuilder().addComponents(
+      entries.map((e) =>
+        new ButtonBuilder().setCustomId(`rolemenu:${e.roleId}`).setLabel(e.label).setStyle(ButtonStyle.Secondary),
+      ),
+    )
+
+    const message = await channel.send({ embeds: [embed], components: [row] })
+    await roleMenus.add({
+      guildId: interaction.guildId,
+      channelId: channel.id,
+      messageId: message.id,
+      mapping: entries,
+      createdBy: interaction.user.id,
+    })
+
+    await interaction.reply({ content: `Role menu posted in ${channel}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/roles.command.js

@@ -0,0 +1,68 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+// Bulk targeting is "by existing role" only — the spec also mentions an
+// explicit list of members, but Discord slash commands have no multi-user
+// picker, so that variant is deferred rather than faked with a handful of
+// user1..user5 options that would feel arbitrary and cramped.
+module.exports = {
+  data: {
+    name: 'roles',
+    description: 'Bulk role operations across members who share an existing role.',
+    default_member_permissions: PermissionFlagsBits.ManageRoles.toString(),
+    options: [
+      {
+        name: 'bulk-assign',
+        description: 'Add a role to every member who has another role.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'has-role', description: 'Members with this role are targeted', type: ApplicationCommandOptionType.Role, required: true },
+          { name: 'add-role', description: 'Role to add to those members', type: ApplicationCommandOptionType.Role, required: true },
+        ],
+      },
+      {
+        name: 'bulk-remove',
+        description: 'Remove a role from every member who has another role.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'has-role', description: 'Members with this role are targeted', type: ApplicationCommandOptionType.Role, required: true },
+          { name: 'remove-role', description: 'Role to remove from those members', type: ApplicationCommandOptionType.Role, required: true },
+        ],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+    // Fetching every member + looping role updates can easily exceed
+    // Discord's 3-second initial-response window.
+    await interaction.deferReply({ ephemeral: true })
+
+    const hasRole = interaction.options.getRole('has-role', true)
+    const members = await interaction.guild.members.fetch()
+    const targets = members.filter((m) => m.roles.cache.has(hasRole.id))
+
+    if (sub === 'bulk-assign') {
+      const addRole = interaction.options.getRole('add-role', true)
+      let count = 0
+      for (const member of targets.values()) {
+        if (!member.roles.cache.has(addRole.id)) {
+          await member.roles.add(addRole.id).catch(() => {})
+          count++
+        }
+      }
+      await interaction.editReply({ content: `Added ${addRole} to ${count} member(s) who have ${hasRole}.` })
+      return
+    }
+
+    if (sub === 'bulk-remove') {
+      const removeRole = interaction.options.getRole('remove-role', true)
+      let count = 0
+      for (const member of targets.values()) {
+        if (member.roles.cache.has(removeRole.id)) {
+          await member.roles.remove(removeRole.id).catch(() => {})
+          count++
+        }
+      }
+      await interaction.editReply({ content: `Removed ${removeRole} from ${count} member(s) who have ${hasRole}.` })
+    }
+  },
+}

bot/src/discord/commands/schedule.command.js

@@ -0,0 +1,119 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType, ChannelType } = require('discord.js')
+const cron = require('node-cron')
+
+const scheduledMessages = require('../../model/scheduledMessages')
+const scheduler = require('../../scheduler/scheduler')
+const { parseDuration } = require('../../utils/duration')
+
+module.exports = {
+  data: {
+    name: 'schedule',
+    description: 'Manage recurring and one-off scheduled channel messages.',
+    default_member_permissions: PermissionFlagsBits.ManageGuild.toString(),
+    options: [
+      {
+        name: 'recurring',
+        description: 'Schedule a recurring message on a cron schedule.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'channel', description: 'Channel to post in', type: ApplicationCommandOptionType.Channel, channel_types: [ChannelType.GuildText], required: true },
+          { name: 'cron', description: 'Cron expression, e.g. "0 9 * * 5" (Fridays 9am)', type: ApplicationCommandOptionType.String, required: true },
+          { name: 'message', description: 'Message content to post', type: ApplicationCommandOptionType.String, required: true },
+        ],
+      },
+      {
+        name: 'once',
+        description: 'Schedule a one-off message for a future time.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [
+          { name: 'channel', description: 'Channel to post in', type: ApplicationCommandOptionType.Channel, channel_types: [ChannelType.GuildText], required: true },
+          { name: 'in', description: 'When to post, e.g. 30m, 2h, 1d', type: ApplicationCommandOptionType.String, required: true },
+          { name: 'message', description: 'Message content to post', type: ApplicationCommandOptionType.String, required: true },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a scheduled message by id.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [{ name: 'id', description: 'Scheduled message id (see /schedule list)', type: ApplicationCommandOptionType.Integer, required: true }],
+      },
+      {
+        name: 'list',
+        description: 'List all scheduled messages.',
+        type: ApplicationCommandOptionType.Subcommand,
+        options: [],
+      },
+    ],
+  },
+  async execute(interaction) {
+    const sub = interaction.options.getSubcommand()
+
+    if (sub === 'recurring') {
+      const channel = interaction.options.getChannel('channel', true)
+      const cronExpr = interaction.options.getString('cron', true)
+      const message = interaction.options.getString('message', true)
+      if (!cron.validate(cronExpr)) {
+        await interaction.reply({ content: `"${cronExpr}" isn't a valid cron expression.`, ephemeral: true })
+        return
+      }
+      const id = await scheduledMessages.addRecurring({
+        guildId: interaction.guildId,
+        channelId: channel.id,
+        content: message,
+        cronExpression: cronExpr,
+        createdBy: interaction.user.id,
+        createdByTag: interaction.user.tag,
+      })
+      await scheduler.refresh()
+      await interaction.reply({ content: `Scheduled recurring message #${id} in ${channel} on \`${cronExpr}\`.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'once') {
+      const channel = interaction.options.getChannel('channel', true)
+      const inInput = interaction.options.getString('in', true)
+      const message = interaction.options.getString('message', true)
+      const ms = parseDuration(inInput)
+      if (!ms) {
+        await interaction.reply({ content: 'Invalid time — use a number plus s/m/h/d, e.g. `30m`, `2h`, `1d`.', ephemeral: true })
+        return
+      }
+      const runAt = new Date(Date.now() + ms)
+      const id = await scheduledMessages.addOnce({
+        guildId: interaction.guildId,
+        channelId: channel.id,
+        content: message,
+        runAt,
+        createdBy: interaction.user.id,
+        createdByTag: interaction.user.tag,
+      })
+      await interaction.reply({ content: `Scheduled one-off message #${id} in ${channel} for ${runAt.toLocaleString()}.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'remove') {
+      const id = interaction.options.getInteger('id', true)
+      const removed = await scheduledMessages.remove(interaction.guildId, id)
+      await scheduler.refresh()
+      await interaction.reply({ content: removed ? `Removed scheduled message #${id}.` : `No scheduled message #${id} found.`, ephemeral: true })
+      return
+    }
+
+    if (sub === 'list') {
+      const rows = await scheduledMessages.list(interaction.guildId)
+      if (rows.length === 0) {
+        await interaction.reply({ content: 'No scheduled messages.', ephemeral: true })
+        return
+      }
+      const lines = rows.map((r) => {
+        const kind = r.cron_expression
+          ? `cron \`${r.cron_expression}\``
+          : r.sent_at
+            ? `sent ${new Date(r.sent_at).toLocaleString()}`
+            : `due ${new Date(r.run_at).toLocaleString()}`
+        return `**#${r.id}** <#${r.channel_id}> — ${kind}${r.enabled ? '' : ' (disabled)'}`
+      })
+      await interaction.reply({ content: lines.join('\n'), ephemeral: true })
+    }
+  },
+}

bot/src/discord/commands/warn.command.js

@@ -0,0 +1,40 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType } = require('discord.js')
+
+const modLog = require('../modLog')
+const warnings = require('../../model/warnings')
+
+// Escalation (e.g. "3 active warns -> auto-mute for X hours") and warning
+// decay/expiry are in the original spec but deferred past this phase — this
+// just records the warning and posts it to the mod-log, matching the
+// "Suggested Build Order" step 2 scope (core moderation).
+module.exports = {
+  data: {
+    name: 'warn',
+    description: 'Log a warning against a member.',
+    default_member_permissions: PermissionFlagsBits.ModerateMembers.toString(),
+    options: [
+      { name: 'user', description: 'Member to warn', type: ApplicationCommandOptionType.User, required: true },
+      { name: 'reason', description: 'Reason for the warning', type: ApplicationCommandOptionType.String, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const user = interaction.options.getUser('user', true)
+    const reason = interaction.options.getString('reason', true)
+
+    if (user.id === interaction.user.id) {
+      await interaction.reply({ content: "You can't warn yourself.", ephemeral: true })
+      return
+    }
+
+    await warnings.add({
+      guildId: interaction.guildId,
+      targetUserId: user.id,
+      targetTag: user.tag,
+      staffUserId: interaction.user.id,
+      staffTag: interaction.user.tag,
+      reason,
+    })
+    await modLog.record({ client: interaction.client, guildId: interaction.guildId, actionType: 'warn', target: user, staffUser: interaction.user, reason })
+    await interaction.reply({ content: `Warned ${user.tag}.`, ephemeral: true })
+  },
+}

bot/src/discord/commands/warnings.command.js

@@ -0,0 +1,34 @@
+const { PermissionFlagsBits, ApplicationCommandOptionType, EmbedBuilder } = require('discord.js')
+
+const warnings = require('../../model/warnings')
+
+module.exports = {
+  data: {
+    name: 'warnings',
+    description: "List a member's active warnings.",
+    default_member_permissions: PermissionFlagsBits.ModerateMembers.toString(),
+    options: [
+      { name: 'user', description: 'Member to look up', type: ApplicationCommandOptionType.User, required: true },
+    ],
+  },
+  async execute(interaction) {
+    const user = interaction.options.getUser('user', true)
+    const rows = await warnings.listActive(interaction.guildId, user.id)
+
+    if (rows.length === 0) {
+      await interaction.reply({ content: `${user.tag} has no active warnings.`, ephemeral: true })
+      return
+    }
+
+    const embed = new EmbedBuilder()
+      .setColor(0xe0b070)
+      .setTitle(`Warnings — ${user.tag}`)
+      .setDescription(
+        rows
+          .map((w, i) => `**${i + 1}.** ${w.reason || '(no reason given)'} — by ${w.staff_tag || 'unknown'} on ${new Date(w.created_at).toLocaleDateString()}`)
+          .join('\n'),
+      )
+
+    await interaction.reply({ embeds: [embed], ephemeral: true })
+  },
+}

bot/src/discord/commands/wiki.command.js

@@ -0,0 +1,40 @@
+const { ApplicationCommandOptionType } = require('discord.js')
+
+const siteApiClient = require('../../site/siteApiClient')
+
+// Public command — no default_member_permissions restriction. Read-only:
+// searches wiki titles/content and links to the best match. Never posts to or
+// edits the wiki. Category-scoped search (spec's optional "/wiki spells
+// fireball") is deferred — the site's public search endpoint currently
+// ignores category filters whenever a text query is given.
+function siteOrigin() {
+  const base = process.env.SITE_PUBLIC_URL || 'http://localhost:3000/api/v1/public'
+  return new URL(base).origin
+}
+
+module.exports = {
+  data: {
+    name: 'wiki',
+    description: 'Search the wiki.',
+    options: [{ name: 'query', description: 'What to search for', type: ApplicationCommandOptionType.String, required: true }],
+  },
+  async execute(interaction) {
+    const query = interaction.options.getString('query', true)
+    await interaction.deferReply()
+
+    const result = await siteApiClient.searchWiki(query)
+    if (result.maintenance) {
+      await interaction.editReply({ content: `The wiki is unavailable right now: ${result.message || 'maintenance mode'}` })
+      return
+    }
+    if (!result.ok || !result.data || result.data.length === 0) {
+      await interaction.editReply({ content: `No wiki results for "${query}".` })
+      return
+    }
+
+    const best = result.data[0]
+    const url = `${siteOrigin()}/wiki/${best.slug}`
+    const content = best.excerpt ? `**${best.title}**\n${best.excerpt}\n${url}` : `**${best.title}**\n${url}`
+    await interaction.editReply({ content })
+  },
+}

bot/src/discord/discordManager.js

@@ -0,0 +1,144 @@
+// Owns the single discord.js Client instance for this process: lifecycle
+// (start/stop/status) and slash-command registration/dispatch. Command
+// definitions themselves live in ./commands — this file only wires them up.
+const { Client, GatewayIntentBits, REST, Routes } = require('discord.js')
+
+const createLogger = require('../utils/logger')
+const commands = require('./commands')
+const messageFilter = require('./messageFilter')
+const scheduler = require('../scheduler/scheduler')
+const roleMenuHandler = require('./roleMenuHandler')
+const { handleGuildMemberAdd } = require('./guildMemberAdd')
+const { handleGuildMemberRemove } = require('./guildMemberRemove')
+const inviteTracker = require('./inviteTracker')
+const tempRoleSweeper = require('../roles/tempRoleSweeper')
+const inviteScheduler = require('../invites/inviteScheduler')
+
+const log = createLogger('discord')
+
+let client = null
+let guildId = null
+let status = 'disconnected' // disconnected | connecting | connected | error
+let statusDetail = null
+let lastConnectedAt = null
+
+async function registerCommands(applicationId, targetGuildId) {
+  const rest = new REST({ version: '10' }).setToken(client.token)
+  await rest.put(Routes.applicationGuildCommands(applicationId, targetGuildId), {
+    body: commands.all.map((c) => c.data),
+  })
+  log.info('registered guild slash commands', { guildId: targetGuildId, count: commands.all.length })
+}
+
+async function stop() {
+  if (!client) {
+    status = 'disconnected'
+    statusDetail = null
+    return
+  }
+  scheduler.stop()
+  tempRoleSweeper.stop()
+  inviteScheduler.stop()
+  try {
+    await client.destroy()
+  } catch (err) {
+    log.warn('error while destroying client', { message: err.message })
+  }
+  client = null
+  status = 'disconnected'
+  statusDetail = null
+  log.info('discord client disconnected')
+}
+
+// start({ token, guildId }) — (re)connects. Always stops any existing client
+// first so re-saving config or toggling Enabled off/on is idempotent.
+async function start({ token, guildId: gid }) {
+  await stop()
+  guildId = gid
+  status = 'connecting'
+  statusDetail = null
+
+  // GuildMessages + MessageContent (Phase 3, filter) and GuildMembers
+  // (Phase 5, auto-role + bulk role ops) are all privileged — must be enabled
+  // in the Discord Developer Portal, see the Phase 1 setup notes. GuildInvites
+  // (Phase 6b, invite-usage attribution) is NOT privileged — no portal toggle.
+  client = new Client({
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+      GatewayIntentBits.MessageContent,
+      GatewayIntentBits.GuildMembers,
+      GatewayIntentBits.GuildInvites,
+    ],
+  })
+
+  client.once('ready', async () => {
+    try {
+      await registerCommands(client.application.id, guildId)
+      await scheduler.start(client)
+      tempRoleSweeper.start(client)
+      inviteScheduler.start(client, guildId)
+      await inviteTracker.prime(client, guildId)
+      status = 'connected'
+      statusDetail = null
+      lastConnectedAt = new Date()
+      log.info('discord client ready', { user: client.user?.tag, guildId })
+    } catch (err) {
+      status = 'error'
+      statusDetail = `startup failed: ${err.message}`
+      log.error('post-login startup failed (commands/scheduler/temp-roles/invites)', { message: err.message })
+    }
+  })
+
+  client.on('interactionCreate', async (interaction) => {
+    if (await roleMenuHandler.handleInteraction(interaction)) return
+    if (!interaction.isChatInputCommand()) return
+    const command = commands.get(interaction.commandName)
+    if (!command) return
+    try {
+      await command.execute(interaction)
+    } catch (err) {
+      log.error('command execution failed', { command: interaction.commandName, message: err.message })
+      const payload = { content: 'Something went wrong running that command.', ephemeral: true }
+      if (interaction.replied || interaction.deferred) await interaction.followUp(payload)
+      else await interaction.reply(payload)
+    }
+  })
+
+  client.on('messageCreate', messageFilter.handleMessageCreate)
+  client.on('guildMemberAdd', handleGuildMemberAdd)
+  client.on('guildMemberRemove', handleGuildMemberRemove)
+  // Keep the invite-use cache fresh so guildMemberAdd can attribute joins.
+  client.on('inviteCreate', inviteTracker.onInviteCreate)
+  client.on('inviteDelete', inviteTracker.onInviteDelete)
+
+  client.on('error', (err) => {
+    status = 'error'
+    statusDetail = err.message
+    log.error('discord client error', { message: err.message })
+  })
+
+  try {
+    await client.login(token)
+  } catch (err) {
+    status = 'error'
+    statusDetail = err.message
+    client = null
+    log.error('discord login failed', { message: err.message })
+    throw err
+  }
+}
+
+function getStatus() {
+  return { status, statusDetail, guildId, lastConnectedAt }
+}
+
+// For code that needs the live client + which guild it's connected to (the
+// /internal/announce handler, slash commands already get both from the
+// interaction itself so they don't need this). Returns null if disconnected.
+function getConnection() {
+  if (!client || status !== 'connected') return null
+  return { client, guildId }
+}
+
+module.exports = { start, stop, getStatus, getConnection }

bot/src/discord/guildMemberAdd.js

@@ -0,0 +1,45 @@
+// Member join handling: record the join event (with best-effort invite
+// attribution, Phase 6b) then apply the configured auto-role. Requires the
+// Server Members privileged intent (already enabled per the Phase 1 setup notes)
+// and, for invite attribution, the GuildInvites intent.
+const guildConfig = require('../model/guildConfig')
+const memberEvents = require('../model/memberEvents')
+const inviteTracker = require('./inviteTracker')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('members')
+
+async function handleGuildMemberAdd(member) {
+  // Attribute the invite first (diffs the invite-use cache), then record the join.
+  // Both are best-effort — a failure here must never block the auto-role below.
+  let invite = { code: null, inviterId: null, inviterTag: null }
+  try {
+    invite = await inviteTracker.attribute(member)
+  } catch (err) {
+    log.warn('invite attribution threw', { userId: member.id, message: err.message })
+  }
+  try {
+    await memberEvents.record({
+      guildId: member.guild.id,
+      eventType: 'join',
+      discordUserId: member.id,
+      username: member.user?.tag,
+      inviteCode: invite.code,
+      inviterId: invite.inviterId,
+      inviterTag: invite.inviterTag,
+    })
+  } catch (err) {
+    log.warn('member join record failed', { userId: member.id, message: err.message })
+  }
+
+  try {
+    const roleId = await guildConfig.getAutoRoleId(member.guild.id)
+    if (!roleId) return
+    await member.roles.add(roleId)
+    log.info('auto-role assigned', { userId: member.id, roleId })
+  } catch (err) {
+    log.warn('auto-role assignment failed', { userId: member.id, message: err.message })
+  }
+}
+
+module.exports = { handleGuildMemberAdd }

bot/src/discord/guildMemberRemove.js

@@ -0,0 +1,23 @@
+// Member leave handling (Phase 6b): record a leave event for the dashboard's
+// members feed. Fires on both voluntary leaves and kicks/bans — Discord doesn't
+// distinguish them on this event, and the mod-action (if any) is logged
+// separately via mod_actions, so a leave row here is purely the lifecycle fact.
+const memberEvents = require('../model/memberEvents')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('members')
+
+async function handleGuildMemberRemove(member) {
+  try {
+    await memberEvents.record({
+      guildId: member.guild.id,
+      eventType: 'leave',
+      discordUserId: member.id,
+      username: member.user?.tag,
+    })
+  } catch (err) {
+    log.warn('member leave record failed', { userId: member.id, message: err.message })
+  }
+}
+
+module.exports = { handleGuildMemberRemove }

bot/src/discord/inviteTracker.js

@@ -0,0 +1,74 @@
+// Best-effort invite-usage attribution (Phase 6b). Discord doesn't tell you
+// which invite a member used, so the standard approach is to keep a cache of
+// each invite's use-count and, on guildMemberAdd, re-fetch and find the one
+// whose count went up. Requires the GuildInvites intent + Manage Guild (the bot
+// already creates/deletes invites, so it has the permission). All calls are
+// best-effort: any failure just yields a null attribution and the join is still
+// recorded. Vanity-URL and bot-added joins are inherently unattributable.
+const createLogger = require('../utils/logger')
+
+const log = createLogger('invites')
+
+// guildId -> Map<inviteCode, uses>
+const cache = new Map()
+
+async function snapshot(guild) {
+  const map = new Map()
+  const invites = await guild.invites.fetch()
+  for (const inv of invites.values()) map.set(inv.code, inv.uses || 0)
+  return map
+}
+
+// Populate the cache for a guild (call once the client is ready).
+async function prime(client, guildId) {
+  try {
+    const guild = client.guilds.cache.get(guildId) || (await client.guilds.fetch(guildId))
+    cache.set(guildId, await snapshot(guild))
+    log.info('invite cache primed', { guildId, count: cache.get(guildId).size })
+  } catch (err) {
+    log.warn('invite cache prime failed (missing Manage Guild / GuildInvites?)', { message: err.message })
+  }
+}
+
+function onInviteCreate(invite) {
+  if (!invite.guild) return
+  const g = cache.get(invite.guild.id) || new Map()
+  g.set(invite.code, invite.uses || 0)
+  cache.set(invite.guild.id, g)
+}
+
+function onInviteDelete(invite) {
+  if (!invite.guild) return
+  const g = cache.get(invite.guild.id)
+  if (g) g.delete(invite.code)
+}
+
+// Diff current invite uses against the cached snapshot to find which invite the
+// joining member used, then refresh the cache. Returns { code, inviterId,
+// inviterTag } with nulls when it can't be determined.
+async function attribute(member) {
+  const empty = { code: null, inviterId: null, inviterTag: null }
+  try {
+    const guild = member.guild
+    const before = cache.get(guild.id) || new Map()
+    const current = await guild.invites.fetch()
+
+    let found = empty
+    for (const inv of current.values()) {
+      const prev = before.get(inv.code) || 0
+      if ((inv.uses || 0) > prev && found === empty) {
+        found = { code: inv.code, inviterId: inv.inviter?.id || null, inviterTag: inv.inviter?.tag || null }
+      }
+    }
+
+    const next = new Map()
+    for (const inv of current.values()) next.set(inv.code, inv.uses || 0)
+    cache.set(guild.id, next)
+    return found
+  } catch (err) {
+    log.warn('invite attribution failed', { message: err.message })
+    return empty
+  }
+}
+
+module.exports = { prime, onInviteCreate, onInviteDelete, attribute }

bot/src/discord/messageFilter.js

@@ -0,0 +1,137 @@
+// messageCreate orchestration: allowlist bypass -> invite link -> banned word
+// -> spam/mass-mention/mass-emoji. Invite/spam triggers always delete + warn
+// (no severity tiers for those, unlike the word filter) — kept simple per the
+// spec's "start simple" guidance. Filter-triggered mutes use a fixed 10-minute
+// duration; per-severity-configurable durations are a future refinement.
+const filterCache = require('../filter/filterCache')
+const { findMatch } = require('../filter/normalize')
+const inviteFilter = require('../filter/inviteFilter')
+const spamFilter = require('../filter/spamFilter')
+const warnings = require('../model/warnings')
+const filterHits = require('../model/filterHits')
+const spamHits = require('../model/spamHits')
+const modLog = require('./modLog')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('filter')
+
+const FILTER_MUTE_SECONDS = 600 // 10 minutes
+
+function botActor(client) {
+  return { id: client.user.id, tag: client.user.tag }
+}
+
+// Dashboard event capture (Phase 6b). Best-effort — recording a hit must never
+// break the moderation action it accompanies, so failures are swallowed+logged.
+async function recordFilterHit(message, hitType, matched, actionTaken) {
+  try {
+    await filterHits.record({
+      guildId: message.guildId,
+      hitType,
+      discordUserId: message.author.id,
+      username: message.author.tag,
+      channelId: message.channelId,
+      matched,
+      actionTaken,
+    })
+  } catch (err) {
+    log.warn('filter hit record failed', { message: err.message })
+  }
+}
+
+async function recordSpamHit(message, spamType) {
+  try {
+    await spamHits.record({
+      guildId: message.guildId,
+      spamType,
+      discordUserId: message.author.id,
+      username: message.author.tag,
+      channelId: message.channelId,
+    })
+  } catch (err) {
+    log.warn('spam hit record failed', { message: err.message })
+  }
+}
+
+// Which spam rule tripped (for the spam_hits row). isRateLimited has a side
+// effect (records this message's timestamp) so it must be evaluated first, and
+// exactly once — mirroring the original OR-order.
+function detectSpam(message) {
+  if (spamFilter.isRateLimited(message.guildId, message.author.id)) return 'rate_limit'
+  if (spamFilter.isMassMention(message)) return 'mass_mention'
+  if (spamFilter.isMassEmoji(message.content)) return 'mass_emoji'
+  return null
+}
+
+async function isBypassed(message, cache) {
+  if (cache.allowChannels.has(message.channelId)) return true
+  const memberRoles = message.member ? message.member.roles.cache : null
+  if (memberRoles && [...memberRoles.keys()].some((id) => cache.allowRoles.has(id))) return true
+  return false
+}
+
+async function applyWarnAction(message, reason) {
+  const staff = botActor(message.client)
+  await warnings.add({
+    guildId: message.guildId,
+    targetUserId: message.author.id,
+    targetTag: message.author.tag,
+    staffUserId: staff.id,
+    staffTag: staff.tag,
+    reason,
+  })
+  await modLog.record({ client: message.client, guildId: message.guildId, actionType: 'warn', target: message.author, staffUser: staff, reason })
+}
+
+async function applyMuteAction(message, reason) {
+  const staff = botActor(message.client)
+  if (message.member && message.member.moderatable) {
+    await message.member.timeout(FILTER_MUTE_SECONDS * 1000, reason)
+  }
+  await modLog.record({
+    client: message.client,
+    guildId: message.guildId,
+    actionType: 'mute',
+    target: message.author,
+    staffUser: staff,
+    reason,
+    durationSeconds: FILTER_MUTE_SECONDS,
+  })
+}
+
+async function handleMessageCreate(message) {
+  if (message.author.bot || !message.guildId) return
+
+  try {
+    const cache = await filterCache.getOrLoad(message.guildId)
+    if (await isBypassed(message, cache)) return
+
+    const foreignCode = await inviteFilter.foreignInviteCode(message)
+    if (foreignCode) {
+      await message.delete().catch(() => {})
+      await recordFilterHit(message, 'invite', foreignCode, 'warn')
+      await applyWarnAction(message, 'Posted a Discord invite link')
+      return
+    }
+
+    const match = findMatch(message.content, cache.words)
+    if (match) {
+      await message.delete().catch(() => {})
+      await recordFilterHit(message, 'word', match.word, match.severity)
+      if (match.severity === 'mute') await applyMuteAction(message, `Filtered word: ${match.word}`)
+      else if (match.severity === 'warn') await applyWarnAction(message, `Filtered word: ${match.word}`)
+      return
+    }
+
+    const spamType = detectSpam(message)
+    if (spamType) {
+      await message.delete().catch(() => {})
+      await recordSpamHit(message, spamType)
+      await applyWarnAction(message, 'Automated spam detection (rate limit / mass mention / mass emoji)')
+    }
+  } catch (err) {
+    log.error('messageFilter failed', { message: err.message })
+  }
+}
+
+module.exports = { handleMessageCreate }

bot/src/discord/modLog.js

@@ -0,0 +1,53 @@
+// Shared by every moderation command (ban/kick/mute/warn): writes the audit
+// row and posts the embed to the configured mod-log channel. Takes `client`
+// as a parameter (from interaction.client) rather than importing
+// discordManager directly, to avoid a require cycle (discordManager -> commands
+// -> modLog -> discordManager).
+const { EmbedBuilder } = require('discord.js')
+
+const db = require('../db')
+const guildConfig = require('../model/guildConfig')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('modlog')
+
+const COLOR = { ban: 0xd98b84, kick: 0xe0b070, mute: 0xe0b070, warn: 0xe0b070 }
+
+async function record({ client, guildId, actionType, target, staffUser, reason, durationSeconds }) {
+  await db.query(
+    `INSERT INTO mod_actions (guild_id, action_type, target_user_id, target_tag, staff_user_id, staff_tag, reason, duration_seconds)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [guildId, actionType, target.id, target.tag || null, staffUser.id, staffUser.tag || null, reason || null, durationSeconds || null],
+  )
+
+  try {
+    const channelId = await guildConfig.getModLogChannelId(guildId)
+    if (!channelId) return
+    const channel = await client.channels.fetch(channelId)
+    if (!channel || !channel.isTextBased()) return
+
+    const embed = new EmbedBuilder()
+      .setColor(COLOR[actionType] || 0x9aa5b1)
+      .setTitle(actionType.toUpperCase())
+      .addFields(
+        { name: 'Target', value: `${target.tag || target.id} (${target.id})`, inline: true },
+        { name: 'Staff', value: `${staffUser.tag || staffUser.id} (${staffUser.id})`, inline: true },
+      )
+      .setTimestamp()
+    if (reason) embed.addFields({ name: 'Reason', value: reason })
+    if (durationSeconds) embed.addFields({ name: 'Duration', value: formatDuration(durationSeconds), inline: true })
+
+    await channel.send({ embeds: [embed] })
+  } catch (err) {
+    log.warn('failed to post mod-log embed', { message: err.message })
+  }
+}
+
+function formatDuration(seconds) {
+  if (seconds % 86400 === 0) return `${seconds / 86400}d`
+  if (seconds % 3600 === 0) return `${seconds / 3600}h`
+  if (seconds % 60 === 0) return `${seconds / 60}m`
+  return `${seconds}s`
+}
+
+module.exports = { record }

bot/src/discord/newsAnnounce.js

@@ -0,0 +1,26 @@
+// Shared by the /internal/announce webhook (site publishes a news post) and
+// the manual /announce command (staff re-posts/boosts an existing one) — so
+// both paths produce an identical embed.
+const { EmbedBuilder } = require('discord.js')
+
+const guildConfig = require('../model/guildConfig')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('news')
+
+async function postAnnounce(client, guildId, { title, excerpt, url, imageUrl }) {
+  const channelId = await guildConfig.getNewsChannelId(guildId)
+  if (!channelId) throw new Error('No news channel configured — set one with /news first.')
+
+  const channel = await client.channels.fetch(channelId)
+  if (!channel || !channel.isTextBased()) throw new Error('Configured news channel is missing or not text-based.')
+
+  const embed = new EmbedBuilder().setColor(0x6a8fc2).setTitle(title).setURL(url)
+  if (excerpt) embed.setDescription(excerpt)
+  if (imageUrl) embed.setImage(imageUrl)
+
+  await channel.send({ embeds: [embed] })
+  log.info('news announced', { title, channelId })
+}
+
+module.exports = { postAnnounce }

bot/src/discord/roleMenuHandler.js

@@ -0,0 +1,41 @@
+// Button-based self-assignable role menus. customId is `rolemenu:<roleId>` —
+// the message's own id (not known until after it's sent, so it can't be
+// embedded in the customId itself) is instead used to look up the tracked
+// role_menus row and confirm the clicked roleId is really part of that
+// menu's mapping, so a stale/foreign button can't toggle an untracked role.
+const roleMenus = require('../model/roleMenus')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('rolemenu')
+
+const PREFIX = 'rolemenu:'
+
+// Returns true if this handler owned the interaction (caller should stop
+// looking for another handler), false if it's not a role-menu button at all.
+async function handleInteraction(interaction) {
+  if (!interaction.isButton() || !interaction.customId.startsWith(PREFIX)) return false
+
+  const roleId = interaction.customId.slice(PREFIX.length)
+  try {
+    const menu = await roleMenus.getByMessageId(interaction.message.id)
+    if (!menu || !menu.mapping.some((m) => m.roleId === roleId)) {
+      await interaction.reply({ content: 'This role menu is no longer valid.', ephemeral: true })
+      return true
+    }
+
+    const member = interaction.member
+    if (member.roles.cache.has(roleId)) {
+      await member.roles.remove(roleId)
+      await interaction.reply({ content: `Removed <@&${roleId}>.`, ephemeral: true })
+    } else {
+      await member.roles.add(roleId)
+      await interaction.reply({ content: `Added <@&${roleId}>.`, ephemeral: true })
+    }
+  } catch (err) {
+    log.error('role menu toggle failed', { message: err.message })
+    await interaction.reply({ content: 'Something went wrong toggling that role.', ephemeral: true }).catch(() => {})
+  }
+  return true
+}
+
+module.exports = { handleInteraction }

bot/src/filter/filterCache.js

@@ -0,0 +1,31 @@
+// In-memory per-guild filter state (word list + allowlist), loaded at startup
+// and refreshed on config change — the messageCreate handler runs on every
+// message, so it must never hit the DB per message (per the spec's
+// performance note).
+const filterWords = require('../model/filterWords')
+const filterAllowlist = require('../model/filterAllowlist')
+
+const cache = new Map() // guildId -> { words, allowRoles: Set, allowChannels: Set }
+
+async function load(guildId) {
+  const [words, roles, channels] = await Promise.all([
+    filterWords.list(guildId),
+    filterAllowlist.getRoles(guildId),
+    filterAllowlist.getChannels(guildId),
+  ])
+  const entry = { words, allowRoles: new Set(roles), allowChannels: new Set(channels) }
+  cache.set(guildId, entry)
+  return entry
+}
+
+// Lazy-loads on first access per guild (e.g. the first message after boot).
+async function getOrLoad(guildId) {
+  return cache.get(guildId) || load(guildId)
+}
+
+// Called by /filter and /filterallow after any mutation.
+function refresh(guildId) {
+  return load(guildId)
+}
+
+module.exports = { getOrLoad, refresh }

bot/src/filter/inviteFilter.js

@@ -0,0 +1,26 @@
+// Detects Discord invite links and blocks any that don't resolve to the
+// current guild (anti-raid/anti-advertising). An invite that fails to resolve
+// (expired/invalid/vanity-only) is treated as foreign too — safer default
+// than silently letting an unresolvable link through.
+const INVITE_REGEX = /(?:discord\.gg|discord(?:app)?\.com\/invite)\/([a-zA-Z0-9-]+)/gi
+
+// Returns the first foreign (or unresolvable) invite code found in the message,
+// or null if the message contains no foreign invites. Returning the code (rather
+// than a bare boolean) lets the caller record which invite was blocked.
+async function foreignInviteCode(message) {
+  const matches = [...message.content.matchAll(INVITE_REGEX)]
+  if (matches.length === 0) return null
+
+  for (const match of matches) {
+    const code = match[1]
+    try {
+      const invite = await message.client.fetchInvite(code)
+      if (invite.guild?.id !== message.guildId) return code
+    } catch {
+      return code
+    }
+  }
+  return null
+}
+
+module.exports = { foreignInviteCode }

bot/src/filter/normalize.js

@@ -0,0 +1,33 @@
+// Basic obfuscation-resistant normalization for the word filter: lowercase,
+// common leetspeak substitutions, and collapsing 3+ repeated characters
+// ("sooooo" -> "so") to one. Deliberately simple per the spec ("start simple,
+// leave room to tighten later") — spaced-out letters ("b a d") and more exotic
+// unicode lookalikes aren't handled yet.
+const SUBS = { 4: 'a', '@': 'a', 3: 'e', 1: 'i', '!': 'i', 0: 'o', $: 's', 5: 's', 7: 't' }
+const SUB_CHARS = /[4@31!05$7]/g
+
+function normalize(text) {
+  return text
+    .toLowerCase()
+    .replace(SUB_CHARS, (ch) => SUBS[ch] || ch)
+    .replace(/(.)\1{2,}/g, '$1')
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// Word-boundary match against already-normalized text. `word` is normalized
+// here too, so callers can pass the raw stored value.
+function matches(normalizedText, word) {
+  const pattern = new RegExp(`\\b${escapeRegex(normalize(word))}\\b`, 'i')
+  return pattern.test(normalizedText)
+}
+
+// Returns the first matching filter_words row ({word, severity}) or null.
+function findMatch(content, words) {
+  const normalizedText = normalize(content)
+  return words.find((w) => matches(normalizedText, w.word)) || null
+}
+
+module.exports = { normalize, matches, findMatch }

bot/src/filter/spamFilter.js

@@ -0,0 +1,42 @@
+// Basic in-memory spam/rate-limit detection. Per-user message-rate tracking is
+// the only stateful piece here (mass-mention/mass-emoji are per-message
+// counts) — kept in memory rather than the DB since this runs on every
+// message and needs to be fast.
+const RATE_LIMIT_COUNT = 5
+const RATE_LIMIT_WINDOW_MS = 5000
+const MENTION_THRESHOLD = 5
+const EMOJI_THRESHOLD = 10
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000
+
+const history = new Map() // `${guildId}:${userId}` -> timestamps[]
+
+function isRateLimited(guildId, userId) {
+  const key = `${guildId}:${userId}`
+  const now = Date.now()
+  const timestamps = (history.get(key) || []).filter((t) => now - t < RATE_LIMIT_WINDOW_MS)
+  timestamps.push(now)
+  history.set(key, timestamps)
+  return timestamps.length > RATE_LIMIT_COUNT
+}
+
+function isMassMention(message) {
+  return message.mentions.users.size + message.mentions.roles.size > MENTION_THRESHOLD
+}
+
+const EMOJI_REGEX = /<a?:\w+:\d+>|\p{Extended_Pictographic}/gu
+
+function isMassEmoji(content) {
+  const count = (content.match(EMOJI_REGEX) || []).length
+  return count > EMOJI_THRESHOLD
+}
+
+// Periodic cleanup so `history` doesn't grow unbounded over a long-running
+// process — drops any key with no recent activity.
+setInterval(() => {
+  const now = Date.now()
+  for (const [key, timestamps] of history) {
+    if (timestamps.every((t) => now - t >= RATE_LIMIT_WINDOW_MS)) history.delete(key)
+  }
+}, SWEEP_INTERVAL_MS).unref()
+
+module.exports = { isRateLimited, isMassMention, isMassEmoji }

bot/src/internal/internal.controller.js

@@ -0,0 +1,50 @@
+const discordManager = require('../discord/discordManager')
+const newsAnnounce = require('../discord/newsAnnounce')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('internal')
+
+// POST /internal/config — called by the main server right after an admin
+// saves the Discord Bot panel, and by the bot's own bootstrap on startup
+// (via a GET to the server for the current config, then this same start/stop
+// logic locally). Body: { token, guildId, enabled }.
+async function setConfig(req, res) {
+  const { token, guildId, enabled } = req.body || {}
+  try {
+    if (enabled) {
+      if (!token || !guildId) {
+        return res.status(400).json({ message: 'token and guildId are required when enabled' })
+      }
+      await discordManager.start({ token, guildId })
+    } else {
+      await discordManager.stop()
+    }
+    return res.json(discordManager.getStatus())
+  } catch (err) {
+    log.error('setConfig failed', { message: err.message })
+    // Still 200 with an error status — the caller (admin panel) should surface
+    // discordManager's status/statusDetail rather than treat this as a 5xx.
+    return res.json(discordManager.getStatus())
+  }
+}
+
+// GET /internal/status — live connection state, polled by the admin panel.
+function getStatusHandler(req, res) {
+  return res.json(discordManager.getStatus())
+}
+
+// POST /internal/announce — called by the main server right after a news
+// post is published. Body: { title, excerpt, url, imageUrl }.
+async function announce(req, res) {
+  const connection = discordManager.getConnection()
+  if (!connection) return res.status(503).json({ message: 'Bot is not connected' })
+  try {
+    await newsAnnounce.postAnnounce(connection.client, connection.guildId, req.body || {})
+    return res.json({ posted: true })
+  } catch (err) {
+    log.warn('announce failed', { message: err.message })
+    return res.status(400).json({ message: err.message })
+  }
+}
+
+module.exports = { setConfig, getStatus: getStatusHandler, announce }

bot/src/internal/internal.routes.js

@@ -0,0 +1,14 @@
+const express = require('express')
+
+const requireInternalKey = require('./requireInternalKey')
+const ctrl = require('./internal.controller')
+
+const router = express.Router()
+
+router.use(requireInternalKey)
+
+router.post('/config', ctrl.setConfig)
+router.get('/status', ctrl.getStatus)
+router.post('/announce', ctrl.announce)
+
+module.exports = router

bot/src/internal/requireInternalKey.js

@@ -0,0 +1,19 @@
+// Gate for the bot's /internal/* API. The only caller is the main UOMysticmoon
+// server, over the private compose network — never expose this route through
+// the public reverse proxy. Timing-safe compare so response time can't be used
+// to brute-force the shared secret one byte at a time.
+const crypto = require('crypto')
+
+function requireInternalKey(req, res, next) {
+  const expected = process.env.BOT_INTERNAL_KEY || ''
+  const provided = req.get('X-Internal-Key') || ''
+
+  const a = Buffer.from(expected)
+  const b = Buffer.from(provided)
+  const match = expected.length > 0 && a.length === b.length && crypto.timingSafeEqual(a, b)
+
+  if (!match) return res.status(401).json({ message: 'Unauthorized' })
+  return next()
+}
+
+module.exports = requireInternalKey

bot/src/invites/inviteRotator.js

@@ -0,0 +1,37 @@
+// Shared by both /invite rotate and the weekly cron job (inviteScheduler.js)
+// so manual and automatic rotations log identically. maxAge is set to match
+// the rotation cadence as defense-in-depth: if the scheduled rotation were
+// ever to silently stop running, the invite still expires on its own instead
+// of staying live forever.
+const guildConfig = require('../model/guildConfig')
+const inviteLog = require('../model/inviteLog')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('invites')
+
+const ROTATION_MAX_AGE_SECONDS = 7 * 24 * 60 * 60 // 7 days
+
+async function rotate(client, guildId, { triggeredBy, triggeredByTag } = {}) {
+  const channelId = await guildConfig.getInviteChannelId(guildId)
+  if (!channelId) throw new Error('No invite channel configured — set one with /invite channel first.')
+
+  const channel = await client.channels.fetch(channelId)
+  if (!channel || !channel.isTextBased()) throw new Error('Configured invite channel is missing or not text-based.')
+
+  const current = await inviteLog.getCurrent(guildId)
+  if (current) {
+    try {
+      await channel.guild.invites.delete(current.invite_code, 'Invite rotation')
+    } catch (err) {
+      log.warn('failed to revoke previous invite (may already be gone)', { message: err.message })
+    }
+    await inviteLog.markRevoked(current.id)
+  }
+
+  const invite = await channel.createInvite({ maxAge: ROTATION_MAX_AGE_SECONDS, unique: true, reason: 'Invite rotation' })
+  await inviteLog.record({ guildId, channelId, inviteCode: invite.code, triggeredBy, triggeredByTag })
+  log.info('invite rotated', { code: invite.code, triggeredBy: triggeredByTag || 'automatic (scheduled)' })
+  return invite
+}
+
+module.exports = { rotate }

bot/src/invites/inviteScheduler.js

@@ -0,0 +1,31 @@
+// Weekly automatic invite rotation (Sundays at midnight). A missing invite
+// channel config just skips quietly (warn-logged) — most guilds won't set
+// this up on day one, and that shouldn't spam errors every week until they do.
+const cron = require('node-cron')
+
+const inviteRotator = require('./inviteRotator')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('invites')
+
+let task = null
+
+function start(client, guildId) {
+  task = cron.schedule('0 0 * * 0', async () => {
+    try {
+      await inviteRotator.rotate(client, guildId, {})
+    } catch (err) {
+      log.warn('scheduled invite rotation skipped', { message: err.message })
+    }
+  })
+  log.info('invite rotation scheduler started')
+}
+
+function stop() {
+  if (task) {
+    task.stop()
+    task = null
+  }
+}
+
+module.exports = { start, stop }

bot/src/model/filterAllowlist.js

@@ -0,0 +1,40 @@
+// Roles/channels that bypass word/invite/spam filtering entirely (staff roles,
+// bot-commands channels, etc.). Stored as CSV in guild_config rather than a
+// separate table — short, rarely-changed lists.
+const guildConfig = require('./guildConfig')
+
+const ROLES_KEY = 'filter_allow_roles'
+const CHANNELS_KEY = 'filter_allow_channels'
+
+function parseCsv(value) {
+  return value ? value.split(',').filter(Boolean) : []
+}
+
+async function getRoles(guildId) {
+  return parseCsv(await guildConfig.get(guildId, ROLES_KEY))
+}
+
+async function getChannels(guildId) {
+  return parseCsv(await guildConfig.get(guildId, CHANNELS_KEY))
+}
+
+// Toggle: adds the id if absent, removes it if present. Returns the new state (true = now allowed).
+async function toggleRole(guildId, roleId) {
+  const roles = await getRoles(guildId)
+  const idx = roles.indexOf(roleId)
+  if (idx === -1) roles.push(roleId)
+  else roles.splice(idx, 1)
+  await guildConfig.set(guildId, ROLES_KEY, roles.join(','))
+  return idx === -1
+}
+
+async function toggleChannel(guildId, channelId) {
+  const channels = await getChannels(guildId)
+  const idx = channels.indexOf(channelId)
+  if (idx === -1) channels.push(channelId)
+  else channels.splice(idx, 1)
+  await guildConfig.set(guildId, CHANNELS_KEY, channels.join(','))
+  return idx === -1
+}
+
+module.exports = { getRoles, getChannels, toggleRole, toggleChannel }

bot/src/model/filterHits.js

@@ -0,0 +1,15 @@
+// Automated content-filter hits (Phase 6b). Bot-owned; recorded whenever the
+// word filter or foreign-invite filter deletes a message. mod_actions still
+// records the resulting warn/mute separately. Schema: server/db/schema.sql
+// (filter_hits).
+const db = require('../db')
+
+async function record({ guildId, hitType, discordUserId, username, channelId, matched, actionTaken }) {
+  await db.query(
+    `INSERT INTO filter_hits (guild_id, hit_type, discord_user_id, username, channel_id, matched, action_taken)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [guildId, hitType, discordUserId, username || null, channelId || null, matched || null, actionTaken],
+  )
+}
+
+module.exports = { record }

bot/src/model/filterWords.js

@@ -0,0 +1,22 @@
+const db = require('../db')
+
+async function add({ guildId, word, severity, addedBy, addedByTag }) {
+  await db.query(
+    `INSERT INTO filter_words (guild_id, word, severity, added_by, added_by_tag)
+     VALUES (?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE severity = VALUES(severity), added_by = VALUES(added_by), added_by_tag = VALUES(added_by_tag)`,
+    [guildId, word.toLowerCase(), severity || 'delete', addedBy || null, addedByTag || null],
+  )
+}
+
+// Returns true if a row was actually removed.
+async function remove(guildId, word) {
+  const res = await db.query('DELETE FROM filter_words WHERE guild_id = ? AND word = ?', [guildId, word.toLowerCase()])
+  return Number(res.affectedRows || 0) > 0
+}
+
+async function list(guildId) {
+  return db.query('SELECT word, severity FROM filter_words WHERE guild_id = ? ORDER BY word ASC', [guildId])
+}
+
+module.exports = { add, remove, list }

bot/src/model/guildConfig.js

@@ -0,0 +1,47 @@
+// Per-guild key/value config the bot owns (see guild_config in
+// server/db/schema.sql). Generic get/set now; filters/schedules/role-menu
+// config reuses this same table in later phases.
+const db = require('../db')
+
+const MOD_LOG_CHANNEL_KEY = 'mod_log_channel_id'
+const AUTO_ROLE_KEY = 'auto_role_id'
+const INVITE_CHANNEL_KEY = 'invite_channel_id'
+const NEWS_CHANNEL_KEY = 'news_channel_id'
+
+async function get(guildId, key) {
+  const rows = await db.query('SELECT value FROM guild_config WHERE guild_id = ? AND `key` = ? LIMIT 1', [guildId, key])
+  return rows[0] ? rows[0].value : null
+}
+
+async function set(guildId, key, value) {
+  await db.query(
+    `INSERT INTO guild_config (guild_id, \`key\`, value) VALUES (?, ?, ?)
+     ON DUPLICATE KEY UPDATE value = VALUES(value)`,
+    [guildId, key, value],
+  )
+}
+
+const getModLogChannelId = (guildId) => get(guildId, MOD_LOG_CHANNEL_KEY)
+const setModLogChannelId = (guildId, channelId) => set(guildId, MOD_LOG_CHANNEL_KEY, channelId)
+
+const getAutoRoleId = (guildId) => get(guildId, AUTO_ROLE_KEY)
+const setAutoRoleId = (guildId, roleId) => set(guildId, AUTO_ROLE_KEY, roleId)
+
+const getInviteChannelId = (guildId) => get(guildId, INVITE_CHANNEL_KEY)
+const setInviteChannelId = (guildId, channelId) => set(guildId, INVITE_CHANNEL_KEY, channelId)
+
+const getNewsChannelId = (guildId) => get(guildId, NEWS_CHANNEL_KEY)
+const setNewsChannelId = (guildId, channelId) => set(guildId, NEWS_CHANNEL_KEY, channelId)
+
+module.exports = {
+  get,
+  set,
+  getModLogChannelId,
+  setModLogChannelId,
+  getAutoRoleId,
+  setAutoRoleId,
+  getInviteChannelId,
+  setInviteChannelId,
+  getNewsChannelId,
+  setNewsChannelId,
+}

bot/src/model/inviteLog.js

@@ -0,0 +1,29 @@
+const db = require('../db')
+
+async function record({ guildId, channelId, inviteCode, triggeredBy, triggeredByTag }) {
+  const res = await db.query(
+    `INSERT INTO invite_log (guild_id, channel_id, invite_code, triggered_by, triggered_by_tag)
+     VALUES (?, ?, ?, ?, ?)`,
+    [guildId, channelId, inviteCode, triggeredBy || null, triggeredByTag || null],
+  )
+  return res.insertId
+}
+
+// The active (not-yet-revoked) invite for a guild, if any.
+async function getCurrent(guildId) {
+  const rows = await db.query(
+    'SELECT * FROM invite_log WHERE guild_id = ? AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1',
+    [guildId],
+  )
+  return rows[0] || null
+}
+
+async function markRevoked(id) {
+  await db.query('UPDATE invite_log SET revoked_at = NOW() WHERE id = ?', [id])
+}
+
+async function list(guildId, limit = 10) {
+  return db.query('SELECT * FROM invite_log WHERE guild_id = ? ORDER BY created_at DESC LIMIT ?', [guildId, limit])
+}
+
+module.exports = { record, getCurrent, markRevoked, list }

bot/src/model/memberEvents.js

@@ -0,0 +1,14 @@
+// Guild member join/leave events (Phase 6b). Bot-owned; the site reads these for
+// the moderation dashboard's members feed + invite-usage view. Schema in
+// server/db/schema.sql (member_events).
+const db = require('../db')
+
+async function record({ guildId, eventType, discordUserId, username, inviteCode, inviterId, inviterTag }) {
+  await db.query(
+    `INSERT INTO member_events (guild_id, event_type, discord_user_id, username, invite_code, inviter_id, inviter_tag)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [guildId, eventType, discordUserId, username || null, inviteCode || null, inviterId || null, inviterTag || null],
+  )
+}
+
+module.exports = { record }

bot/src/model/roleMenus.js

@@ -0,0 +1,17 @@
+const db = require('../db')
+
+async function add({ guildId, channelId, messageId, mapping, createdBy }) {
+  await db.query(
+    `INSERT INTO role_menus (guild_id, channel_id, message_id, mapping, created_by)
+     VALUES (?, ?, ?, ?, ?)`,
+    [guildId, channelId, messageId, JSON.stringify(mapping), createdBy || null],
+  )
+}
+
+async function getByMessageId(messageId) {
+  const rows = await db.query('SELECT * FROM role_menus WHERE message_id = ? LIMIT 1', [messageId])
+  if (!rows[0]) return null
+  return { ...rows[0], mapping: JSON.parse(rows[0].mapping) }
+}
+
+module.exports = { add, getByMessageId }

bot/src/model/scheduledMessages.js

@@ -0,0 +1,57 @@
+const db = require('../db')
+
+async function addRecurring({ guildId, channelId, content, cronExpression, createdBy, createdByTag }) {
+  const res = await db.query(
+    `INSERT INTO scheduled_messages (guild_id, channel_id, content, cron_expression, created_by, created_by_tag)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [guildId, channelId, content, cronExpression, createdBy || null, createdByTag || null],
+  )
+  return res.insertId
+}
+
+async function addOnce({ guildId, channelId, content, runAt, createdBy, createdByTag }) {
+  const res = await db.query(
+    `INSERT INTO scheduled_messages (guild_id, channel_id, content, run_at, created_by, created_by_tag)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [guildId, channelId, content, runAt, createdBy || null, createdByTag || null],
+  )
+  return res.insertId
+}
+
+// Returns true if a row was actually removed (scoped to the guild so one
+// guild can't remove another's rows).
+async function remove(guildId, id) {
+  const res = await db.query('DELETE FROM scheduled_messages WHERE id = ? AND guild_id = ?', [id, guildId])
+  return Number(res.affectedRows || 0) > 0
+}
+
+async function list(guildId) {
+  return db.query(
+    `SELECT id, channel_id, content, cron_expression, run_at, enabled, sent_at FROM scheduled_messages
+     WHERE guild_id = ? ORDER BY id ASC`,
+    [guildId],
+  )
+}
+
+// All enabled recurring rows across every guild the bot serves — v1 only
+// ever has one, but the scheduler doesn't need to special-case that.
+async function listEnabledRecurring() {
+  return db.query(
+    `SELECT id, guild_id, channel_id, content, cron_expression FROM scheduled_messages
+     WHERE cron_expression IS NOT NULL AND enabled = 1`,
+  )
+}
+
+// One-off rows due to post right now.
+async function listDueOneOff() {
+  return db.query(
+    `SELECT id, guild_id, channel_id, content FROM scheduled_messages
+     WHERE run_at IS NOT NULL AND sent_at IS NULL AND enabled = 1 AND run_at <= NOW()`,
+  )
+}
+
+async function markSent(id) {
+  await db.query('UPDATE scheduled_messages SET sent_at = NOW() WHERE id = ?', [id])
+}
+
+module.exports = { addRecurring, addOnce, remove, list, listEnabledRecurring, listDueOneOff, markSent }

bot/src/model/spamHits.js

@@ -0,0 +1,14 @@
+// Automated spam-detection hits (Phase 6b). Bot-owned; recorded when the
+// rate-limit / mass-mention / mass-emoji checks trip. mod_actions still logs the
+// resulting warn separately. Schema: server/db/schema.sql (spam_hits).
+const db = require('../db')
+
+async function record({ guildId, spamType, discordUserId, username, channelId }) {
+  await db.query(
+    `INSERT INTO spam_hits (guild_id, spam_type, discord_user_id, username, channel_id)
+     VALUES (?, ?, ?, ?, ?)`,
+    [guildId, spamType, discordUserId, username || null, channelId || null],
+  )
+}
+
+module.exports = { record }

bot/src/model/tempRoles.js

@@ -0,0 +1,26 @@
+const db = require('../db')
+
+// Upsert — re-granting the same temp role refreshes its expiry instead of
+// creating a duplicate row (see UNIQUE(guild,user,role) in schema.sql).
+async function add({ guildId, userId, roleId, expiresAt, createdBy }) {
+  await db.query(
+    `INSERT INTO temp_roles (guild_id, user_id, role_id, expires_at, created_by)
+     VALUES (?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE expires_at = VALUES(expires_at), created_by = VALUES(created_by)`,
+    [guildId, userId, roleId, expiresAt, createdBy || null],
+  )
+}
+
+async function remove(guildId, userId, roleId) {
+  await db.query('DELETE FROM temp_roles WHERE guild_id = ? AND user_id = ? AND role_id = ?', [guildId, userId, roleId])
+}
+
+async function listExpired() {
+  return db.query('SELECT id, guild_id, user_id, role_id FROM temp_roles WHERE expires_at <= NOW()')
+}
+
+async function removeById(id) {
+  await db.query('DELETE FROM temp_roles WHERE id = ?', [id])
+}
+
+module.exports = { add, remove, listExpired, removeById }

bot/src/model/warnings.js

@@ -0,0 +1,26 @@
+// Standing warnings (separate from mod_actions so /warnings can list a
+// user's active warnings). expires_at is always NULL for now — decay/escalation
+// (e.g. "3 active warns -> auto-mute") is deferred past Phase 2, see
+// warn.command.js.
+const db = require('../db')
+
+async function add({ guildId, targetUserId, targetTag, staffUserId, staffTag, reason }) {
+  await db.query(
+    `INSERT INTO warnings (guild_id, target_user_id, target_tag, staff_user_id, staff_tag, reason)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [guildId, targetUserId, targetTag || null, staffUserId, staffTag || null, reason || null],
+  )
+}
+
+// Active = not expired. Every row is active today since expires_at is never
+// set, but the query is written to already respect it once decay lands.
+async function listActive(guildId, targetUserId) {
+  return db.query(
+    `SELECT id, reason, staff_tag, created_at FROM warnings
+     WHERE guild_id = ? AND target_user_id = ? AND (expires_at IS NULL OR expires_at > NOW())
+     ORDER BY created_at DESC`,
+    [guildId, targetUserId],
+  )
+}
+
+module.exports = { add, listActive }

bot/src/roles/tempRoleSweeper.js

@@ -0,0 +1,48 @@
+// Once-a-minute sweep for expired temp_roles: removes the Discord role (best
+// effort — the member/guild/role may already be gone) then deletes the row
+// regardless, so a stale row can never block future re-grants of the same
+// role to the same member.
+const cron = require('node-cron')
+
+const tempRoles = require('../model/tempRoles')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('temproles')
+
+let client = null
+let task = null
+
+async function sweep() {
+  try {
+    const expired = await tempRoles.listExpired()
+    for (const row of expired) {
+      try {
+        const guild = await client.guilds.fetch(row.guild_id)
+        const member = await guild.members.fetch(row.user_id).catch(() => null)
+        if (member) await member.roles.remove(row.role_id).catch(() => {})
+      } catch (err) {
+        log.warn('failed to remove expired temp role', { message: err.message, roleId: row.role_id, userId: row.user_id })
+      } finally {
+        await tempRoles.removeById(row.id)
+      }
+    }
+  } catch (err) {
+    log.error('temp role sweep failed', { message: err.message })
+  }
+}
+
+function start(discordClient) {
+  client = discordClient
+  task = cron.schedule('* * * * *', sweep)
+  log.info('temp role sweeper started')
+}
+
+function stop() {
+  if (task) {
+    task.stop()
+    task = null
+  }
+  client = null
+}
+
+module.exports = { start, stop }

bot/src/scheduler/scheduler.js

@@ -0,0 +1,83 @@
+// Recurring + one-off scheduled channel messages. Recurring rows are each
+// registered as their own node-cron task; one-off rows are picked up by a
+// once-a-minute sweep that checks for anything due and marks it sent so it
+// never reposts. Needs a live discord.js Client to actually send — wired up
+// by discordManager.js (start() once the client is ready, stop() alongside
+// client teardown).
+const cron = require('node-cron')
+
+const scheduledMessages = require('../model/scheduledMessages')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('scheduler')
+
+let discordClient = null
+const recurringTasks = new Map() // id -> node-cron ScheduledTask
+let sweepTask = null
+
+async function sendToChannel(channelId, content) {
+  try {
+    const channel = await discordClient.channels.fetch(channelId)
+    if (!channel || !channel.isTextBased()) {
+      log.warn('scheduled message skipped — channel missing or not text-based', { channelId })
+      return
+    }
+    await channel.send({ content })
+    log.info('sent scheduled message', { channelId })
+  } catch (err) {
+    log.warn('failed to send scheduled message', { channelId, message: err.message })
+  }
+}
+
+async function loadRecurring() {
+  for (const task of recurringTasks.values()) task.stop()
+  recurringTasks.clear()
+
+  const rows = await scheduledMessages.listEnabledRecurring()
+  for (const row of rows) {
+    if (!cron.validate(row.cron_expression)) {
+      log.warn('skipping scheduled message with invalid cron expression', { id: row.id, cron: row.cron_expression })
+      continue
+    }
+    const task = cron.schedule(row.cron_expression, () => sendToChannel(row.channel_id, row.content))
+    recurringTasks.set(row.id, task)
+  }
+  log.info('loaded recurring scheduled messages', { count: recurringTasks.size })
+}
+
+async function sweepDueOneOff() {
+  try {
+    const due = await scheduledMessages.listDueOneOff()
+    for (const row of due) {
+      await sendToChannel(row.channel_id, row.content)
+      await scheduledMessages.markSent(row.id)
+    }
+  } catch (err) {
+    log.error('one-off sweep failed', { message: err.message })
+  }
+}
+
+async function start(client) {
+  discordClient = client
+  await loadRecurring()
+  sweepTask = cron.schedule('* * * * *', sweepDueOneOff)
+  log.info('scheduler started')
+}
+
+// Called by /schedule after any add/remove so changes apply without a restart.
+async function refresh() {
+  if (!discordClient) return
+  await loadRecurring()
+}
+
+function stop() {
+  for (const task of recurringTasks.values()) task.stop()
+  recurringTasks.clear()
+  if (sweepTask) {
+    sweepTask.stop()
+    sweepTask = null
+  }
+  discordClient = null
+}
+
+module.exports = { start, stop, refresh }

bot/src/server.js

@@ -0,0 +1,52 @@
+require('dotenv').config()
+
+const app = require('./app')
+const bootstrap = require('./bootstrap')
+const createLogger = require('./utils/logger')
+const discordManager = require('./discord/discordManager')
+const pkg = require('../package.json')
+
+const log = createLogger('server')
+const PORT = Number(process.env.PORT) || 4100
+const HOST = '0.0.0.0'
+
+async function start() {
+  log.info(`starting UOMysticmoon bot v${pkg.version}`, {
+    node: process.version,
+    logFile: createLogger.logFilePath || 'disabled (console only)',
+  })
+
+  const server = app.listen(PORT, HOST, () => {
+    log.info(`internal API listening on http://${HOST}:${PORT}`)
+  })
+
+  await bootstrap()
+
+  setupShutdown(server)
+}
+
+function setupShutdown(server) {
+  let closing = false
+  const shutdown = async (signal) => {
+    if (closing) return
+    closing = true
+    log.warn(`${signal} received — shutting down gracefully`)
+    server.close(() => log.info('internal API closed'))
+    await discordManager.stop()
+    await createLogger.close()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => shutdown('SIGINT'))
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('unhandledRejection', (reason) => log.error('unhandledRejection', { reason: String(reason) }))
+  process.on('uncaughtException', (err) => {
+    log.error('uncaughtException', err)
+    process.exit(1)
+  })
+}
+
+start().catch((err) => {
+  log.error('failed to start bot', err)
+  process.exit(1)
+})

bot/src/site/siteApiClient.js

@@ -0,0 +1,42 @@
+// Read-only client for the main site's PUBLIC API (no shared secret — this is
+// the same unauthenticated data any visitor's browser can fetch). Used by
+// /wiki (search) and /announce (re-post an existing news item). Distinct from
+// botInternalClient.js, which is the shared-secret-gated server<->bot channel.
+const createLogger = require('../utils/logger')
+
+const log = createLogger('site-api')
+
+const BASE_URL = (process.env.SITE_PUBLIC_URL || 'http://localhost:3000/api/v1/public').replace(/\/+$/, '')
+const TIMEOUT_MS = 5000
+
+async function call(path) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const res = await fetch(`${BASE_URL}${path}`, { signal: controller.signal })
+    const data = await res.json().catch(() => null)
+    // Public content routes 503 with this shape while the site is in
+    // maintenance mode (see server/src/middleware/siteMode.js) — surface it
+    // distinctly so commands can show a clear message instead of a generic error.
+    if (res.status === 503 && data?.mode === 'maintenance') {
+      return { ok: false, maintenance: true, message: data.message }
+    }
+    if (!res.ok) return { ok: false, error: `site responded ${res.status}` }
+    return { ok: true, data }
+  } catch (err) {
+    log.warn('site API call failed', { path, message: err.message })
+    return { ok: false, error: err.message }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function getNewsPost(idOrSlug) {
+  return call(`/posts/news/${encodeURIComponent(idOrSlug)}`)
+}
+
+function searchWiki(query) {
+  return call(`/wiki?q=${encodeURIComponent(query)}`)
+}
+
+module.exports = { getNewsPost, searchWiki }

bot/src/utils/duration.js

@@ -0,0 +1,16 @@
+// Parses simple duration strings ("30s", "10m", "2h", "1d") to milliseconds.
+// Returns null for anything unparseable. Discord's own timeout API caps at 28
+// days — callers should clamp to MAX_TIMEOUT_MS rather than trust user input.
+const UNIT_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }
+
+const MAX_TIMEOUT_MS = 28 * 86_400_000
+
+function parseDuration(input) {
+  if (!input) return null
+  const match = /^(\d+)\s*(s|m|h|d)$/i.exec(input.trim())
+  if (!match) return null
+  const [, amount, unit] = match
+  return Number(amount) * UNIT_MS[unit.toLowerCase()]
+}
+
+module.exports = { parseDuration, MAX_TIMEOUT_MS }

bot/src/utils/logger.js

@@ -0,0 +1,97 @@
+// Dual-transport logger: writes to the console AND to a log file.
+// Levels: error | warn | info | debug.
+//   LOG_LEVEL       console verbosity   (default info)
+//   FILE_LOG_LEVEL  file verbosity      (default debug — keep a full record on disk)
+//   LOG_TO_FILE     enable file logging (default true)
+//   LOG_DIR         log directory       (default <bot>/logs)
+//   LOG_FILE        log file name       (default bot.log)
+//
+// Copied from server/src/utils/logger.js rather than shared — the bot is an
+// independently deployable process with its own package.json/Dockerfile.
+const fs = require('fs')
+const path = require('path')
+
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 }
+
+const consoleThreshold = LEVELS[(process.env.LOG_LEVEL || 'info').toLowerCase()] ?? LEVELS.info
+const fileThreshold = LEVELS[(process.env.FILE_LOG_LEVEL || 'debug').toLowerCase()] ?? LEVELS.debug
+
+// Color only on an interactive TTY — never in files or Docker logs.
+const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR == null
+const COLOR = { error: '\x1b[31m', warn: '\x1b[33m', info: '\x1b[36m', debug: '\x1b[90m' }
+const RESET = '\x1b[0m'
+
+// ── File transport ────────────────────────────────────────────────────
+const fileEnabled = (process.env.LOG_TO_FILE || 'true').toLowerCase() !== 'false'
+let fileStream = null
+let logFilePath = null
+
+if (fileEnabled) {
+  try {
+    const dir = process.env.LOG_DIR || path.join(__dirname, '..', '..', 'logs')
+    fs.mkdirSync(dir, { recursive: true })
+    logFilePath = path.join(dir, process.env.LOG_FILE || 'bot.log')
+    fileStream = fs.createWriteStream(logFilePath, { flags: 'a' })
+    fileStream.on('error', (err) => {
+      process.stderr.write(`[logger] file logging disabled: ${err.message}\n`)
+      fileStream = null
+    })
+  } catch (err) {
+    process.stderr.write(`[logger] could not open log file: ${err.message}\n`)
+    fileStream = null
+  }
+}
+
+function fmt(meta) {
+  if (meta == null) return ''
+  if (typeof meta === 'string') return meta
+  if (meta instanceof Error) return JSON.stringify({ message: meta.message, stack: meta.stack })
+  try {
+    return JSON.stringify(meta)
+  } catch {
+    return String(meta)
+  }
+}
+
+function emit(level, tag, msg, meta) {
+  const levelNum = LEVELS[level]
+  if (levelNum === undefined) return
+
+  const ts = new Date().toISOString()
+  const lvl = level.toUpperCase().padEnd(5)
+  const label = tag ? ` [${tag}]` : ''
+  const metaStr = meta === undefined ? '' : ` ${fmt(meta)}`
+  const plain = `${ts} ${lvl}${label} ${msg}${metaStr}`
+
+  // Console transport
+  if (levelNum <= consoleThreshold) {
+    const line = useColor ? `${COLOR[level] || ''}${plain}${RESET}` : plain
+    const stream = level === 'error' || level === 'warn' ? process.stderr : process.stdout
+    stream.write(`${line}\n`)
+  }
+
+  // File transport (plain text, no color)
+  if (fileStream && levelNum <= fileThreshold) {
+    fileStream.write(`${plain}\n`)
+  }
+}
+
+function createLogger(tag) {
+  return {
+    error: (msg, meta) => emit('error', tag, msg, meta),
+    warn: (msg, meta) => emit('warn', tag, msg, meta),
+    info: (msg, meta) => emit('info', tag, msg, meta),
+    debug: (msg, meta) => emit('debug', tag, msg, meta),
+  }
+}
+
+// Flush and close the file stream (called on graceful shutdown).
+createLogger.close = () =>
+  new Promise((resolve) => {
+    if (fileStream) fileStream.end(resolve)
+    else resolve()
+  })
+
+createLogger.emit = emit
+createLogger.logFilePath = logFilePath
+module.exports = createLogger

client/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>UOMysticmoon</title>
+    <meta name="description" content="UOMysticmoon — an independent private Ultima Online shard. News, screenshots, guides, and community notes." />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@500;600;700&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

client/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "uomysticmoon-client",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tiptap/extension-image": "^2.27.2",
+    "@tiptap/extension-link": "^2.27.2",
+    "@tiptap/react": "^2.27.2",
+    "@tiptap/starter-kit": "^2.27.2",
+    "diff": "^5.2.2",
+    "dompurify": "^3.4.11",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.2"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.2",
+    "vite": "^5.4.8"
+  }
+}

client/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /admin

client/src/App.jsx

@@ -0,0 +1,104 @@
+import { Routes, Route, Navigate, Outlet } from 'react-router-dom'
+import { AuthProvider } from './contexts/AuthContext.jsx'
+import { SiteProvider } from './contexts/SiteContext.jsx'
+import MaintenanceGate from './components/MaintenanceGate.jsx'
+import RequireAuth from './components/RequireAuth.jsx'
+import RoleGate from './components/RoleGate.jsx'
+
+// Public
+import Portal from './routes/public/Portal.jsx'
+import Website from './routes/public/Website.jsx'
+import News from './routes/public/News.jsx'
+import Screenshots from './routes/public/Screenshots.jsx'
+import FiveOnFriday from './routes/public/FiveOnFriday.jsx'
+import Newsletter from './routes/public/Newsletter.jsx'
+import NewsletterIssue from './routes/public/NewsletterIssue.jsx'
+import About from './routes/public/About.jsx'
+import Status from './routes/public/Status.jsx'
+import Wiki from './routes/wiki/Wiki.jsx'
+import WikiArticle from './routes/wiki/WikiArticle.jsx'
+
+// Admin
+import AdminLogin from './routes/admin/AdminLogin.jsx'
+import AdminLayout from './routes/admin/AdminLayout.jsx'
+import Dashboard from './routes/admin/views/Dashboard.jsx'
+import PostsAdmin from './routes/admin/views/PostsAdmin.jsx'
+import WikiAdmin from './routes/admin/views/WikiAdmin.jsx'
+import HeroEditor from './routes/admin/views/HeroEditor.jsx'
+import SettingsAdmin from './routes/admin/views/SettingsAdmin.jsx'
+import ActivityAdmin from './routes/admin/views/ActivityAdmin.jsx'
+import BotActivityAdmin from './routes/admin/views/BotActivityAdmin.jsx'
+import DiscordBotAdmin from './routes/admin/views/DiscordBotAdmin.jsx'
+import AuthProvidersAdmin from './routes/admin/views/AuthProvidersAdmin.jsx'
+import UsersAdmin from './routes/admin/views/UsersAdmin.jsx'
+import AccountAdmin from './routes/admin/views/AccountAdmin.jsx'
+import Moderation from './routes/admin/views/Moderation.jsx'
+import ModerationUser from './routes/admin/views/ModerationUser.jsx'
+
+export default function App() {
+  return (
+    <AuthProvider>
+      <SiteProvider>
+        <Routes>
+          {/* Public site — gated by maintenance mode (admins preview through it) */}
+          <Route
+            element={
+              <MaintenanceGate>
+                <Outlet />
+              </MaintenanceGate>
+            }
+          >
+            <Route path="/" element={<Portal />} />
+            <Route path="/site" element={<Website />} />
+            <Route path="/site/news" element={<News />} />
+            <Route path="/site/screenshots" element={<Screenshots />} />
+            <Route path="/site/five-on-friday" element={<FiveOnFriday />} />
+            <Route path="/site/newsletter" element={<Newsletter />} />
+            <Route path="/site/newsletter/:id" element={<NewsletterIssue />} />
+            <Route path="/site/about" element={<About />} />
+            <Route path="/site/status" element={<Status />} />
+            <Route path="/wiki" element={<Wiki />} />
+            <Route path="/wiki/:slug" element={<WikiArticle />} />
+          </Route>
+
+          {/* Admin */}
+          <Route path="/admin/login" element={<AdminLogin />} />
+          <Route
+            path="/admin"
+            element={
+              <RequireAuth>
+                <AdminLayout />
+              </RequireAuth>
+            }
+          >
+            <Route index element={<Dashboard />} />
+            <Route path="posts" element={<PostsAdmin />} />
+            <Route path="wiki" element={<WikiAdmin />} />
+            <Route path="hero" element={<HeroEditor />} />
+            <Route path="settings" element={<SettingsAdmin />} />
+            <Route
+              path="moderation"
+              element={
+                <RoleGate roles={['admin', 'moderator']}>
+                  <Outlet />
+                </RoleGate>
+              }
+            >
+              <Route index element={<Moderation />} />
+              <Route path="user/:discordId" element={<ModerationUser />} />
+            </Route>
+            <Route path="activity" element={<ActivityAdmin />} />
+            <Route path="bot-activity" element={<BotActivityAdmin />} />
+            <Route path="discord-bot" element={<DiscordBotAdmin />} />
+            <Route path="auth-providers" element={<AuthProvidersAdmin />} />
+            <Route path="users" element={<UsersAdmin />} />
+            <Route path="account" element={<AccountAdmin />} />
+            <Route path="*" element={<Navigate to="/admin" replace />} />
+          </Route>
+
+          <Route path="*" element={<Navigate to="/" replace />} />
+        </Routes>
+      </SiteProvider>
+    </AuthProvider>
+  )
+}

client/src/api/client.js

@@ -0,0 +1,191 @@
+// Thin fetch wrapper. Always sends cookies (httpOnly JWT) and talks to the
+// same-origin API (/api/v1) — proxied to the Express server in dev.
+const BASE = '/api/v1'
+
+class ApiError extends Error {
+  constructor(status, message, body) {
+    super(message)
+    this.status = status
+    this.body = body
+  }
+}
+
+async function req(path, { method = 'GET', body, headers, raw } = {}) {
+  const opts = { method, credentials: 'include', headers: { ...headers } }
+  if (body !== undefined) {
+    if (raw) {
+      opts.body = body // FormData — let the browser set the content-type
+    } else {
+      opts.headers['Content-Type'] = 'application/json'
+      opts.body = JSON.stringify(body)
+    }
+  }
+  const res = await fetch(BASE + path, opts)
+  const text = await res.text()
+  const data = text ? safeParse(text) : null
+  if (!res.ok) {
+    const message = (data && data.message) || res.statusText || 'Request failed'
+    throw new ApiError(res.status, message, data)
+  }
+  return data
+}
+
+function safeParse(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+export const api = {
+  // ----- auth -----
+  me: () => req('/auth/me'),
+  // `extra` carries the honeypot field (and any future login fields).
+  login: (username, password, extra = {}) =>
+    req('/auth/login', { method: 'POST', body: { username, password, ...extra } }),
+  loginTotp: (challenge, code) =>
+    req('/auth/login/totp', { method: 'POST', body: { challenge, code } }),
+  // Second factor for an SSO login (challenge is held in an httpOnly cookie set by
+  // the callback, so only the code is sent). Returns { user, returnTo }.
+  ssoLoginTotp: (code) => req('/auth/sso/totp', { method: 'POST', body: { code } }),
+  logout: () => req('/auth/logout', { method: 'POST' }),
+  // Public SSO provider discovery — drives the login-page provider buttons.
+  authProviders: () => req('/auth/providers'),
+
+  // ----- public -----
+  publicSettings: () => req('/public/settings'),
+  status: () => req('/public/status'),
+  posts: (category) => req(`/public/posts/${category}`),
+  post: (category, idOrSlug) => req(`/public/posts/${category}/${idOrSlug}`),
+  wiki: (opts = {}) => {
+    const qs = new URLSearchParams()
+    if (opts.category) qs.set('category', opts.category)
+    if (opts.tag) qs.set('tag', opts.tag)
+    if (opts.q) qs.set('q', opts.q)
+    const s = qs.toString()
+    return req(`/public/wiki${s ? `?${s}` : ''}`)
+  },
+  wikiCategories: () => req('/public/wiki/categories'),
+  wikiTags: () => req('/public/wiki/tags'),
+  wikiPage: (slug) => req(`/public/wiki/${slug}`),
+  contact: (payload) => req('/public/contact', { method: 'POST', body: payload }),
+
+  // ----- admin -----
+  admin: {
+    dashboard: () => req('/admin/dashboard'),
+    setSiteMode: (mode) => req('/admin/site-mode', { method: 'PUT', body: { mode } }),
+    listPosts: (category) => req(`/admin/posts${category ? `?category=${category}` : ''}`),
+    getPost: (id) => req(`/admin/posts/${id}`),
+    createPost: (data) => req('/admin/posts', { method: 'POST', body: data }),
+    updatePost: (id, data) => req(`/admin/posts/${id}`, { method: 'PUT', body: data }),
+    deletePost: (id) => req(`/admin/posts/${id}`, { method: 'DELETE' }),
+    publishPost: (id, published) =>
+      req(`/admin/posts/${id}/publish`, { method: 'PATCH', body: { published } }),
+    uploadImage: (file) => {
+      const fd = new FormData()
+      fd.append('image', file)
+      return req('/admin/posts/upload', { method: 'POST', body: fd, raw: true })
+    },
+    // Generalized upload for rich-text editors → { url }.
+    upload: (file) => {
+      const fd = new FormData()
+      fd.append('image', file)
+      return req('/admin/uploads', { method: 'POST', body: fd, raw: true })
+    },
+    listWiki: (params = '') => req(`/admin/wiki${params}`),
+    getWiki: (slug) => req(`/admin/wiki/${slug}`),
+    createWiki: (data) => req('/admin/wiki', { method: 'POST', body: data }),
+    updateWiki: (slug, data) => req(`/admin/wiki/${slug}`, { method: 'PUT', body: data }),
+    publishWiki: (slug, published) =>
+      req(`/admin/wiki/${slug}/publish`, { method: 'PATCH', body: { published } }),
+    deleteWiki: (slug) => req(`/admin/wiki/${slug}`, { method: 'DELETE' }),
+    listWikiRevisions: (slug) => req(`/admin/wiki/${slug}/revisions`),
+    getWikiRevision: (slug, id) => req(`/admin/wiki/${slug}/revisions/${id}`),
+    restoreWikiRevision: (slug, id) =>
+      req(`/admin/wiki/${slug}/revisions/${id}/restore`, { method: 'POST' }),
+    listWikiTags: () => req('/admin/wiki/tags'),
+    listWikiCategories: () => req('/admin/wiki/categories'),
+    createWikiCategory: (data) => req('/admin/wiki/categories', { method: 'POST', body: data }),
+    updateWikiCategory: (id, data) =>
+      req(`/admin/wiki/categories/${id}`, { method: 'PUT', body: data }),
+    deleteWikiCategory: (id) => req(`/admin/wiki/categories/${id}`, { method: 'DELETE' }),
+    getSettings: () => req('/admin/settings'),
+    updateSettings: (obj) => req('/admin/settings', { method: 'PUT', body: obj }),
+    activity: (limit = 50) => req(`/admin/activity?limit=${limit}`),
+    botActivity: () => req('/admin/bot-activity'),
+    unbanIp: (ip) => req('/admin/bot-activity/unban', { method: 'POST', body: { ip } }),
+    listUsers: () => req('/admin/users'),
+    createUser: (data) => req('/admin/users', { method: 'POST', body: data }),
+    updateUser: (id, data) => req(`/admin/users/${id}`, { method: 'PUT', body: data }),
+    deleteUser: (id) => req(`/admin/users/${id}`, { method: 'DELETE' }),
+
+    // ----- moderation dashboard (admin + moderator) -----
+    modSummary: () => req('/admin/moderation/stats/summary'),
+    modRecent: (params = {}) => {
+      const qs = new URLSearchParams()
+      if (params.type) qs.set('type', params.type)
+      if (params.limit) qs.set('limit', params.limit)
+      if (params.offset) qs.set('offset', params.offset)
+      const s = qs.toString()
+      return req(`/admin/moderation/recent${s ? `?${s}` : ''}`)
+    },
+    modSearch: (q) => req(`/admin/moderation/search?q=${encodeURIComponent(q)}`),
+    modMembers: (params = {}) => {
+      const qs = new URLSearchParams()
+      if (params.type) qs.set('type', params.type)
+      if (params.limit) qs.set('limit', params.limit)
+      if (params.offset) qs.set('offset', params.offset)
+      const s = qs.toString()
+      return req(`/admin/moderation/members${s ? `?${s}` : ''}`)
+    },
+    modFilterHits: (params = {}) => {
+      const qs = new URLSearchParams()
+      if (params.limit) qs.set('limit', params.limit)
+      if (params.offset) qs.set('offset', params.offset)
+      const s = qs.toString()
+      return req(`/admin/moderation/filter-hits${s ? `?${s}` : ''}`)
+    },
+    modSpamHits: (params = {}) => {
+      const qs = new URLSearchParams()
+      if (params.limit) qs.set('limit', params.limit)
+      if (params.offset) qs.set('offset', params.offset)
+      const s = qs.toString()
+      return req(`/admin/moderation/spam-hits${s ? `?${s}` : ''}`)
+    },
+    modUser: (discordId) => req(`/admin/moderation/user/${discordId}`),
+    modUserActions: (discordId, params = {}) => {
+      const qs = new URLSearchParams()
+      if (params.type) qs.set('type', params.type)
+      if (params.limit) qs.set('limit', params.limit)
+      if (params.offset) qs.set('offset', params.offset)
+      const s = qs.toString()
+      return req(`/admin/moderation/user/${discordId}/actions${s ? `?${s}` : ''}`)
+    },
+    modUserNotes: (discordId) => req(`/admin/moderation/user/${discordId}/notes`),
+    addModNote: (discordId, data) =>
+      req(`/admin/moderation/user/${discordId}/notes`, { method: 'POST', body: data }),
+
+    // ----- account security (self-service 2FA) -----
+    getAccount: () => req('/admin/account'),
+    totpSetup: () => req('/admin/account/totp/setup', { method: 'POST' }),
+    totpEnable: (code) => req('/admin/account/totp/enable', { method: 'POST', body: { code } }),
+    totpDisable: (code) => req('/admin/account/totp/disable', { method: 'POST', body: { code } }),
+
+    // ----- linked SSO identities (self-service) -----
+    linkedIdentities: () => req('/admin/account/identities'),
+    unlinkIdentity: (provider) => req(`/admin/account/identities/${provider}`, { method: 'DELETE' }),
+
+    // ----- auth providers / SSO config (admin only) -----
+    listAuthProviders: () => req('/admin/auth/providers'),
+    createAuthProvider: (data) => req('/admin/auth/providers', { method: 'POST', body: data }),
+    updateAuthProvider: (id, data) => req(`/admin/auth/providers/${id}`, { method: 'PUT', body: data }),
+    deleteAuthProvider: (id) => req(`/admin/auth/providers/${id}`, { method: 'DELETE' }),
+
+    // ----- Discord bot control (admin only) -----
+    getDiscordBotConfig: () => req('/admin/discord-bot/config'),
+    saveDiscordBotConfig: (data) => req('/admin/discord-bot/config', { method: 'PUT', body: data }),
+  },
+}
+
+export { ApiError }

client/src/components/HeroElement.jsx

@@ -0,0 +1,182 @@
+import { Link } from 'react-router-dom'
+
+const MOON_IMAGE = '/assets/img/hero-moon.png'
+
+// Font family tokens a line may opt into; default is the page serif.
+const FONT = { display: 'var(--display)', sans: 'var(--sans)' }
+
+// fontSize may be a number (px, from the editor) or a CSS string (e.g. a clamp()
+// used by the pre-populated default so the hero stays responsive until edited).
+function sizeToCss(v) {
+  return typeof v === 'number' ? `${v}px` : v
+}
+
+function lineStyle(line) {
+  return {
+    display: 'block', // each line stacks (so a span line behaves like the others)
+    margin: line.marginTop != null ? `${line.marginTop}px 0 0` : '0',
+    fontFamily: FONT[line.font] || undefined,
+    fontSize: sizeToCss(line.fontSize),
+    color: line.color || 'inherit',
+    fontWeight: line.weight || undefined,
+    fontStyle: line.italic ? 'italic' : undefined,
+    letterSpacing: line.letterSpacing || undefined,
+    textTransform: line.transform || undefined,
+    lineHeight: line.lineHeight || undefined,
+    maxWidth: line.maxWidth ? `${line.maxWidth}px` : undefined,
+    marginLeft: line.maxWidth ? 'auto' : undefined,
+    marginRight: line.maxWidth ? 'auto' : undefined,
+  }
+}
+
+function TextBlock({ props }) {
+  const align = props.align || 'center'
+  return (
+    <div style={{ textAlign: align, textShadow: '0 2px 22px rgba(0,0,0,0.82)' }}>
+      {(props.lines || []).map((line, i) => {
+        const Tag = /^(h1|h2|h3|p|span)$/.test(line.tag) ? line.tag : 'p'
+        return (
+          <Tag key={i} style={lineStyle(line)}>
+            {line.text}
+          </Tag>
+        )
+      })}
+    </div>
+  )
+}
+
+function Buttons({ props }) {
+  const justify = props.align === 'left' ? 'flex-start' : props.align === 'right' ? 'flex-end' : 'center'
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: props.gap ?? 12, justifyContent: justify }}>
+      {(props.items || []).map((b, i) => (
+        <Link key={i} to={b.to || '#'} className={`btn ${b.variant === 'ghost' ? 'btn-ghost' : 'btn-primary'}`}>
+          {b.label}
+        </Link>
+      ))}
+    </div>
+  )
+}
+
+function Badge({ props }) {
+  return (
+    <span
+      className="sans"
+      style={{
+        display: 'inline-block',
+        padding: '6px 14px',
+        background: props.bgColor || 'rgba(11,22,48,0.6)',
+        color: props.textColor || '#c2d2e6',
+        borderRadius: props.borderRadius ?? 999,
+        fontSize: '0.74rem',
+        fontWeight: 700,
+        letterSpacing: '0.18em',
+        textTransform: 'uppercase',
+      }}
+    >
+      {props.text}
+    </span>
+  )
+}
+
+function HeroImage({ props }) {
+  if (!props.src) {
+    // Editor placeholder until an image is chosen (a srcless image never ships live).
+    return (
+      <div
+        className="sans"
+        style={{ width: 160, height: 100, display: 'grid', placeItems: 'center', border: '1px dashed var(--accent)', borderRadius: 8, color: 'var(--muted)', fontSize: '0.8rem', background: 'rgba(11,22,48,0.4)' }}
+      >
+        Upload an image
+      </div>
+    )
+  }
+  return (
+    <img
+      src={props.src}
+      alt={props.alt || ''}
+      style={{ width: `${props.width || 40}%`, height: 'auto', display: 'block', borderRadius: 8 }}
+    />
+  )
+}
+
+function content(element) {
+  switch (element.type) {
+    case 'text_block':
+      return <TextBlock props={element.props || {}} />
+    case 'buttons':
+      return <Buttons props={element.props || {}} />
+    case 'moon': {
+      const props = element.props || {}
+      const size = props.size || 96
+      const glow = props.glow ?? 0.45
+      // Image source is configurable; old layouts with no src fall back to the
+      // default hero moon so they render exactly as before. Size/glow unchanged.
+      return (
+        <img
+          src={props.src || MOON_IMAGE}
+          alt={props.alt || ''}
+          draggable={false}
+          style={{
+            width: size,
+            height: 'auto',
+            display: 'block',
+            filter: glow ? `drop-shadow(0 0 ${size * 0.45}px rgba(216,226,239,${glow}))` : undefined,
+          }}
+        />
+      )
+    }
+    case 'badge':
+      return <Badge props={element.props || {}} />
+    case 'image':
+      return <HeroImage props={element.props || {}} />
+    default:
+      return null
+  }
+}
+
+// Absolute-positioned wrapper + type-specific content. In `editor` mode the inner
+// content is made non-interactive (so clicks select/drag the wrapper) and the
+// wrapper takes selection styling + an onPointerDown handler.
+export default function HeroElement({
+  element,
+  wrapperStyle,
+  editor = false,
+  selected = false,
+  onPointerDown,
+  children,
+}) {
+  const anchor = element.anchor || 'center'
+  const transform =
+    anchor === 'center'
+      ? 'translate(-50%, -50%)'
+      : anchor === 'top-right'
+        ? 'translateX(-100%)'
+        : undefined
+  // text_block/buttons may set a box width (px); kept within the containing block
+  // (the hero section live, or the editor canvas) with small side gutters.
+  const boxWidth =
+    (element.type === 'text_block' || element.type === 'buttons') && element.props?.width
+      ? `min(${element.props.width}px, calc(100% - 36px))`
+      : undefined
+  const cls = [editor ? 'hero-el-editable' : '', selected ? 'is-selected' : ''].filter(Boolean).join(' ')
+  return (
+    <div
+      className={cls || undefined}
+      onPointerDown={onPointerDown}
+      style={{
+        position: 'absolute',
+        left: `${element.x}%`,
+        top: `${element.y}%`,
+        zIndex: element.z || 0,
+        transform,
+        width: boxWidth,
+        cursor: editor ? 'move' : undefined,
+        ...wrapperStyle,
+      }}
+    >
+      <div style={editor ? { pointerEvents: 'none' } : undefined}>{content(element)}</div>
+      {children}
+    </div>
+  )
+}

client/src/components/MaintenanceGate.jsx

@@ -0,0 +1,22 @@
+import { useAuth } from '../contexts/AuthContext.jsx'
+import { useSite } from '../contexts/SiteContext.jsx'
+import Maintenance from '../routes/public/Maintenance.jsx'
+
+// Wraps the public site. When the shard is in maintenance, visitors see the
+// coming-soon page; a logged-in admin sees the real site (live preview).
+export default function MaintenanceGate({ children }) {
+  const { mode, loading } = useSite()
+  const { user, loading: authLoading } = useAuth()
+
+  if (loading || authLoading) {
+    return (
+      <div style={{ minHeight: '100vh', display: 'grid', placeItems: 'center', background: 'var(--bg-deep)' }}>
+        <span className="spin" />
+      </div>
+    )
+  }
+  if (mode === 'maintenance' && !user) {
+    return <Maintenance />
+  }
+  return children
+}

client/src/components/Modal.jsx

@@ -0,0 +1,70 @@
+import { useEffect } from 'react'
+
+// Simple centered modal used by the admin editors.
+export default function Modal({ title, onClose, children, footer, width = 560 }) {
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  return (
+    <div
+      onMouseDown={onClose}
+      style={{
+        position: 'fixed',
+        inset: 0,
+        background: 'rgba(6,9,13,0.66)',
+        backdropFilter: 'blur(3px)',
+        display: 'grid',
+        placeItems: 'center',
+        padding: 18,
+        zIndex: 100,
+      }}
+    >
+      <div
+        onMouseDown={(e) => e.stopPropagation()}
+        className="panel"
+        style={{ width: '100%', maxWidth: width, maxHeight: '90vh', display: 'flex', flexDirection: 'column' }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            padding: '18px 22px',
+            borderBottom: '1px solid var(--line-soft)',
+          }}
+        >
+          <h2 className="display" style={{ margin: 0, fontSize: '1.2rem', color: 'var(--head)' }}>
+            {title}
+          </h2>
+          <button
+            onClick={onClose}
+            className="sans"
+            style={{ border: 'none', background: 'transparent', color: 'var(--muted)', fontSize: '1.4rem', cursor: 'pointer', lineHeight: 1 }}
+            aria-label="Close"
+          >
+            ×
+          </button>
+        </div>
+        <div style={{ padding: 22, overflow: 'auto' }}>{children}</div>
+        {footer && (
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'flex-end',
+              gap: 10,
+              padding: '16px 22px',
+              borderTop: '1px solid var(--line-soft)',
+            }}
+          >
+            {footer}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

client/src/components/MoonDot.jsx

@@ -0,0 +1,8 @@
+// The little glowing moon used in the logo, login, maintenance screens, and the
+// hero canvas. `color` overrides the radial-gradient start point (else the CSS
+// .moon default is used).
+export default function MoonDot({ size = 13, glow = 0.45, color }) {
+  const style = { width: size, height: size, boxShadow: `0 0 ${size * 0.8}px rgba(216,226,239,${glow})` }
+  if (color) style.background = `radial-gradient(circle at 35% 30%, ${color}, #9fb0c6 55%, #5d6e88)`
+  return <span className="moon" style={style} />
+}

client/src/components/PageHeader.jsx

@@ -0,0 +1,14 @@
+// The eyebrow + title + lead block at the top of most pages.
+export default function PageHeader({ eyebrow, title, lead, center = false }) {
+  return (
+    <section style={{ marginBottom: 40, textAlign: center ? 'center' : 'left' }}>
+      {eyebrow && <p className="eyebrow">{eyebrow}</p>}
+      <h1 className="h1">{title}</h1>
+      {lead && (
+        <p className="lead" style={{ maxWidth: 680, marginLeft: center ? 'auto' : undefined, marginRight: center ? 'auto' : undefined }}>
+          {lead}
+        </p>
+      )}
+    </section>
+  )
+}

client/src/components/PageState.jsx

@@ -0,0 +1,27 @@
+// Consistent loading / error / empty states for data-driven sections.
+export function Loading({ label = 'Loading…' }) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12, color: 'var(--muted)', padding: '24px 0' }}>
+      <span className="spin" /> {label}
+    </div>
+  )
+}
+
+export function ErrorState({ message = 'Something went wrong.' }) {
+  return (
+    <div className="note" style={{ borderLeftColor: '#b4665f' }}>
+      {message}
+    </div>
+  )
+}
+
+export function EmptyState({ children }) {
+  return (
+    <div
+      className="panel"
+      style={{ padding: '28px', color: 'var(--muted)', textAlign: 'center', fontFamily: 'var(--sans)', fontSize: '0.95rem' }}
+    >
+      {children}
+    </div>
+  )
+}

client/src/components/ProviderIcon.jsx

@@ -0,0 +1,37 @@
+// Inline SVG brand icons for SSO providers. No binary assets — these scale
+// crisply at any size and keep their own brand colors. `icon` matches the
+// provider `kind` from the discovery endpoint ('google' | 'discord' | oidc/oauth2).
+// Anything unknown falls back to a neutral key glyph in the current text color.
+
+function GoogleMark({ size }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 48 48" aria-hidden="true" focusable="false">
+      <path fill="#EA4335" d="M24 9.5c3.54 0 6.71 1.22 9.21 3.6l6.85-6.85C35.9 2.38 30.47 0 24 0 14.62 0 6.51 5.38 2.56 13.22l7.98 6.19C12.43 13.72 17.74 9.5 24 9.5z" />
+      <path fill="#4285F4" d="M46.98 24.55c0-1.57-.15-3.09-.38-4.55H24v9.02h12.94c-.58 2.96-2.26 5.48-4.78 7.18l7.73 6c4.51-4.18 7.09-10.36 7.09-17.65z" />
+      <path fill="#FBBC05" d="M10.53 28.59c-.48-1.45-.76-2.99-.76-4.59s.27-3.14.76-4.59l-7.98-6.19C.92 16.46 0 20.12 0 24c0 3.88.92 7.54 2.56 10.78l7.97-6.19z" />
+      <path fill="#34A853" d="M24 48c6.48 0 11.93-2.13 15.89-5.81l-7.73-6c-2.15 1.45-4.92 2.3-8.16 2.3-6.26 0-11.57-4.22-13.47-9.91l-7.98 6.19C6.51 42.62 14.62 48 24 48z" />
+    </svg>
+  )
+}
+
+function DiscordMark({ size }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="#5865F2" aria-hidden="true" focusable="false">
+      <path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z" />
+    </svg>
+  )
+}
+
+function GenericMark({ size }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
+      <path d="M21 2l-2 2m-7.61 7.61a5.5 5.5 0 1 1-7.778 7.778 5.5 5.5 0 0 1 7.777-7.777zm0 0L15.5 7.5m0 0l3 3L22 7l-3-3m-3.5 3.5L19 4" />
+    </svg>
+  )
+}
+
+export default function ProviderIcon({ icon, size = 18 }) {
+  if (icon === 'google') return <GoogleMark size={size} />
+  if (icon === 'discord') return <DiscordMark size={size} />
+  return <GenericMark size={size} />
+}

client/src/components/PublicLayout.jsx

@@ -0,0 +1,13 @@
+import SiteHeader from './SiteHeader.jsx'
+import SiteFooter from './SiteFooter.jsx'
+
+// Standard page chrome for the public site + wiki.
+export default function PublicLayout({ section = 'website', header = true, children }) {
+  return (
+    <div className="page">
+      {header && <SiteHeader section={section} />}
+      {children}
+      <SiteFooter />
+    </div>
+  )
+}

client/src/components/RequireAuth.jsx

@@ -0,0 +1,20 @@
+import { Navigate, useLocation } from 'react-router-dom'
+import { useAuth } from '../contexts/AuthContext.jsx'
+
+// Gate for /admin/* — redirects to the login screen when not authenticated.
+export default function RequireAuth({ children }) {
+  const { user, loading } = useAuth()
+  const location = useLocation()
+
+  if (loading) {
+    return (
+      <div style={{ minHeight: '100vh', display: 'grid', placeItems: 'center', background: 'var(--bg-deep)' }}>
+        <span className="spin" />
+      </div>
+    )
+  }
+  if (!user) {
+    return <Navigate to="/admin/login" state={{ from: location }} replace />
+  }
+  return children
+}

client/src/components/RichTextEditor.jsx

@@ -0,0 +1,186 @@
+import { useEffect, useRef, useState } from 'react'
+import { useEditor, EditorContent } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Link from '@tiptap/extension-link'
+import Image from '@tiptap/extension-image'
+import { api } from '../api/client.js'
+
+// Toolbar button.
+function Btn({ onClick, active, disabled, title, children }) {
+  return (
+    <button
+      type="button"
+      title={title}
+      onMouseDown={(e) => e.preventDefault()} // keep editor selection
+      onClick={onClick}
+      disabled={disabled}
+      className={`rte-btn${active ? ' is-active' : ''}`}
+    >
+      {children}
+    </button>
+  )
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
+}
+
+// Toolbar variants:
+//   'full'    — every control, incl. the internal wiki-page link picker (wiki use).
+//   'post'    — full minus the wiki-page picker (no page-list context in posts).
+//   'minimal' — image upload only; text formatting stripped (Screenshots captions).
+export default function RichTextEditor({ value, onChange, pages = [], variant = 'full' }) {
+  const showText = variant !== 'minimal' // bold/italic/strike, headings, lists, quotes, links
+  const showWikiLink = variant === 'full' && pages.length > 0
+  const fileRef = useRef(null)
+  const [uploading, setUploading] = useState(false)
+  const [linkMenu, setLinkMenu] = useState(false)
+  const [linkFilter, setLinkFilter] = useState('')
+
+  const editor = useEditor({
+    extensions: [
+      StarterKit.configure({ heading: { levels: [2, 3] } }),
+      Link.configure({ openOnClick: false, autolink: true }),
+      Image.configure({ inline: false }),
+    ],
+    content: value || '',
+    onUpdate: ({ editor }) => onChange(editor.getHTML()),
+  })
+
+  // Safety net: sync if the parent resets `value` externally (won't fire during
+  // normal typing because the parent value equals what the editor just emitted).
+  useEffect(() => {
+    if (!editor) return
+    if (value != null && value !== editor.getHTML()) {
+      editor.commands.setContent(value, false)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, editor])
+
+  if (!editor) return null
+
+  function setLink() {
+    const prev = editor.getAttributes('link').href || ''
+    const url = window.prompt('Link URL (leave blank to remove)', prev)
+    if (url === null) return
+    if (url === '') return editor.chain().focus().extendMarkRange('link').unsetLink().run()
+    editor.chain().focus().extendMarkRange('link').setLink({ href: url }).run()
+  }
+
+  function insertInternalLink(page) {
+    const { from, to } = editor.state.selection
+    if (from === to) {
+      editor.chain().focus().insertContent(`<a href="/wiki/${page.slug}">${escapeHtml(page.title)}</a> `).run()
+    } else {
+      editor.chain().focus().extendMarkRange('link').setLink({ href: `/wiki/${page.slug}` }).run()
+    }
+    setLinkMenu(false)
+    setLinkFilter('')
+  }
+
+  async function onPickImage(e) {
+    const file = e.target.files?.[0]
+    e.target.value = '' // allow re-selecting the same file
+    if (!file) return
+    setUploading(true)
+    try {
+      const { url } = await api.admin.upload(file)
+      editor.chain().focus().setImage({ src: url, alt: file.name }).run()
+    } catch (err) {
+      alert(err.message || 'Image upload failed.')
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  return (
+    <div className="rte">
+      <div className="rte-toolbar">
+        {showText && (
+          <>
+            <Btn title="Bold" active={editor.isActive('bold')} onClick={() => editor.chain().focus().toggleBold().run()}>
+              <b>B</b>
+            </Btn>
+            <Btn title="Italic" active={editor.isActive('italic')} onClick={() => editor.chain().focus().toggleItalic().run()}>
+              <i>I</i>
+            </Btn>
+            <Btn title="Strikethrough" active={editor.isActive('strike')} onClick={() => editor.chain().focus().toggleStrike().run()}>
+              <s>S</s>
+            </Btn>
+            <span className="rte-sep" />
+            <Btn title="Heading 2 (table of contents)" active={editor.isActive('heading', { level: 2 })} onClick={() => editor.chain().focus().toggleHeading({ level: 2 }).run()}>
+              H2
+            </Btn>
+            <Btn title="Heading 3" active={editor.isActive('heading', { level: 3 })} onClick={() => editor.chain().focus().toggleHeading({ level: 3 }).run()}>
+              H3
+            </Btn>
+            <span className="rte-sep" />
+            <Btn title="Bullet list" active={editor.isActive('bulletList')} onClick={() => editor.chain().focus().toggleBulletList().run()}>
+              • List
+            </Btn>
+            <Btn title="Numbered list" active={editor.isActive('orderedList')} onClick={() => editor.chain().focus().toggleOrderedList().run()}>
+              1. List
+            </Btn>
+            <Btn title="Quote" active={editor.isActive('blockquote')} onClick={() => editor.chain().focus().toggleBlockquote().run()}>
+              ❝
+            </Btn>
+            <Btn title="Code block" active={editor.isActive('codeBlock')} onClick={() => editor.chain().focus().toggleCodeBlock().run()}>
+              {'</>'}
+            </Btn>
+            <Btn title="Divider" onClick={() => editor.chain().focus().setHorizontalRule().run()}>
+              —
+            </Btn>
+            <span className="rte-sep" />
+            <Btn title="Link" active={editor.isActive('link')} onClick={setLink}>
+              🔗
+            </Btn>
+            {showWikiLink && (
+              <Btn title="Link to another wiki page" onClick={() => setLinkMenu((v) => !v)}>
+                📄
+              </Btn>
+            )}
+          </>
+        )}
+        <Btn title="Insert image" disabled={uploading} onClick={() => fileRef.current?.click()}>
+          {uploading ? '…' : '🖼'}
+        </Btn>
+        <span className="rte-sep" />
+        <Btn title="Undo" disabled={!editor.can().undo()} onClick={() => editor.chain().focus().undo().run()}>
+          ↶
+        </Btn>
+        <Btn title="Redo" disabled={!editor.can().redo()} onClick={() => editor.chain().focus().redo().run()}>
+          ↷
+        </Btn>
+      </div>
+
+      {linkMenu && (
+        <div className="rte-linkmenu">
+          <input
+            autoFocus
+            className="input"
+            placeholder="Filter pages…"
+            value={linkFilter}
+            onChange={(e) => setLinkFilter(e.target.value)}
+          />
+          <div className="rte-linkmenu-list">
+            {pages
+              .filter((p) => {
+                const q = linkFilter.trim().toLowerCase()
+                return !q || p.title.toLowerCase().includes(q) || p.slug.includes(q)
+              })
+              .slice(0, 30)
+              .map((p) => (
+                <button key={p.slug} type="button" className="rte-linkmenu-item" onClick={() => insertInternalLink(p)}>
+                  <span>{p.title}</span>
+                  <span className="rte-linkmenu-slug">/{p.slug}</span>
+                </button>
+              ))}
+          </div>
+        </div>
+      )}
+
+      <EditorContent editor={editor} className="rte-content prose" />
+      <input ref={fileRef} type="file" accept="image/*" onChange={onPickImage} hidden />
+    </div>
+  )
+}

client/src/components/RoleGate.jsx

@@ -0,0 +1,11 @@
+import { Navigate } from 'react-router-dom'
+import { useAuth } from '../contexts/AuthContext.jsx'
+
+// Client-side role gate for admin sub-sections. Real enforcement is server-side
+// (requireRole); this just keeps the UI honest — a user without one of `roles`
+// is redirected rather than shown a page that will only 403 on every call.
+export default function RoleGate({ roles, children, redirect = '/admin' }) {
+  const { user } = useAuth()
+  if (user && !roles.includes(user.role)) return <Navigate to={redirect} replace />
+  return children
+}

client/src/components/SiteFooter.jsx

@@ -0,0 +1,36 @@
+import { Link } from 'react-router-dom'
+import { useSite } from '../contexts/SiteContext.jsx'
+
+export default function SiteFooter() {
+  const { contactEmail } = useSite()
+  return (
+    <footer
+      className="sans"
+      style={{
+        borderTop: '1px solid var(--line)',
+        padding: '28px 16px',
+        color: 'var(--muted)',
+        textAlign: 'center',
+        fontSize: '0.9rem',
+        background: 'rgba(9,13,18,0.6)',
+      }}
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6 }}>
+        <span>UOMysticmoon is an independent private shard project.</span>
+        <span style={{ color: 'var(--dim)', fontSize: '0.84rem' }}>
+          <a href={`mailto:${contactEmail}`} style={{ color: 'var(--accent)', textDecoration: 'none' }}>
+            {contactEmail}
+          </a>
+          &nbsp;·&nbsp;
+          <Link to="/site/status" style={{ color: 'var(--accent)', textDecoration: 'none' }}>
+            Shard Status
+          </Link>
+          &nbsp;·&nbsp;
+          <Link to="/admin/login" style={{ color: '#5d6b7d', textDecoration: 'none' }}>
+            Admin
+          </Link>
+        </span>
+      </div>
+    </footer>
+  )
+}

client/src/components/SiteHeader.jsx

@@ -0,0 +1,73 @@
+import { Link } from 'react-router-dom'
+import MoonDot from './MoonDot.jsx'
+
+const NAV = {
+  website: [
+    { label: 'News', to: '/site/news' },
+    { label: 'Screenshots', to: '/site/screenshots' },
+    { label: 'Five on Friday', to: '/site/five-on-friday' },
+    { label: 'Newsletter', to: '/site/newsletter' },
+    { label: 'About', to: '/site/about' },
+    { label: 'Wiki', to: '/wiki' },
+  ],
+  wiki: [
+    { label: 'Website', to: '/site' },
+    { label: 'New Player Guide', to: '/wiki/new-player-guide' },
+    { label: 'Maps & Atlas', to: '/wiki/maps-atlas' },
+    { label: 'Systems', to: '/wiki/systems' },
+    { label: 'Rules', to: '/wiki/rules' },
+  ],
+}
+
+export default function SiteHeader({ section = 'website' }) {
+  const links = NAV[section] || NAV.website
+  return (
+    <header
+      style={{
+        borderBottom: '1px solid var(--line)',
+        background: 'rgba(9,13,18,0.86)',
+        backdropFilter: 'blur(8px)',
+        position: 'sticky',
+        top: 0,
+        zIndex: 30,
+      }}
+    >
+      <div
+        className="shell"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          gap: 20,
+          padding: '14px 0',
+          flexWrap: 'wrap',
+        }}
+      >
+        <Link
+          to="/"
+          className="display"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 10,
+            fontSize: '1.2rem',
+            letterSpacing: '0.05em',
+            color: 'var(--accent-bright)',
+            textDecoration: 'none',
+            fontWeight: 600,
+          }}
+        >
+          <MoonDot />
+          UOMysticmoon
+        </Link>
+        <nav style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
+          {links.map((l) => (
+            <Link key={l.to + l.label} to={l.to} className="pill">
+              {l.label}
+            </Link>
+          ))}
+        </nav>
+      </div>
+    </header>
+  )
+}

client/src/contexts/AuthContext.jsx

@@ -0,0 +1,67 @@
+import { createContext, useContext, useEffect, useState, useCallback } from 'react'
+import { api } from '../api/client.js'
+
+const AuthContext = createContext(null)
+
+export function AuthProvider({ children }) {
+  const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  const refresh = useCallback(async () => {
+    try {
+      const data = await api.me()
+      setUser(data.user)
+    } catch {
+      setUser(null)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    refresh()
+  }, [refresh])
+
+  // Step 1. Returns { user } on success, or { totpRequired, challenge } when the
+  // account has 2FA on (caller then calls loginTotp). `extra` carries honeypot.
+  const login = useCallback(async (username, password, extra) => {
+    const data = await api.login(username, password, extra)
+    if (data.user) setUser(data.user)
+    return data
+  }, [])
+
+  // Step 2 for TOTP users: exchange the challenge + code for a real session.
+  const loginTotp = useCallback(async (challenge, code) => {
+    const data = await api.loginTotp(challenge, code)
+    setUser(data.user)
+    return data.user
+  }, [])
+
+  // Step 2 for SSO logins whose account has 2FA on. The pending challenge lives in
+  // an httpOnly cookie, so only the code is sent. Returns { user, returnTo }.
+  const ssoLoginTotp = useCallback(async (code) => {
+    const data = await api.ssoLoginTotp(code)
+    setUser(data.user)
+    return data
+  }, [])
+
+  const logout = useCallback(async () => {
+    try {
+      await api.logout()
+    } finally {
+      setUser(null)
+    }
+  }, [])
+
+  return (
+    <AuthContext.Provider value={{ user, loading, login, loginTotp, ssoLoginTotp, logout, refresh }}>
+      {children}
+    </AuthContext.Provider>
+  )
+}
+
+export function useAuth() {
+  const ctx = useContext(AuthContext)
+  if (!ctx) throw new Error('useAuth must be used within AuthProvider')
+  return ctx
+}

client/src/contexts/SiteContext.jsx

@@ -0,0 +1,42 @@
+import { createContext, useContext, useEffect, useState, useCallback } from 'react'
+import { api } from '../api/client.js'
+
+const SiteContext = createContext(null)
+
+// Public site settings + mode (always reachable, even during maintenance).
+export function SiteProvider({ children }) {
+  const [settings, setSettings] = useState({})
+  const [loading, setLoading] = useState(true)
+
+  const refresh = useCallback(async () => {
+    try {
+      const data = await api.publicSettings()
+      setSettings(data || {})
+    } catch {
+      setSettings({})
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    refresh()
+  }, [refresh])
+
+  const value = {
+    settings,
+    loading,
+    refresh,
+    mode: settings.site_mode || 'live',
+    siteTitle: settings.site_title || 'UOMysticmoon',
+    contactEmail: settings.contact_email || 'UOMysticmoon@gmail.com',
+  }
+
+  return <SiteContext.Provider value={value}>{children}</SiteContext.Provider>
+}
+
+export function useSite() {
+  const ctx = useContext(SiteContext)
+  if (!ctx) throw new Error('useSite must be used within SiteProvider')
+  return ctx
+}

client/src/lib/format.js

@@ -0,0 +1,66 @@
+// Date + label helpers shared across pages.
+
+const MONTHS = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+]
+
+function parse(value) {
+  if (!value) return null
+  const d = new Date(value)
+  return isNaN(d.getTime()) ? null : d
+}
+
+// "June 24, 2026"
+export function longDate(value) {
+  const d = parse(value)
+  if (!d) return ''
+  return `${MONTHS[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`
+}
+
+// "Jun 24"
+export function shortDate(value) {
+  const d = parse(value)
+  if (!d) return ''
+  return `${MONTHS[d.getMonth()].slice(0, 3)} ${d.getDate()}`
+}
+
+// "Jun 26 18:55"
+export function dateTime(value) {
+  const d = parse(value)
+  if (!d) return ''
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  return `${MONTHS[d.getMonth()].slice(0, 3)} ${d.getDate()} ${hh}:${mm}`
+}
+
+// { mon: 'JUN', num: "'26" } for the newsletter month tile
+export function monthTile(value) {
+  const d = parse(value)
+  if (!d) return { mon: '—', num: '' }
+  return { mon: MONTHS[d.getMonth()].slice(0, 3).toUpperCase(), num: `'${String(d.getFullYear()).slice(2)}` }
+}
+
+// Compact relative time: "5m ago", "2h ago", "1d ago"
+export function ago(value) {
+  const d = parse(value)
+  if (!d) return ''
+  const secs = Math.max(1, Math.floor((Date.now() - d.getTime()) / 1000))
+  if (secs < 60) return `${secs}s ago`
+  const mins = Math.floor(secs / 60)
+  if (mins < 60) return `${mins}m ago`
+  const hrs = Math.floor(mins / 60)
+  if (hrs < 24) return `${hrs}h ago`
+  const days = Math.floor(hrs / 24)
+  return `${days}d ago`
+}
+
+const CATEGORY_LABELS = {
+  news: 'News',
+  five_on_friday: 'Five on Friday',
+  newsletter: 'Newsletter',
+  screenshot: 'Screenshot',
+}
+export function categoryLabel(dbCategory) {
+  return CATEGORY_LABELS[dbCategory] || dbCategory
+}

client/src/lib/heroLayout.js

@@ -0,0 +1,108 @@
+// Shared hero-layout helpers used by the public portal and the admin editor.
+
+export const DEFAULT_HERO_IMAGE = '/assets/img/uomysticmoon-main-hero.png'
+
+// The original hand-tuned multi-gradient hero background (used only for the
+// untouched default so the live page is byte-for-byte unchanged until edited).
+export const HERO_BG =
+  "linear-gradient(90deg,rgba(11,15,20,0.34) 0%,rgba(11,15,20,0.5) 36%,rgba(11,15,20,0.78) 62%,rgba(11,15,20,0.66) 100%),linear-gradient(180deg,rgba(11,15,20,0.08) 0%,rgba(11,15,20,0.72) 100%),url('" +
+  DEFAULT_HERO_IMAGE +
+  "')"
+
+// Single-stop dark overlay driven by the editor's opacity slider.
+export function buildOverlay(opacity) {
+  return `linear-gradient(180deg,rgba(11,15,20,${opacity * 0.15}) 0%,rgba(11,15,20,${opacity}) 100%)`
+}
+
+// Background style for a layout. When `isDefault` and no custom image is set, use
+// the exact original gradient stack; otherwise compose the overlay over the image.
+export function heroBackground(layout, { isDefault = false } = {}) {
+  const bg = layout.background || {}
+  const backgroundImage =
+    isDefault && !bg.image_url
+      ? HERO_BG
+      : `${buildOverlay(layout.overlay?.opacity ?? 0.72)}, url('${bg.image_url || DEFAULT_HERO_IMAGE}')`
+  return {
+    backgroundColor: 'var(--bg-deep)',
+    backgroundImage,
+    backgroundPosition: `${bg.position_x || 'left'} ${bg.position_y || 'center'}`,
+    backgroundRepeat: 'no-repeat',
+    backgroundSize: bg.size || 'cover',
+  }
+}
+
+// Parse a stored layout string; return null if missing/malformed/wrong version.
+export function parseLayout(str) {
+  try {
+    const l = str ? JSON.parse(str) : null
+    return l && l.version === 1 && Array.isArray(l.elements) ? l : null
+  } catch {
+    return null
+  }
+}
+
+// The current hardcoded hero as a HeroLayout, so the page is unchanged until
+// staff publish their own. Font sizes use the existing clamp() strings so the
+// default stays responsive (editor-created text uses px).
+export function defaultLayout(teaser) {
+  return {
+    version: 1,
+    background: { image_url: null, position_x: 'left', position_y: 'center', size: 'cover' },
+    overlay: { opacity: 0.72 },
+    elements: [
+      {
+        id: 'default-text',
+        type: 'text_block',
+        x: 50,
+        y: 42,
+        z: 1,
+        anchor: 'center',
+        props: {
+          align: 'center',
+          width: 760,
+          lines: [
+            { text: 'Private shard project', tag: 'span', fontSize: '0.74rem', color: '#c2d2e6', weight: 700, letterSpacing: '0.22em', transform: 'uppercase', font: 'sans' },
+            { text: 'UOMysticmoon', tag: 'h1', fontSize: 'clamp(3rem,8.5vw,5.75rem)', color: 'var(--head)', weight: 600, letterSpacing: '0.02em', lineHeight: 1, font: 'display', marginTop: 14 },
+            { text: 'A private Ultima Online world in progress', tag: 'p', fontSize: '1.32rem', color: '#dbe2ea', italic: true, marginTop: 22 },
+            { text: teaser, tag: 'p', fontSize: '1.06rem', color: '#c4cdd8', maxWidth: 600, marginTop: 22 },
+          ],
+        },
+      },
+      {
+        id: 'default-buttons',
+        type: 'buttons',
+        x: 50,
+        y: 72,
+        z: 2,
+        anchor: 'center',
+        props: {
+          align: 'center',
+          gap: 12,
+          items: [
+            { label: 'Enter the Website', to: '/site', variant: 'primary' },
+            { label: 'Open the Wiki', to: '/wiki', variant: 'ghost' },
+          ],
+        },
+      },
+      {
+        id: 'default-quick-links',
+        type: 'buttons',
+        x: 50,
+        y: 85,
+        z: 3,
+        anchor: 'center',
+        props: {
+          align: 'center',
+          gap: 10,
+          items: [
+            { label: 'News', to: '/site/news', variant: 'ghost' },
+            { label: 'Screenshots', to: '/site/screenshots', variant: 'ghost' },
+            { label: 'Five on Friday', to: '/site/five-on-friday', variant: 'ghost' },
+            { label: 'Monthly Newsletter', to: '/site/newsletter', variant: 'ghost' },
+            { label: 'About', to: '/site/about', variant: 'ghost' },
+          ],
+        },
+      },
+    ],
+  }
+}

client/src/lib/useAsync.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react'
+
+// Minimal data-fetching hook: runs `fn` on mount / when deps change.
+export function useAsync(fn, deps = []) {
+  const [state, setState] = useState({ loading: true, error: null, data: null })
+
+  useEffect(() => {
+    let active = true
+    setState({ loading: true, error: null, data: null })
+    fn()
+      .then((data) => active && setState({ loading: false, error: null, data }))
+      .catch((error) => active && setState({ loading: false, error, data: null }))
+    return () => {
+      active = false
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps)
+
+  return state
+}

client/src/main.jsx

@@ -0,0 +1,13 @@
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import App from './App.jsx'
+import './styles/theme.css'
+
+createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </React.StrictMode>,
+)

client/src/routes/admin/AdminLayout.jsx

@@ -0,0 +1,191 @@
+import { useEffect } from 'react'
+import { NavLink, Outlet, useNavigate, useLocation } from 'react-router-dom'
+import MoonDot from '../../components/MoonDot.jsx'
+import { useAuth } from '../../contexts/AuthContext.jsx'
+import { useSite } from '../../contexts/SiteContext.jsx'
+
+// `roles` (when present) restricts which roles see a nav item. Items without it
+// are shown to admin/editor as before. Moderators are further confined to just
+// their own section + account security (see the redirect effect below).
+const NAV = [
+  { to: '/admin', label: 'Dashboard', end: true },
+  { to: '/admin/posts', label: 'Posts' },
+  { to: '/admin/wiki', label: 'Wiki' },
+  { to: '/admin/hero', label: 'Hero Editor' },
+  { to: '/admin/moderation', label: 'Moderation', roles: ['admin', 'moderator'] },
+  { to: '/admin/settings', label: 'Settings' },
+  { to: '/admin/activity', label: 'Activity' },
+  { to: '/admin/bot-activity', label: 'Bot Activity' },
+  { to: '/admin/discord-bot', label: 'Discord Bot' },
+  { to: '/admin/auth-providers', label: 'Authentication' },
+  { to: '/admin/users', label: 'Users' },
+  { to: '/admin/account', label: 'Account' },
+]
+
+const TITLES = {
+  '/admin': 'Dashboard',
+  '/admin/posts': 'Posts',
+  '/admin/wiki': 'Wiki Pages',
+  '/admin/hero': 'Hero Editor',
+  '/admin/moderation': 'Moderation',
+  '/admin/settings': 'Site Settings',
+  '/admin/activity': 'Activity Log',
+  '/admin/bot-activity': 'Bot Activity',
+  '/admin/discord-bot': 'Discord Bot',
+  '/admin/auth-providers': 'Authentication',
+  '/admin/users': 'Users',
+  '/admin/account': 'Account Security',
+}
+
+const navBtnBase = {
+  textAlign: 'left',
+  borderRadius: 8,
+  padding: '10px 14px',
+  fontFamily: 'var(--sans)',
+  fontSize: '0.92rem',
+  textDecoration: 'none',
+  display: 'block',
+  transition: 'background .15s,color .15s',
+}
+
+export default function AdminLayout() {
+  const { user, logout } = useAuth()
+  const { mode } = useSite()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const title =
+    TITLES[location.pathname] ||
+    (location.pathname.startsWith('/admin/moderation') ? 'Moderation' : 'Admin')
+  // The hero canvas editor needs room — let it use the full content width.
+  const wide = location.pathname === '/admin/hero'
+  const modeDot = mode === 'live' ? 'var(--mode-live)' : 'var(--mode-maint)'
+
+  // Moderators only get the moderation section + their own account security.
+  const isModerator = user?.role === 'moderator'
+  const navItems = NAV.filter((n) => {
+    if (n.roles && !n.roles.includes(user?.role)) return false
+    if (isModerator) return n.to === '/admin/moderation' || n.to === '/admin/account'
+    return true
+  })
+
+  // Confine a moderator who deep-links (or is redirected to the index) to a page
+  // outside their remit — the API would 403 anyway, so send them to their home.
+  useEffect(() => {
+    if (!isModerator) return
+    const p = location.pathname
+    if (!p.startsWith('/admin/moderation') && p !== '/admin/account') {
+      navigate('/admin/moderation', { replace: true })
+    }
+  }, [isModerator, location.pathname, navigate])
+
+  // Keep the admin out of search indexes (belt-and-suspenders with robots.txt).
+  useEffect(() => {
+    const meta = document.createElement('meta')
+    meta.name = 'robots'
+    meta.content = 'noindex, nofollow'
+    document.head.appendChild(meta)
+    return () => document.head.removeChild(meta)
+  }, [])
+
+  async function signOut() {
+    await logout()
+    navigate('/admin/login', { replace: true })
+  }
+
+  return (
+    <div className="admin-grid">
+      {/* Sidebar */}
+      <aside
+        style={{
+          borderRight: '1px solid var(--line)',
+          background: 'var(--bg)',
+          display: 'flex',
+          flexDirection: 'column',
+          position: 'sticky',
+          top: 0,
+          height: '100vh',
+        }}
+      >
+        <div style={{ padding: '22px 22px 18px', borderBottom: '1px solid var(--line-soft)', display: 'flex', alignItems: 'center', gap: 10 }}>
+          <MoonDot />
+          <div>
+            <div className="display" style={{ fontSize: '1.02rem', color: 'var(--head)', letterSpacing: '0.03em' }}>
+              UOMysticmoon
+            </div>
+            <div className="sans" style={{ color: 'var(--dim)', fontSize: '0.66rem', letterSpacing: '0.14em', textTransform: 'uppercase' }}>
+              Admin
+            </div>
+          </div>
+        </div>
+
+        <nav style={{ flex: 1, padding: '14px 12px', display: 'flex', flexDirection: 'column', gap: 4 }}>
+          {navItems.map((n) => (
+            <NavLink
+              key={n.to}
+              to={n.to}
+              end={n.end}
+              style={({ isActive }) => ({
+                ...navBtnBase,
+                background: isActive ? 'var(--blue)' : 'transparent',
+                color: isActive ? 'var(--ink)' : 'var(--muted)',
+                borderLeft: `2px solid ${isActive ? 'var(--accent)' : 'transparent'}`,
+              })}
+            >
+              {n.label}
+            </NavLink>
+          ))}
+        </nav>
+
+        <div style={{ padding: '14px 16px', borderTop: '1px solid var(--line-soft)' }}>
+          <div className="sans" style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12, fontSize: '0.78rem', color: 'var(--muted)' }}>
+            <span style={{ width: 9, height: 9, borderRadius: '50%', background: modeDot, boxShadow: `0 0 8px ${modeDot}` }} />
+            Site is&nbsp;<strong style={{ color: 'var(--ink)', textTransform: 'capitalize' }}>{mode}</strong>
+          </div>
+          <button
+            onClick={signOut}
+            className="sans"
+            style={{ display: 'block', width: '100%', textAlign: 'center', border: '1px solid var(--line)', borderRadius: 8, padding: 9, color: 'var(--muted)', background: 'transparent', fontSize: '0.84rem', cursor: 'pointer' }}
+          >
+            Sign out
+          </button>
+        </div>
+      </aside>
+
+      {/* Main */}
+      <main style={{ display: 'flex', flexDirection: 'column', minWidth: 0 }}>
+        <header
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 16,
+            padding: '20px 32px',
+            borderBottom: '1px solid var(--line-soft)',
+            background: 'var(--bg)',
+            position: 'sticky',
+            top: 0,
+            zIndex: 10,
+          }}
+        >
+          <h1 className="display" style={{ margin: 0, fontSize: '1.5rem', color: 'var(--head)' }}>
+            {title}
+          </h1>
+          <div className="sans" style={{ display: 'flex', alignItems: 'center', gap: 14, fontSize: '0.84rem', color: 'var(--muted)' }}>
+            <a href="/" target="_blank" rel="noreferrer" style={{ color: 'var(--accent)', textDecoration: 'none' }}>
+              View site →
+            </a>
+            <span
+              style={{ width: 30, height: 30, borderRadius: '50%', background: 'linear-gradient(180deg,#2a3a52,#1a2536)', border: '1px solid var(--line)', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#d8e2ef', fontSize: '0.8rem', textTransform: 'uppercase' }}
+            >
+              {(user?.username || 'A').charAt(0)}
+            </span>
+          </div>
+        </header>
+
+        <div style={{ flex: 1, padding: '30px 32px 60px', maxWidth: wide ? 'none' : 1000, width: '100%' }}>
+          <Outlet />
+        </div>
+      </main>
+    </div>
+  )
+}

client/src/routes/admin/AdminLogin.jsx

@@ -0,0 +1,299 @@
+import { useEffect, useState } from 'react'
+import { Link, useNavigate, useLocation } from 'react-router-dom'
+import MoonDot from '../../components/MoonDot.jsx'
+import ProviderIcon from '../../components/ProviderIcon.jsx'
+import { useAuth } from '../../contexts/AuthContext.jsx'
+import { api } from '../../api/client.js'
+
+// Friendly copy for the ?sso_error codes the SSO callback can redirect back with.
+const SSO_ERRORS = {
+  not_linked: 'That account is not linked to an admin user. Sign in with your password, then link it under Account.',
+  denied: 'Sign-in was cancelled.',
+  unavailable: 'That sign-in method is not available right now.',
+  bad_state: 'Your sign-in session expired. Please try again.',
+  error: 'Could not complete sign-in. Please try again.',
+}
+
+const BG =
+  "linear-gradient(180deg,rgba(11,15,20,0.72),rgba(11,15,20,0.9)),url('/assets/img/uomysticmoon-main-hero.png')"
+
+// Hidden anti-bot field. Off-screen via CSS (NOT display:none/hidden, which bots
+// skip) so real users never fill it but naive scripted bots do. Name must match
+// the server's HONEYPOT_FIELD ('company').
+const honeypotStyle = {
+  position: 'absolute',
+  left: '-9999px',
+  top: 'auto',
+  width: '1px',
+  height: '1px',
+  opacity: 0,
+  pointerEvents: 'none',
+}
+
+export default function AdminLogin() {
+  const { user, login, loginTotp, ssoLoginTotp } = useAuth()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const dest = location.state?.from?.pathname || '/admin'
+
+  const [username, setUsername] = useState('')
+  const [password, setPassword] = useState('')
+  const [company, setCompany] = useState('') // honeypot — must stay empty
+  const [error, setError] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  // Two-factor step state. `ssoTotp` marks the SSO variant: the challenge lives in
+  // an httpOnly cookie (not React state), so the code posts to a different endpoint.
+  const [stage, setStage] = useState('creds') // 'creds' | 'totp'
+  const [challenge, setChallenge] = useState('')
+  const [code, setCode] = useState('')
+  const [ssoTotp, setSsoTotp] = useState(false)
+
+  // SSO providers to offer (empty if none configured) + any error the callback
+  // bounced us back with (?sso_error=...).
+  const [providers, setProviders] = useState([])
+  const ssoError = SSO_ERRORS[new URLSearchParams(location.search).get('sso_error')] || ''
+
+  // Already signed in → go straight to the panel.
+  useEffect(() => {
+    if (user) navigate(dest, { replace: true })
+  }, [user, dest, navigate])
+
+  // The SSO callback bounces 2FA accounts back here with ?sso_totp=1 after the IdP
+  // step: it has staged an httpOnly TOTP challenge and needs the authenticator code
+  // before it will issue a session. Jump straight to the code step.
+  useEffect(() => {
+    if (new URLSearchParams(location.search).get('sso_totp')) {
+      setStage('totp')
+      setSsoTotp(true)
+    }
+  }, [location.search])
+
+  // Load enabled SSO providers for the buttons. Failure is non-fatal — the page
+  // still works with password login and simply shows no provider buttons.
+  useEffect(() => {
+    let active = true
+    api
+      .authProviders()
+      .then((list) => active && setProviders(Array.isArray(list) ? list : []))
+      .catch(() => active && setProviders([]))
+    return () => {
+      active = false
+    }
+  }, [])
+
+  // Full-page redirect into the provider's OAuth flow, preserving the intended
+  // destination so the callback can return the user there.
+  function startSso(provider) {
+    const q = dest && dest !== '/admin' ? `?returnTo=${encodeURIComponent(dest)}` : ''
+    window.location.assign(provider.loginUrl + q)
+  }
+
+  async function onSubmit(e) {
+    e.preventDefault()
+    setError('')
+    setBusy(true)
+    try {
+      const data = await login(username, password, { company })
+      if (data.totpRequired) {
+        setChallenge(data.challenge)
+        setStage('totp')
+        setBusy(false)
+        return
+      }
+      navigate(dest, { replace: true })
+    } catch (err) {
+      setError(err.status === 401 ? 'Incorrect username or password.' : 'Could not sign in right now.')
+      setBusy(false)
+    }
+  }
+
+  async function onSubmitTotp(e) {
+    e.preventDefault()
+    setError('')
+    setBusy(true)
+    try {
+      if (ssoTotp) {
+        const { returnTo } = await ssoLoginTotp(code)
+        navigate(returnTo || '/admin', { replace: true })
+      } else {
+        await loginTotp(challenge, code)
+        navigate(dest, { replace: true })
+      }
+    } catch (err) {
+      const expired = err.status === 401 && /expired/i.test(err.message)
+      setError(
+        expired
+          ? 'Your verification session expired. Please sign in again.'
+          : 'Invalid verification code.',
+      )
+      setBusy(false)
+      if (expired) {
+        setStage('creds')
+        setSsoTotp(false)
+      }
+    }
+  }
+
+  return (
+    <main
+      style={{
+        minHeight: '100vh',
+        display: 'grid',
+        placeItems: 'center',
+        padding: '40px 18px',
+        overflow: 'hidden',
+        backgroundColor: 'var(--bg-deep)',
+        backgroundImage: BG,
+        backgroundPosition: 'center',
+        backgroundSize: 'cover',
+      }}
+    >
+      <div style={{ width: '100%', maxWidth: 400 }}>
+        <div style={{ textAlign: 'center', marginBottom: 26 }}>
+          <div style={{ marginBottom: 14 }}>
+            <MoonDot size={15} glow={0.55} />
+          </div>
+          <h1 className="display" style={{ margin: 0, fontSize: '1.7rem', letterSpacing: '0.04em', color: 'var(--head)' }}>
+            UOMysticmoon
+          </h1>
+          <p className="sans" style={{ margin: '6px 0 0', color: '#9aa6b4', fontSize: '0.8rem', letterSpacing: '0.16em', textTransform: 'uppercase' }}>
+            Admin Panel
+          </p>
+        </div>
+
+        <form
+          onSubmit={stage === 'totp' ? onSubmitTotp : onSubmit}
+          style={{
+            border: '1px solid var(--line)',
+            borderRadius: 12,
+            padding: 28,
+            background: 'linear-gradient(180deg,rgba(25,34,49,0.92),rgba(20,26,33,0.92))',
+            backdropFilter: 'blur(6px)',
+            boxShadow: '0 24px 60px rgba(0,0,0,0.5)',
+          }}
+        >
+          {stage === 'creds' ? (
+            <>
+              <label style={{ display: 'block', marginBottom: 16 }}>
+                <span className="field-label">Username</span>
+                <input
+                  type="text"
+                  autoComplete="username"
+                  autoFocus
+                  value={username}
+                  onChange={(e) => setUsername(e.target.value)}
+                  className="input"
+                />
+              </label>
+              <label style={{ display: 'block', marginBottom: 22 }}>
+                <span className="field-label">Password</span>
+                <input
+                  type="password"
+                  autoComplete="current-password"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  className="input"
+                />
+              </label>
+
+              {/* Honeypot: hidden from humans, left empty; bots that fill it are rejected. */}
+              <div style={honeypotStyle} aria-hidden="true">
+                <label>
+                  Company
+                  <input
+                    type="text"
+                    name="company"
+                    tabIndex={-1}
+                    autoComplete="off"
+                    value={company}
+                    onChange={(e) => setCompany(e.target.value)}
+                  />
+                </label>
+              </div>
+            </>
+          ) : (
+            <label style={{ display: 'block', marginBottom: 22 }}>
+              <span className="field-label">Authentication code</span>
+              <input
+                type="text"
+                inputMode="numeric"
+                autoComplete="one-time-code"
+                autoFocus
+                placeholder="6-digit code"
+                value={code}
+                onChange={(e) => setCode(e.target.value)}
+                className="input"
+              />
+              <span className="sans" style={{ display: 'block', marginTop: 8, color: 'var(--dim)', fontSize: '0.76rem' }}>
+                Enter the code from your authenticator app.
+              </span>
+            </label>
+          )}
+
+          {(error || (stage === 'creds' && ssoError)) && (
+            <p className="sans" style={{ margin: '0 0 14px', color: '#d98b84', fontSize: '0.85rem', textAlign: 'center', lineHeight: 1.5 }}>
+              {error || ssoError}
+            </p>
+          )}
+
+          <button
+            type="submit"
+            disabled={busy}
+            className="btn btn-primary"
+            style={{ display: 'block', width: '100%', borderRadius: 8, padding: 12, textAlign: 'center' }}
+          >
+            {busy ? 'Signing in…' : stage === 'totp' ? 'Verify' : 'Sign in'}
+          </button>
+
+          {/* SSO providers — only on the credentials step, only if any are enabled. */}
+          {stage === 'creds' && providers.length > 0 && (
+            <div style={{ marginTop: 20 }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 12, margin: '0 0 16px', color: 'var(--dim)' }}>
+                <span style={{ flex: 1, height: 1, background: 'var(--line)' }} />
+                <span className="sans" style={{ fontSize: '0.72rem', letterSpacing: '0.14em', textTransform: 'uppercase' }}>or</span>
+                <span style={{ flex: 1, height: 1, background: 'var(--line)' }} />
+              </div>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
+                {providers.map((p) => (
+                  <button
+                    key={p.id}
+                    type="button"
+                    onClick={() => startSso(p)}
+                    className="btn"
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      gap: 10,
+                      width: '100%',
+                      borderRadius: 8,
+                      padding: 11,
+                      border: '1px solid var(--line)',
+                      background: 'rgba(255,255,255,0.04)',
+                      color: 'var(--ink)',
+                    }}
+                  >
+                    <span style={{ display: 'inline-flex', width: 18, height: 18 }}>
+                      <ProviderIcon icon={p.icon} size={18} />
+                    </span>
+                    Continue with {p.name}
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+
+          <p className="sans" style={{ margin: '16px 0 0', textAlign: 'center', color: 'var(--dim)', fontSize: '0.76rem' }}>
+            Protected area — not indexed. Sessions expire after 1 day.
+          </p>
+        </form>
+        <p style={{ textAlign: 'center', margin: '20px 0 0' }}>
+          <Link to="/" className="sans" style={{ color: 'var(--accent)', fontSize: '0.84rem', textDecoration: 'none' }}>
+            ← Back to site
+          </Link>
+        </p>
+      </div>
+    </main>
+  )
+}

client/src/routes/admin/views/AccountAdmin.jsx

@@ -0,0 +1,308 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import ProviderIcon from '../../../components/ProviderIcon.jsx'
+import { api } from '../../../api/client.js'
+
+// Link/unlink external SSO identities to this account. Linking redirects through
+// the provider's OAuth flow (/auth/sso/:id/link) and returns here with ?linked
+// or ?link_error. Only providers that are enabled + valid can be linked.
+function LinkedAccounts() {
+  const [linked, setLinked] = useState(null)
+  const [available, setAvailable] = useState([])
+  const [error, setError] = useState('')
+
+  const banner = (() => {
+    const q = new URLSearchParams(window.location.search)
+    if (q.get('linked')) return { ok: true, text: 'Account linked.' }
+    if (q.get('link_error') === 'in_use') return { ok: false, text: 'That external account is already linked to another user.' }
+    if (q.get('link_error')) return { ok: false, text: 'Could not link that account. Please try again.' }
+    return null
+  })()
+
+  const load = useCallback(async () => {
+    try {
+      const [ids, avail] = await Promise.all([
+        api.admin.linkedIdentities(),
+        api.authProviders().catch(() => []),
+      ])
+      setLinked(ids)
+      setAvailable(Array.isArray(avail) ? avail : [])
+    } catch {
+      setError('Could not load linked accounts.')
+    }
+  }, [])
+  useEffect(() => {
+    load()
+  }, [load])
+
+  const nameFor = (id) => available.find((p) => p.id === id)?.name || id.charAt(0).toUpperCase() + id.slice(1)
+  const iconFor = (id) => (id === 'google' || id === 'discord' ? id : 'oidc')
+
+  async function unlink(provider) {
+    if (!window.confirm(`Unlink ${nameFor(provider)} from your account?`)) return
+    try {
+      await api.admin.unlinkIdentity(provider)
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not unlink.')
+    }
+  }
+
+  if (error) return <ErrorState message={error} />
+  if (!linked) return null
+
+  const linkedIds = new Set(linked.map((i) => i.provider))
+  const linkable = available.filter((p) => !linkedIds.has(p.id))
+
+  return (
+    <div style={{ marginTop: 40, borderTop: '1px solid var(--line-soft)', paddingTop: 28 }}>
+      <h2 className="display" style={{ marginTop: 0, fontSize: '1.2rem', color: 'var(--head)' }}>
+        Linked accounts
+      </h2>
+      <p className="sans" style={{ color: 'var(--muted)', fontSize: '0.9rem', lineHeight: 1.6 }}>
+        Link a Google, Discord, or other SSO account so you can sign in with it. SSO can only sign in
+        to an account it is linked to — linking here is what grants that access.
+      </p>
+
+      {banner && (
+        <p className="sans" style={{ color: banner.ok ? '#7fd0a4' : '#d98b84', fontSize: '0.86rem' }}>
+          {banner.text}
+        </p>
+      )}
+
+      {linked.length > 0 && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 10, margin: '14px 0' }}>
+          {linked.map((i) => (
+            <div key={i.provider} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '10px 14px', border: '1px solid var(--line)', borderRadius: 8 }}>
+              <span style={{ display: 'inline-flex', width: 20, height: 20 }}>
+                <ProviderIcon icon={iconFor(i.provider)} size={20} />
+              </span>
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <div className="sans" style={{ color: 'var(--head)', fontSize: '0.9rem' }}>{nameFor(i.provider)}</div>
+                {i.email && <div className="sans dim" style={{ fontSize: '0.78rem' }}>{i.email}</div>}
+              </div>
+              <button onClick={() => unlink(i.provider)} className="pill" style={{ color: '#d98b84', borderColor: '#d98b84' }}>
+                Unlink
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {linkable.length > 0 && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 10, marginTop: 6 }}>
+          {linkable.map((p) => (
+            <button
+              key={p.id}
+              onClick={() => window.location.assign(`/api/v1/auth/sso/${p.id}/link`)}
+              className="btn"
+              style={{ display: 'flex', alignItems: 'center', gap: 10, justifyContent: 'center', width: '100%', maxWidth: 320, borderRadius: 8, padding: 10, border: '1px solid var(--line)', background: 'rgba(255,255,255,0.04)', color: 'var(--ink)' }}
+            >
+              <span style={{ display: 'inline-flex', width: 18, height: 18 }}>
+                <ProviderIcon icon={p.icon} size={18} />
+              </span>
+              Link {p.name}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {linked.length === 0 && linkable.length === 0 && (
+        <p className="sans dim" style={{ fontSize: '0.86rem' }}>
+          No SSO providers are enabled. Configure them under <strong>Authentication</strong>.
+        </p>
+      )}
+    </div>
+  )
+}
+
+// Self-service account security: enable / disable optional TOTP two-factor.
+export default function AccountAdmin() {
+  const [account, setAccount] = useState(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState('')
+
+  // Enrollment state.
+  const [setup, setSetup] = useState(null) // { qr, otpauthUrl }
+  const [code, setCode] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [msg, setMsg] = useState('')
+
+  async function load() {
+    try {
+      setAccount(await api.admin.getAccount())
+    } catch {
+      setError('Could not load your account.')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    load()
+  }, [])
+
+  if (loading) return <Loading />
+  if (error) return <ErrorState message={error} />
+
+  async function beginSetup() {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      setSetup(await api.admin.totpSetup())
+      setCode('')
+    } catch (err) {
+      setError(err.message || 'Could not start setup.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function confirmEnable() {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      await api.admin.totpEnable(code.trim())
+      setSetup(null)
+      setCode('')
+      setMsg('Two-factor authentication is now enabled.')
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not enable two-factor.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function disable() {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      await api.admin.totpDisable(code.trim())
+      setCode('')
+      setMsg('Two-factor authentication has been disabled.')
+      await load()
+    } catch (err) {
+      setError(err.message || 'Could not disable two-factor.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const enabled = account?.totp_enabled
+
+  return (
+    <section style={{ maxWidth: 560 }}>
+      <h2 className="display" style={{ marginTop: 0, fontSize: '1.2rem', color: 'var(--head)' }}>
+        Two-factor authentication
+      </h2>
+      <p className="sans" style={{ color: 'var(--muted)', fontSize: '0.9rem', lineHeight: 1.6 }}>
+        Add a time-based one-time code (TOTP) from an authenticator app as a second step at login.
+        Optional, and only affects your own account.
+      </p>
+
+      <div
+        className="sans"
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 8,
+          padding: '6px 12px',
+          borderRadius: 999,
+          border: '1px solid var(--line)',
+          fontSize: '0.82rem',
+          color: enabled ? '#7fd0a4' : 'var(--muted)',
+          marginBottom: 22,
+        }}
+      >
+        <span
+          style={{
+            width: 9,
+            height: 9,
+            borderRadius: '50%',
+            background: enabled ? '#7fd0a4' : 'var(--dim)',
+          }}
+        />
+        {enabled ? 'Enabled' : 'Not enabled'}
+      </div>
+
+      {/* Enable flow */}
+      {!enabled && !setup && (
+        <div>
+          <button onClick={beginSetup} disabled={busy} className="btn btn-primary btn-sq">
+            {busy ? 'Preparing…' : 'Set up two-factor'}
+          </button>
+        </div>
+      )}
+
+      {!enabled && setup && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+          <p className="sans" style={{ margin: 0, color: 'var(--muted)', fontSize: '0.88rem' }}>
+            1. Scan this QR code with your authenticator app, then enter the current 6-digit code to confirm.
+          </p>
+          <img
+            src={setup.qr}
+            alt="TOTP QR code"
+            width={180}
+            height={180}
+            style={{ borderRadius: 8, background: '#fff', padding: 8, alignSelf: 'flex-start' }}
+          />
+          <label style={{ display: 'block', maxWidth: 220 }}>
+            <span className="field-label">Verification code</span>
+            <input
+              type="text"
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              placeholder="6-digit code"
+              value={code}
+              onChange={(e) => setCode(e.target.value)}
+              className="input"
+            />
+          </label>
+          <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
+            <button onClick={confirmEnable} disabled={busy || !code.trim()} className="btn btn-primary btn-sq">
+              {busy ? 'Enabling…' : 'Confirm & enable'}
+            </button>
+            <button onClick={() => setSetup(null)} disabled={busy} className="pill">
+              Cancel
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* Disable flow */}
+      {enabled && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+          <p className="sans" style={{ margin: 0, color: 'var(--muted)', fontSize: '0.88rem' }}>
+            Enter a current code from your authenticator to turn two-factor off.
+          </p>
+          <label style={{ display: 'block', maxWidth: 220 }}>
+            <span className="field-label">Verification code</span>
+            <input
+              type="text"
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              placeholder="6-digit code"
+              value={code}
+              onChange={(e) => setCode(e.target.value)}
+              className="input"
+            />
+          </label>
+          <div>
+            <button onClick={disable} disabled={busy || !code.trim()} className="btn btn-sq" style={{ borderColor: '#d98b84', color: '#d98b84' }}>
+              {busy ? 'Disabling…' : 'Disable two-factor'}
+            </button>
+          </div>
+        </div>
+      )}
+
+      {msg && <p className="sans" style={{ marginTop: 16, color: '#7fd0a4', fontSize: '0.86rem' }}>{msg}</p>}
+      {error && <p className="sans" style={{ marginTop: 16, color: '#d98b84', fontSize: '0.86rem' }}>{error}</p>}
+
+      <LinkedAccounts />
+    </section>
+  )
+}

client/src/routes/admin/views/ActivityAdmin.jsx

@@ -0,0 +1,57 @@
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import { useAsync } from '../../../lib/useAsync.js'
+import { dateTime } from '../../../lib/format.js'
+import { api } from '../../../api/client.js'
+import { formatDetail } from './Dashboard.jsx'
+
+export default function ActivityAdmin() {
+  const { loading, error, data } = useAsync(() => api.admin.activity(100))
+  const rows = data || []
+
+  if (loading) return <Loading />
+  if (error) return <ErrorState message="Could not load the activity log." />
+
+  return (
+    <section>
+      <div className="panel-flat">
+        <table className="adm-table">
+          <thead>
+            <tr>
+              <th className="adm-th">Action</th>
+              <th className="adm-th">Detail</th>
+              <th className="adm-th">User</th>
+              <th className="adm-th">IP</th>
+              <th className="adm-th">When</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.length === 0 && (
+              <tr>
+                <td className="adm-td" colSpan={5} style={{ color: 'var(--muted)' }}>
+                  No activity recorded yet.
+                </td>
+              </tr>
+            )}
+            {rows.map((a) => (
+              <tr key={a.id}>
+                <td className="adm-td">
+                  <span style={{ fontFamily: 'ui-monospace,Menlo,monospace', color: 'var(--accent)', fontSize: '0.82rem' }}>
+                    {a.action}
+                  </span>
+                </td>
+                <td className="adm-td">{formatDetail(a)}</td>
+                <td className="adm-td" style={{ color: 'var(--text)' }}>
+                  {a.username || '—'}
+                </td>
+                <td className="adm-td dim" style={{ fontFamily: 'ui-monospace,Menlo,monospace', fontSize: '0.8rem' }}>
+                  {a.ip || '—'}
+                </td>
+                <td className="adm-td dim">{dateTime(a.created_at)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  )
+}

client/src/routes/admin/views/AuthProvidersAdmin.jsx

@@ -0,0 +1,380 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import ProviderIcon from '../../../components/ProviderIcon.jsx'
+import { api } from '../../../api/client.js'
+
+// Admin config for authentication providers. Local password + TOTP is always on
+// (informational tab). Google/Discord are built-ins with a fixed config surface
+// (Enabled + Client ID + Client Secret). Custom providers use the full OIDC editor.
+
+const TABS = [
+  { id: 'local', label: 'Local Accounts' },
+  { id: 'google', label: 'Google' },
+  { id: 'discord', label: 'Discord' },
+  { id: 'custom', label: 'Custom Providers' },
+]
+
+// The redirect/callback URL to register with the provider. Mirrors the server's
+// redirect_uri (APP_BASE_URL + this path); shown so admins can copy it exactly.
+function callbackUrl(id) {
+  return `${window.location.origin}/api/v1/auth/sso/${id}/callback`
+}
+
+function HealthWarning({ provider }) {
+  if (!provider || !provider.enabled || provider.health.valid) return null
+  return (
+    <p className="sans" style={{ margin: '4px 0 0', color: '#e0b070', fontSize: '0.82rem', lineHeight: 1.5 }}>
+      Enabled but incomplete (missing: {provider.health.missing.join(', ')}). Hidden from the login
+      page until fully configured.
+    </p>
+  )
+}
+
+function CallbackHint({ id }) {
+  return (
+    <div style={{ marginTop: 4 }}>
+      <span className="field-label">Redirect / callback URL (register this with the provider)</span>
+      <code
+        className="sans"
+        style={{ display: 'block', padding: '9px 12px', borderRadius: 8, border: '1px solid var(--line)', background: 'var(--bg-deep)', color: 'var(--muted)', fontSize: '0.82rem', wordBreak: 'break-all' }}
+      >
+        {callbackUrl(id)}
+      </code>
+    </div>
+  )
+}
+
+function Toggle({ checked, onChange, label }) {
+  return (
+    <label className="sans" style={{ display: 'inline-flex', alignItems: 'center', gap: 10, cursor: 'pointer', fontSize: '0.9rem', color: 'var(--ink)' }}>
+      <input type="checkbox" checked={checked} onChange={(e) => onChange(e.target.checked)} />
+      {label}
+    </label>
+  )
+}
+
+// ── Built-in (Google / Discord) config form ────────────────────────────────
+function BuiltinForm({ provider, onSaved }) {
+  const [enabled, setEnabled] = useState(provider.enabled)
+  const [clientId, setClientId] = useState(provider.clientId || '')
+  const [secret, setSecret] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [msg, setMsg] = useState('')
+  const [error, setError] = useState('')
+
+  // Re-sync when switching between provider tabs.
+  useEffect(() => {
+    setEnabled(provider.enabled)
+    setClientId(provider.clientId || '')
+    setSecret('')
+    setMsg('')
+    setError('')
+  }, [provider.id]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  async function save() {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      const body = { enabled, clientId }
+      if (secret) body.secret = secret // only send a new secret when entered
+      await api.admin.updateAuthProvider(provider.id, body)
+      setSecret('')
+      setMsg('Saved.')
+      await onSaved()
+    } catch (err) {
+      setError(err.message || 'Could not save.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div style={{ maxWidth: 560, display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <span style={{ display: 'inline-flex', width: 26, height: 26 }}>
+          <ProviderIcon icon={provider.kind} size={26} />
+        </span>
+        <h2 className="display" style={{ margin: 0, fontSize: '1.2rem', color: 'var(--head)' }}>
+          {provider.name}
+        </h2>
+      </div>
+
+      <Toggle checked={enabled} onChange={setEnabled} label="Enable this sign-in method" />
+      <HealthWarning provider={provider} />
+
+      <label style={{ display: 'block' }}>
+        <span className="field-label">Client ID</span>
+        <input type="text" value={clientId} onChange={(e) => setClientId(e.target.value)} className="input" autoComplete="off" />
+      </label>
+
+      <label style={{ display: 'block' }}>
+        <span className="field-label">Client Secret</span>
+        <input
+          type="password"
+          value={secret}
+          onChange={(e) => setSecret(e.target.value)}
+          className="input"
+          autoComplete="new-password"
+          placeholder={provider.hasSecret ? '•••••••• configured — leave blank to keep' : 'Client secret'}
+        />
+      </label>
+
+      <CallbackHint id={provider.id} />
+
+      <div style={{ display: 'flex', gap: 10, alignItems: 'center', marginTop: 4 }}>
+        <button onClick={save} disabled={busy} className="btn btn-primary btn-sq">
+          {busy ? 'Saving…' : 'Save changes'}
+        </button>
+        {msg && <span className="sans" style={{ color: '#7fd0a4', fontSize: '0.85rem' }}>{msg}</span>}
+        {error && <span className="sans" style={{ color: '#d98b84', fontSize: '0.85rem' }}>{error}</span>}
+      </div>
+    </div>
+  )
+}
+
+// ── Local accounts (informational) ─────────────────────────────────────────
+function LocalInfo() {
+  return (
+    <div style={{ maxWidth: 560 }}>
+      <h2 className="display" style={{ marginTop: 0, fontSize: '1.2rem', color: 'var(--head)' }}>
+        Local accounts
+      </h2>
+      <p className="sans" style={{ color: 'var(--muted)', fontSize: '0.9rem', lineHeight: 1.6 }}>
+        Username &amp; password sign-in (with optional TOTP two-factor) is always enabled and cannot
+        be turned off — it is how you manage accounts and link SSO identities. Manage users under
+        <strong> Users</strong>, and your own two-factor under <strong>Account</strong>.
+      </p>
+    </div>
+  )
+}
+
+// ── Custom OIDC/OAuth2 providers ────────────────────────────────────────────
+const EMPTY_CUSTOM = {
+  id: '', name: '', kind: 'oidc', enabled: false, clientId: '', secret: '',
+  authorizeUrl: '', tokenUrl: '', userinfoUrl: '', scopes: 'openid email profile', priority: 100,
+}
+
+function CustomEditor({ initial, onDone, onCancel }) {
+  const isNew = !initial.id
+  const [f, setF] = useState(isNew ? EMPTY_CUSTOM : { ...initial, secret: '' })
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState('')
+  const set = (k) => (e) => setF((prev) => ({ ...prev, [k]: e.target.value }))
+
+  async function save() {
+    setBusy(true)
+    setError('')
+    try {
+      const body = {
+        name: f.name, kind: f.kind, enabled: f.enabled, clientId: f.clientId,
+        authorizeUrl: f.authorizeUrl, tokenUrl: f.tokenUrl, userinfoUrl: f.userinfoUrl,
+        scopes: f.scopes, priority: Number(f.priority) || 100,
+      }
+      if (f.secret) body.secret = f.secret
+      if (isNew) await api.admin.createAuthProvider({ id: f.id, ...body })
+      else await api.admin.updateAuthProvider(initial.id, body)
+      await onDone()
+    } catch (err) {
+      setError(err.message || 'Could not save provider.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div style={{ border: '1px solid var(--line)', borderRadius: 10, padding: 20, marginTop: 16, display: 'flex', flexDirection: 'column', gap: 14, maxWidth: 640 }}>
+      <h3 className="display" style={{ margin: 0, fontSize: '1.05rem', color: 'var(--head)' }}>
+        {isNew ? 'Add custom provider' : `Edit ${initial.name}`}
+      </h3>
+      {isNew && (
+        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
+          <label>
+            <span className="field-label">ID (slug)</span>
+            <input className="input" value={f.id} onChange={set('id')} placeholder="authentik" />
+          </label>
+          <label>
+            <span className="field-label">Type</span>
+            <select className="input" value={f.kind} onChange={set('kind')}>
+              <option value="oidc">OIDC</option>
+              <option value="oauth2">OAuth2</option>
+            </select>
+          </label>
+        </div>
+      )}
+      <label>
+        <span className="field-label">Display name</span>
+        <input className="input" value={f.name} onChange={set('name')} placeholder="Authentik" />
+      </label>
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
+        <label>
+          <span className="field-label">Client ID</span>
+          <input className="input" value={f.clientId} onChange={set('clientId')} autoComplete="off" />
+        </label>
+        <label>
+          <span className="field-label">Client Secret</span>
+          <input className="input" type="password" value={f.secret} onChange={set('secret')} autoComplete="new-password" placeholder={!isNew && initial.hasSecret ? '•••• leave blank to keep' : ''} />
+        </label>
+      </div>
+      <label>
+        <span className="field-label">Authorization URL</span>
+        <input className="input" value={f.authorizeUrl} onChange={set('authorizeUrl')} placeholder="https://idp.example/application/o/authorize/" />
+      </label>
+      <label>
+        <span className="field-label">Token URL</span>
+        <input className="input" value={f.tokenUrl} onChange={set('tokenUrl')} placeholder="https://idp.example/application/o/token/" />
+      </label>
+      <label>
+        <span className="field-label">UserInfo URL</span>
+        <input className="input" value={f.userinfoUrl} onChange={set('userinfoUrl')} placeholder="https://idp.example/application/o/userinfo/" />
+      </label>
+      <div style={{ display: 'grid', gridTemplateColumns: '2fr 1fr', gap: 12 }}>
+        <label>
+          <span className="field-label">Scopes</span>
+          <input className="input" value={f.scopes} onChange={set('scopes')} />
+        </label>
+        <label>
+          <span className="field-label">Priority</span>
+          <input className="input" type="number" value={f.priority} onChange={set('priority')} />
+        </label>
+      </div>
+      <Toggle checked={f.enabled} onChange={(v) => setF((p) => ({ ...p, enabled: v }))} label="Enabled" />
+      {!isNew && <CallbackHint id={initial.id} />}
+      <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
+        <button onClick={save} disabled={busy} className="btn btn-primary btn-sq">
+          {busy ? 'Saving…' : 'Save provider'}
+        </button>
+        <button onClick={onCancel} disabled={busy} className="pill">Cancel</button>
+        {error && <span className="sans" style={{ color: '#d98b84', fontSize: '0.85rem' }}>{error}</span>}
+      </div>
+    </div>
+  )
+}
+
+function CustomProviders({ items, onChanged }) {
+  const [editing, setEditing] = useState(null) // null | 'new' | provider
+
+  async function del(p) {
+    if (!window.confirm(`Delete provider "${p.name}"? This cannot be undone.`)) return
+    await api.admin.deleteAuthProvider(p.id)
+    await onChanged()
+  }
+
+  return (
+    <div>
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 14, gap: 12, flexWrap: 'wrap' }}>
+        <p className="sans muted" style={{ margin: 0, fontSize: '0.9rem' }}>
+          OAuth2 / OIDC providers (Authentik, Keycloak, Okta, Azure AD, Zitadel, …)
+        </p>
+        {!editing && (
+          <button onClick={() => setEditing('new')} className="btn btn-primary btn-sq">+ Add provider</button>
+        )}
+      </div>
+
+      {items.length === 0 && !editing && (
+        <p className="sans dim" style={{ fontSize: '0.88rem' }}>No custom providers yet.</p>
+      )}
+
+      {items.length > 0 && (
+        <div className="panel-flat">
+          <table className="adm-table">
+            <thead>
+              <tr>
+                <th className="adm-th">Name</th>
+                <th className="adm-th">Type</th>
+                <th className="adm-th">Status</th>
+                <th className="adm-th" />
+              </tr>
+            </thead>
+            <tbody>
+              {items.map((p) => (
+                <tr key={p.id}>
+                  <td className="adm-td" style={{ color: 'var(--head)' }}>{p.name}</td>
+                  <td className="adm-td dim">{p.kind}</td>
+                  <td className="adm-td">
+                    {p.enabled && p.health.valid ? (
+                      <span className="sans" style={{ color: '#7fd0a4' }}>Live</span>
+                    ) : p.enabled ? (
+                      <span className="sans" style={{ color: '#e0b070' }}>Incomplete</span>
+                    ) : (
+                      <span className="sans dim">Disabled</span>
+                    )}
+                  </td>
+                  <td className="adm-td" style={{ textAlign: 'right' }}>
+                    <span className="link-accent" onClick={() => setEditing(p)}>Edit</span>
+                    <span className="link-accent" onClick={() => del(p)} style={{ marginLeft: 14, color: '#d98b84' }}>Delete</span>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {editing && (
+        <CustomEditor
+          initial={editing === 'new' ? {} : editing}
+          onCancel={() => setEditing(null)}
+          onDone={async () => {
+            setEditing(null)
+            await onChanged()
+          }}
+        />
+      )}
+    </div>
+  )
+}
+
+export default function AuthProvidersAdmin() {
+  const [providers, setProviders] = useState(null)
+  const [error, setError] = useState('')
+  const [tab, setTab] = useState('local')
+
+  const load = useCallback(async () => {
+    try {
+      setProviders(await api.admin.listAuthProviders())
+    } catch {
+      setError('Could not load authentication providers.')
+    }
+  }, [])
+  useEffect(() => {
+    load()
+  }, [load])
+
+  if (error) return <ErrorState message={error} />
+  if (!providers) return <Loading />
+
+  const byId = (id) => providers.find((p) => p.id === id)
+  const customs = providers.filter((p) => !p.builtin)
+
+  return (
+    <section>
+      <div style={{ display: 'flex', gap: 6, borderBottom: '1px solid var(--line-soft)', marginBottom: 24, flexWrap: 'wrap' }}>
+        {TABS.map((t) => (
+          <button
+            key={t.id}
+            onClick={() => setTab(t.id)}
+            className="sans"
+            style={{
+              padding: '9px 16px',
+              border: 'none',
+              background: 'transparent',
+              cursor: 'pointer',
+              fontSize: '0.9rem',
+              color: tab === t.id ? 'var(--head)' : 'var(--muted)',
+              borderBottom: `2px solid ${tab === t.id ? 'var(--accent)' : 'transparent'}`,
+              marginBottom: -1,
+            }}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+
+      {tab === 'local' && <LocalInfo />}
+      {tab === 'google' && <BuiltinForm provider={byId('google')} onSaved={load} />}
+      {tab === 'discord' && <BuiltinForm provider={byId('discord')} onSaved={load} />}
+      {tab === 'custom' && <CustomProviders items={customs} onChanged={load} />}
+    </section>
+  )
+}

client/src/routes/admin/views/BotActivityAdmin.jsx

@@ -0,0 +1,142 @@
+import { useCallback, useState } from 'react'
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import { useAsync } from '../../../lib/useAsync.js'
+import { dateTime } from '../../../lib/format.js'
+import { api } from '../../../api/client.js'
+
+// Read-only visibility into the botScore middleware: who is currently banned and
+// a feed of recent scoring events. The only action is an emergency unban for
+// false positives — there is no ban/adjust-weights surface here by design.
+const mono = { fontFamily: 'ui-monospace,Menlo,monospace', fontSize: '0.82rem' }
+
+export default function BotActivityAdmin() {
+  const [tick, setTick] = useState(0)
+  const reload = useCallback(() => setTick((t) => t + 1), [])
+  const { loading, error, data } = useAsync(() => api.admin.botActivity(), [tick])
+  const [busyIp, setBusyIp] = useState('')
+
+  const ips = data?.ips || []
+  const events = data?.events || []
+  const banned = ips.filter((e) => e.banned)
+
+  async function unban(ip) {
+    if (!window.confirm(`Unban ${ip}? This clears its score and ban immediately.`)) return
+    setBusyIp(ip)
+    try {
+      await api.admin.unbanIp(ip)
+      reload()
+    } catch {
+      // Surface nothing intrusive; a reload will re-fetch true state either way.
+      reload()
+    } finally {
+      setBusyIp('')
+    }
+  }
+
+  if (loading) return <Loading />
+  if (error) return <ErrorState message="Could not load bot activity." />
+
+  return (
+    <section style={{ display: 'flex', flexDirection: 'column', gap: 34 }}>
+      <p className="sans muted" style={{ margin: 0, fontSize: '0.9rem' }}>
+        Live, in-memory scoring and ban state from the bot-protection middleware. State resets
+        when the server restarts.
+      </p>
+
+      {/* Currently banned IPs */}
+      <div>
+        <h2 className="display" style={{ margin: '0 0 12px', fontSize: '1.1rem', color: 'var(--head)' }}>
+          Currently banned{banned.length > 0 ? ` (${banned.length})` : ''}
+        </h2>
+        <div className="panel-flat">
+          <table className="adm-table">
+            <thead>
+              <tr>
+                <th className="adm-th">IP</th>
+                <th className="adm-th">Score</th>
+                <th className="adm-th">Banned until</th>
+                <th className="adm-th" />
+              </tr>
+            </thead>
+            <tbody>
+              {banned.length === 0 && (
+                <tr>
+                  <td className="adm-td" colSpan={4} style={{ color: 'var(--muted)' }}>
+                    No IPs are currently banned.
+                  </td>
+                </tr>
+              )}
+              {banned.map((e) => (
+                <tr key={e.ip}>
+                  <td className="adm-td" style={{ ...mono, color: 'var(--head)' }}>
+                    {e.ip}
+                  </td>
+                  <td className="adm-td">{e.score}</td>
+                  <td className="adm-td dim">{dateTime(e.bannedUntil)}</td>
+                  <td className="adm-td" style={{ textAlign: 'right' }}>
+                    <button
+                      onClick={() => unban(e.ip)}
+                      disabled={busyIp === e.ip}
+                      className="btn btn-sq"
+                      style={{ borderColor: '#d98b84', color: '#d98b84', padding: '5px 12px', fontSize: '0.82rem' }}
+                    >
+                      {busyIp === e.ip ? 'Unbanning…' : 'Unban'}
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      {/* Recent scoring events */}
+      <div>
+        <h2 className="display" style={{ margin: '0 0 12px', fontSize: '1.1rem', color: 'var(--head)' }}>
+          Recent events
+        </h2>
+        <div className="panel-flat">
+          <table className="adm-table">
+            <thead>
+              <tr>
+                <th className="adm-th">When</th>
+                <th className="adm-th">IP</th>
+                <th className="adm-th">Reason</th>
+                <th className="adm-th">Path</th>
+                <th className="adm-th">Points</th>
+                <th className="adm-th">Score</th>
+              </tr>
+            </thead>
+            <tbody>
+              {events.length === 0 && (
+                <tr>
+                  <td className="adm-td" colSpan={6} style={{ color: 'var(--muted)' }}>
+                    No events recorded yet.
+                  </td>
+                </tr>
+              )}
+              {events.map((ev, i) => (
+                <tr key={`${ev.ts}-${ev.ip}-${i}`}>
+                  <td className="adm-td dim">{dateTime(ev.ts)}</td>
+                  <td className="adm-td" style={{ ...mono, color: 'var(--text)' }}>
+                    {ev.ip}
+                  </td>
+                  <td className="adm-td">
+                    <span style={{ ...mono, color: ev.type === 'ban' ? '#d98b84' : 'var(--accent)' }}>
+                      {ev.reason}
+                    </span>
+                  </td>
+                  <td className="adm-td dim" style={{ ...mono, wordBreak: 'break-all' }}>
+                    {ev.path || '—'}
+                  </td>
+                  <td className="adm-td dim">{ev.points ? `+${ev.points}` : '—'}</td>
+                  <td className="adm-td">{ev.score}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </section>
+  )
+}