diff --git a/README.md b/README.md
index e527f09..926497f 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,30 @@
 
 Rule-based no-reply gate for OpenClaw.
 
-## Status
+## What it does
 
-Initial scaffold.
+WhisperGate adds a deterministic gate **before model selection**:
+
+1. If message is not from Discord → skip gate
+2. If sender is in bypass user list → skip gate
+3. If message ends with configured end-symbol → skip gate
+4. Otherwise switch this turn to a no-reply model/provider
+
+The no-reply provider returns `NO_REPLY` for any input.
+
+---
+
+## Repo layout
+
+- `plugin/` — OpenClaw plugin (before_model_resolve hook)
+- `no-reply-api/` — OpenAI-compatible minimal API that always returns `NO_REPLY`
+- `docs/` — rollout and configuration notes
+
+---
+
+## Development plan (incremental commits)
+
+- [x] Task 1: project docs + structure
+- [ ] Task 2: no-reply API MVP
+- [ ] Task 3: plugin MVP with rule chain
+- [ ] Task 4: sample config + quick verification scripts
diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md
new file mode 100644
index 0000000..8bd0912
--- /dev/null
+++ b/docs/IMPLEMENTATION.md
@@ -0,0 +1,21 @@
+# WhisperGate Implementation Notes
+
+## Decision path
+
+WhisperGate evaluates in strict order:
+
+1. channel check (discord-only)
+2. bypass sender check
+3. message ending symbol check
+4. fallback to no-reply model override
+
+## Why before_model_resolve
+
+- deterministic
+- no LLM dependency
+- low overhead
+- uses built-in override path (`providerOverride` + `modelOverride`)
+
+## Known limitation
+
+This does not fully skip OpenClaw prompt assembly. It reduces provider-side LLM usage by routing no-reply turns to a deterministic API.