1 files changed, 60 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..42148f6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# panto-rsvp
+
+Rapid serial presentation for assistant replies. It presents the latest assistant text one newline-delimited paragraph at a time, omitting fenced code; it does not change ordinary transcript rendering.
+
+RSVP is an optional **focus mode**, not a comprehension or speed promise.
+
+## Install
+
+1. Add the rock to a layered `config.toml`:
+
+   ```toml
+   [extensions]
+   rocks = ["panto-rsvp"]
+   ```
+
+   For a local checkout, use `paths = ["/path/to/panto-rsvp"]` instead; panto's own LuaRocks tree must already provide `luv` (it ships with panto).
+2. Bind activation to Ctrl+S:
+
+   ```toml
+   [keys]
+   "ctrl+s" = "/rsvp"
+   ```
+
+3. Restart panto. Run `/rsvp` or Ctrl+S while idle to start the next unread paragraph.
+
+If `[extensions]` or `[keys]` already exists, add these entries to the existing tables rather than declaring them twice.
+
+## Controls
+
+- Ctrl+S: play the next unread paragraph while waiting; ignored during playback.
+- Space: pause or resume. Resume gives the current word a fresh interval.
+- `-` / `+`: adjust speed; changes apply to the next word interval.
+- Esc: leave. An unfinished paragraph remains unread and restarts on the next activation.
+
+The current word stays centered above the input, with speed and paragraph progress. Text arriving while a paragraph is playing does not change that paragraph's word snapshot. Progress resets on session replacement and is not persisted.
+
+## Settings
+
+Optional settings live in `[rsvp]`:
+
+```toml
+[rsvp]
+wpm = 250
+wpm_step = 25
+min_wpm = 50
+```
+
+| Setting | Default | Meaning |
+| --- | ---: | --- |
+| `wpm` | `250` | Initial words per minute; values below `min_wpm` start at the lower bound. |
+| `wpm_step` | `25` | Change per `-` or `+`. |
+| `min_wpm` | `50` | Lowest speed; `-` stops here. |
+
+All three values must be finite positive numbers. Theme changes re-render the active paragraph using the current Markdown display style.
+
+## Development
+
+```sh
+mise run check    # panto lua _selfcheck.lua
+```