From cb006abcb8516e7e408240a6805d1bc7a117a71d Mon Sep 17 00:00:00 2001
From: OlegTheSnowman <123775785+OlegTheSnowman@users.noreply.github.com>
Date: Sat, 11 Jul 2026 00:08:19 +0300
Subject: [PATCH] Document the Gag Manager

Covers opening the menu (Alt+N), the 3-step gag creation flow (pattern,
method, category), the voice/full/substitute gag methods, and sharing
gags.lua between players. Also notes a real conflict found while writing
this: Alt+N is also bound to south-west movement by direction_plugin.xml,
and GagManager's later load order currently shadows it.
---
 readme.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/readme.md b/readme.md
index 44091e7..04a3acf 100644
--- a/readme.md
+++ b/readme.md
@@ -106,6 +106,39 @@ The soundpack mirrors game text into a separate notepad-style window titled "out
 - **Ctrl + Alt + Enter**: Toggle stopping speech whenever you press Enter
 - **Ctrl + 1** to **Ctrl + 0**: Recall a recent output line by position from the end (tap once to speak it, twice to copy it, three times to paste it into the command line)
 
+### Gag Manager
+- **Alt + N**: Open the Gag Configuration menu (see [Gag Manager](#gag-manager) below)
+
+
+## Gag Manager
+
+Gags let you hide or replace lines of game text you don't want to see or hear - spam messages, repetitive room text, anything cluttering your screen or your screen reader. Under the hood a gag is just a MUSHclient trigger, matched against incoming game text the same way any other trigger would be.
+
+### Opening the gag menu
+
+Press **Alt + N** to open the Gag Configuration menu. From there you can:
+
+*   **Create a new gag** - a 3-step walkthrough: the text to match, how to gag it, and which category to file it under.
+*   **Delete an existing gag** - pick from a list of everything you've gagged.
+*   **Toggle a whole category on or off** - Activity, Ship, Vehicle, or Misc gags, without deleting anything.
+
+### Creating a gag
+
+1.  **Pattern**: Type the exact text as it appears in-game. Use `*` as a wildcard - e.g. `* hugs you` matches anyone hugging you, `You receive *` matches any "You receive ..." line.
+2.  **Method**:
+    *   **Voice only**: Hidden from the screen and log, but your screen reader still reads it aloud. Good for things you want to hear but don't need cluttering the screen.
+    *   **Full gag**: Removed from both the screen and speech entirely.
+    *   **Substitute**: Replaces the matched line with your own text. Use `%1`, `%2`, etc. for wildcard matches and `%0` for the whole original line - e.g. pattern `* hugs you` with substitution `%1 pokes you` turns "warrior hugs you" into "warrior pokes you".
+3.  **Category**: Activity, Ship, Vehicle, or Misc. This only controls grouping, so you can toggle a whole category at once - e.g. turn off all Ship gags when you're not flying.
+
+### Sharing gags
+
+Your gags are saved to `gags.lua`, next to your world file (`worlds/Cosmic Rage/gags.lua`). It's a plain, human-readable file, so you can copy it to share your gag list with someone else or keep it as a backup. To load someone else's list, drop their `gags.lua` into your own `worlds/Cosmic Rage/` folder - this replaces your existing gags, so back yours up first if you want to keep it.
+
+### Known issue
+
+**Alt + N** is also bound to south-west movement by another plugin. Because Gag Manager loads after it, Alt+N currently opens the gag menu instead of moving you - southwest movement via that key doesn't work right now.
+
 
 ## FAQ