1 files changed, 82 insertions, 0 deletions
diff --git a/admin/reload.md b/admin/reload.md
new file mode 100644
index 0000000..5cfc5b9
--- /dev/null
+++ b/admin/reload.md
@@ -0,0 +1,82 @@
+# POST /reload
+
+[back to admin](README.md) /// [home](../README.md)
+
+Hotreload server configuration. Rereads all config files, merges with DB settings, rebuilds the permission system. All without downtime hopefully maybe.
+
+Requires power >= `min_reload_power` (configurable).
+
+## Request Body (optional)
+
+```json
+{
+  "restart": false,
+  "forced": false
+}
+```
+
+| Field     | Type    | Default | Notes                                    |
+|-----------|---------|---------|------------------------------------------|
+| `restart` | boolean | false   | schedule a full server restart (reexec)  |
+| `forced`  | boolean | false   | skip idle wait and restart immediately   |
+
+If you send no body at all the server just does a config reload without restarting.
+
+## Why restart?
+
+Some things might be unable to be hot reloaded because theyre baked in the oven at startup such as:
+- rate limiter settings
+- server port
+- database connection settings
+- scheduled queries
+
+For these feel free to do a full restart. A compliant server should reexec itself (same binary, fresh process).
+
+## Restart modes
+
+### Graceful restart (`restart: true, forced: false`)
+
+Schedules a restart that waits for a configurable idle period before actually restarting. If theres user activity the timer should reset so you dont pull the rug from under active users lol.
+
+Response:
+
+```json
+{
+  "success": true,
+  "message": "Configuration reloaded: server will restart after 30s of idle time...",
+  "request_id": "abc123",
+  "restarting": true,
+  "restart_wait_seconds": 30,
+  "note": "Server restart is scheduled to apply heavy config changes (rate limits)."
+}
+```
+
+### Forced restart (`restart: true, forced: true`)
+
+Restarts immediately, server should flush cached sessions to the database if it supports persistant sessions first (with a reasonable timeout so a dead DB doesnt block the restart) then reexec.
+
+Because the server dies before it can send a json derulo response back the client wont really get a response. Just fire and forget, then wait for jsonderulo to come back lol.
+
+Should require higher power than a normal reload (configurable via `min_manual_restart_power`).
+
+### No restart (`restart: false`)
+
+Just reloads config. Fast and safe.
+
+```json
+{
+  "success": true,
+  "message": "Configuration reloaded successfully (TOML + DB merged, RBAC rebuilt)",
+  "request_id": "abc123",
+  "restarting": false,
+  "note": "Rate limiter and scheduled query changes require a restart to take effect."
+}
+```
+
+## Error Responses
+
+| Code | When                                                    |
+|------|---------------------------------------------------------|
+| 401  | no token or invalid session                             |
+| 403  | power level too low (for reload or for restart)         |
+| 500  | config reload failed (bad config syntax, DB error, etc) |