docs: record the coupling with qtmaildirHEADmaster

mailrules.py and qtmaildir's src/tagrules.cpp are two implementations of
one format, so a schema change is a two-repo change: a field added on one
side is silently dropped when the other saves.

Also notes that post-new is installed and live, so a change here reaches
real mail on the cron timer rather than when someone next runs a command.

1 files changed, 31 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index db9ca07..eb47322 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,37 @@ depends on how it behaves, so the constraints on the script are all over
 there. Sync and organization stay separate here exactly as before; there is
 simply nothing to sync with in this tree.
 
+**This tool has a sibling, and one file couples them.** `qtmaildir`
+(`../qtmaildir`) is a Qt6 GUI over the same notmuch index. The two are
+independent except for `~/.config/mailrules/rules.json`, the auto-tagging rule
+store: `mailrules.py` here and `src/tagrules.cpp` there are **two independent
+implementations of one format**, agreeing by test rather than by shared code.
+Both preserve fields they do not understand, which is what keeps the file owned
+by neither.
+
+Consequences for work in this repo:
+
+- **A change to the rule format is a two-repo change.** A field added here and
+  not there is silently dropped the next time the other tool saves. The full
+  procedure is under "Changing the shared rule format" in
+  `../qtmaildir/CLAUDE.md`, and the design is
+  `../qtmaildir/docs/superpowers/specs/2026-08-12-tagging-rules-design.md`.
+- **`post-new` is live.** It is installed at `<database.path>/.notmuch/hooks/`
+  and runs on every sync, so a change here reaches real mail on a ten-minute
+  timer, not when someone next runs a command. `post-new.shell-backup` beside it
+  is the original hand-written hook, kept as the escape hatch.
+- **Two hook properties are safety-critical.** It refuses to remove `unread` or
+  `inbox`, and it does not consume the `tag:new` marker when the rules fail to
+  load. The reasoning is in the hook's own comments; weaken neither without
+  reading them.
+- **Rule editing stays out of this tool**, deliberately. `mailrules.save()`
+  exists because both tools must agree on the write semantics, but no CLI
+  surface reaches it: a rule edit is a mutation whose blast radius is every
+  future sync, and the gate for that is not designed. qtmaildir has the editor.
+
+Nothing else is shared. This tool never imports from qtmaildir, and qtmaildir
+never invokes it.
+
 ## Installation
 
 No installer, just copy files into place: