diff --git a/nanobot/command/builtin.py b/nanobot/command/builtin.py
index 070aba5a..cd05b5b5 100644
--- a/nanobot/command/builtin.py
+++ b/nanobot/command/builtin.py
@@ -17,6 +17,12 @@ from nanobot.command.router import CommandContext, CommandRouter
 from nanobot.utils.helpers import build_status_content
 from nanobot.utils.restart import set_restart_notice_to_env
 
+# WebUI protocol contract for how a slash command participates in turn state:
+# - side_channel: returns control text without starting or ending an agent turn.
+# - finalize_active_turn: side-channel command that also closes the active UI turn.
+# - stop_active_turn: cancels the active turn; WebUI may intercept exact submits.
+# - agent_turn: always enters the normal agent path.
+# - agent_turn_with_args: no args is side-channel usage; args enter the agent path.
 CommandLifecycle = Literal[
     "side_channel",
     "finalize_active_turn",
diff --git a/webui/src/lib/types.ts b/webui/src/lib/types.ts
index 8733b8d4..ad61ddc8 100644
--- a/webui/src/lib/types.ts
+++ b/webui/src/lib/types.ts
@@ -781,6 +781,15 @@ export interface TranscriptionSettingsUpdate {
   maxUploadMb: number;
 }
 
+/**
+ * Backend-owned contract for how a slash command affects WebUI turn state.
+ *
+ * - side_channel: returns control text without starting or ending an agent turn.
+ * - finalize_active_turn: side-channel command that also closes the active UI turn.
+ * - stop_active_turn: cancels the active turn; exact submits may be intercepted locally.
+ * - agent_turn: always enters the normal agent path.
+ * - agent_turn_with_args: no args is side-channel usage; args enter the agent path.
+ */
 export type SlashCommandLifecycle =
   | "side_channel"
   | "finalize_active_turn"