diff --git a/README.md b/README.md
index 27cb7ac..3423db8 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,45 @@ Official [Dripnex](https://dripnex.app) plugin. Inserts a mermaid fence at the c
 
 Preview SVG rendering ships with the desktop app (`dripnex-mermaid`). This repo is the installable community surface (Inkdrop-style: one plugin, one git repo).
 
+## What it does
+
+Adds an **Insert Mermaid Diagram** menu item and the `mermaid:insert` command. Both insert this fence at the cursor:
+
+````markdown
+```mermaid
+flowchart LR
+  A --> B
+```
+````
+
+The plugin does not render diagrams. Preview rendering is built into Dripnex.
+
 ## Install
 
 ```
 dripnex/plugin-mermaid
 ```
 
-Or `dripnex-plugin install dripnex/plugin-mermaid`.
+Or:
+
+```
+dripnex-plugin install dripnex/plugin-mermaid
+```
+
+## Develop
+
+Source is CommonJS (`src/index.js`); the desktop app loads it with `new Function`. Entry point is `dist/index.js` (`manifest.json` `main`).
+
+```bash
+npm run build   # copy src/index.js → dist/index.js
+npm run pack    # dripnex-plugin pack .
+```
+
+## Contribute
+
+1. Fork this repo and create a branch.
+2. Edit `src/index.js` (keep CommonJS).
+3. Run `npm run build` so `dist/index.js` stays in sync.
+4. Open a pull request against `main`.
+
+MIT — see [LICENSE](LICENSE).