diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6f309ce
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,66 @@
+# CLAUDE.md — maubot-plugins
+
+## What this repo is
+
+Umbrella of plugins for [maubot](https://github.com/maubot/maubot), the
+Matrix bot framework. The maubot daemon itself is provisioned by
+`~/dev/deploy/server-deploy/modules/services/maubot.nix` on the castle
+hosts (currently cfaun). **This repo is the canonical place for
+plugin code; do not edit plugin code from a server-deploy session.**
+
+Layout: one subdir per plugin, each containing `maubot.yaml` + the
+Python sources. Built `.mbp` files are gitignored and live next to
+their source dir after `zip -j ../<plugin>.mbp ...`.
+
+## Where to find context
+
+- **Per-plugin docs:** `<plugin>/README.md` covers commands, schema,
+  quirks, etc.
+- **Repo-wide build/upload flow:** root `README.md`.
+- **Maubot patterns and footguns:** `~/dev/CLAUDE.md` under
+  "Maubot plugin development" — covers `database_type` semantics,
+  `@command.new` vs `@command.passive`, multi-line caveats, etc.
+  Read that before adding new plugins or non-trivial command
+  handlers; there are several silent-data-loss footguns.
+- **Daemon configuration / nginx / sops secrets:** in
+  `~/dev/deploy/server-deploy/modules/services/maubot.nix` and the
+  host's `sops.nix` / `secrets.yaml`. Don't edit those from here —
+  cross-repo coordination point.
+
+## Iteration loop
+
+Standard cycle when modifying an existing plugin:
+
+```sh
+cd <plugin>/
+# edit
+$EDITOR journal.py
+# bump version in maubot.yaml so the UI surfaces the new build
+$EDITOR maubot.yaml
+# zip
+rm -f ../<plugin>.mbp
+zip -j ../<plugin>.mbp maubot.yaml *.py
+# upload via maubot UI → Plugins → click existing → upload
+# then click into the instance and hit SAVE (toggling Enabled
+# alone doesn't persist — easy facepalm)
+```
+
+For brand-new plugins, also create the bot's Matrix account first
+(via Continuwuity registration token), add it as a Client in the
+maubot UI, then create an Instance binding the plugin to that
+client.
+
+## Commits
+
+Direct commits to `main` are the working convention while this stays
+single-maintainer. Conventional-commits style (`feat(<plugin>):`,
+`fix(<plugin>):`, `docs:`). Tag at deploy-ready boundaries if/when
+the repo ever needs publishable releases — for now, the maubot UI
+reads versions from the uploaded `.mbp`, not from git tags.
+
+## Pyright noise
+
+`maubot` / `mautrix` imports are unresolved in pyright + `.subcommand`
+"unknown attribute" warnings on decorator-extended functions are
+expected — the SDK is heavily dynamic and pyright can't introspect
+the decorators. Ignore these; they don't reflect runtime behavior.