From 83455c525ff40a6efed87b49d66f32a0938fafb6 Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Sat, 7 Feb 2026 23:50:55 -0500
Subject: [PATCH] Update commands doc with combat, content, and editor sections

Documents how combat moves are registered from TOML, how content-defined commands
work, and how editor mode captures input.
---
 docs/how/commands.txt | 55 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/docs/how/commands.txt b/docs/how/commands.txt
index 2221f97..e0571e0 100644
--- a/docs/how/commands.txt
+++ b/docs/how/commands.txt
@@ -58,6 +58,58 @@ adding commands
 4. call register(CommandDefinition(...))
 5. import the module in server.py so registration runs at startup
 
+combat commands
+---------------
+
+combat moves are defined in TOML files in content/combat/. each file describes
+a move (attack, defend, counter) with metadata:
+
+    name
+    type (attack/defend)
+    stamina_cost
+    telegraph (what the opponent sees)
+    timing_window_ms (how long to react)
+    damage_pct (base damage as % of attacker PL)
+    counters (list of valid defensive moves)
+
+the combat system loads these at startup and registers them as commands via
+combat/commands.py. when combat mode is active, these commands become available.
+players use the move name to execute it during their turn.
+
+content-defined commands
+------------------------
+
+commands can be defined in TOML files in content/commands/. these are loaded
+at startup by content.py and registered alongside python-defined commands.
+
+format:
+
+    name = "example"
+    aliases = ["ex"]
+    help = "example command help text"
+    mode = "normal"
+
+content commands currently require a python handler (body field pointing to a
+callable). when the DSL arrives, this will be replaced with inline scripting.
+
+editor mode
+-----------
+
+the edit command pushes editor mode onto the mode stack. while editor mode is
+active, all input bypasses the command dispatcher and goes to the editor buffer
+instead.
+
+the editor provides:
+
+    line editing with insert/append/delete/replace
+    search and replace (regex supported)
+    syntax highlighting for TOML/Python
+    save/discard changes
+    dirty flag tracking
+
+quit (:q) pops editor mode and returns to normal. the editor is implemented in
+editor.py and uses the mode stack to capture input.
+
 code
 ----
 
@@ -66,4 +118,7 @@ src/mudlib/commands/movement.py    direction commands
 src/mudlib/commands/look.py        look/l
 src/mudlib/commands/fly.py         fly
 src/mudlib/commands/quit.py        quit/q (mode="*")
+src/mudlib/combat/commands.py      combat move commands (loaded from TOML)
+src/mudlib/content.py              content loading (commands and combat moves)
+src/mudlib/editor.py               editor mode and buffer management
 src/mudlib/player.py               Player dataclass + registry