diff --git a/README.md b/README.md
new file mode 100644
index 0000000..df7156e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,22 @@
+# Hermes Completion Notification Sound
+
+Hermes Desktop plugin that plays a configurable melody when an agent turn completes.
+
+## Features
+
+- Custom Web Audio melody on `message.complete`
+- Volume control from 0 to 100%
+- Duration control from 0.1 to 5 seconds
+- Longer duration adds more notes to the melody
+- Preview button and enable/disable switch
+- Status-bar icon shows enabled/disabled state
+
+## Install
+
+Copy `plugin.js` to:
+
+```text
+<HERMES_HOME>/desktop-plugins/completion-notification-sound/plugin.js
+```
+
+Then run **Reload desktop plugins** from the command palette.