From 69235cac5b3da5ff0dc20310e7474cabd8e63ba3 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Tue, 15 Sep 2026 20:14:02 -0400
Subject: feat: route all html editor API mutations through single owner task

---
 building_guide/admin.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'building_guide/admin.md')

diff --git a/building_guide/admin.md b/building_guide/admin.md
index 05363d5..9805ef7 100644
--- a/building_guide/admin.md
+++ b/building_guide/admin.md
@@ -266,6 +266,23 @@ the game server and is configured in `config.yaml` under `admin_http` (plain HTT
 All CRUD editors support undo/redo (persisted to `data/.admin_history.json`), so changes can be reverted
 even across sessions.
 
+#### Live editing and maintenance
+
+Editor API requests (including undo/redo) execute as one game-owner task:
+file writes and their runtime callbacks/reloads cannot interleave with a tick
+or player command. Large edits briefly pause gameplay; slow browser uploads
+and downloads do not. Requests are limited to 8 MiB and rejected during game
+shutdown. See [Concurrency & durability](concurrency.md#admin-editor-isolation)
+for the endpoint inventory and developer rules.
+
+This does not make every edit automatically hot-reloadable. Existing reload
+requirements still apply to definition editors and raw Files edits. Use the
+structured room rename/insert/remove tools for live structural changes; raw
+YAML/file renames do not migrate player or casino state. Stop the game before
+external bulk file edits, and prefer a maintenance window for major world
+reorganizations. A browser timeout does not necessarily mean an edit failed:
+check the current state before retrying.
+
 #### Map Interface
 
 The map page (`/`) is the main navigation hub:
-- 
cgit v1.2.3