diff --git a/plugin/README.md b/plugin/README.md
new file mode 100644
index 0000000..c7388f3
--- /dev/null
+++ b/plugin/README.md
@@ -0,0 +1,27 @@
+# WhisperGate Plugin
+
+## Hook strategy
+
+- `message:received` caches a per-session decision from deterministic rules.
+- `before_model_resolve` applies `providerOverride + modelOverride` when decision says no-reply.
+
+## Rules (in order)
+
+1. non-discord -> skip
+2. bypass sender -> skip
+3. end symbol matched -> skip
+4. else -> no-reply override
+
+## Config
+
+See `docs/CONFIG.example.json`.
+
+Required:
+- `noReplyProvider`
+- `noReplyModel`
+
+Optional:
+- `enabled` (default true)
+- `discordOnly` (default true)
+- `bypassUserIds` (default [])
+- `endSymbols` (default punctuation set)