The marketplace, the iOS client and the Android client are checked out beside
this repo and are invisible from inside it, so a change here could break one of
them with nothing in context to say so. CLAUDE.md now lists all three by
relative path, states what each is, and — the part that matters — names the
coupling: plugin-mobile-connector for the two clients, the manifest format for
the marketplace.
The marketplace row repeats the existing rule rather than softening it: the
authoring spec is CONNECTOR_MANIFEST_GUIDE.md in that repo, edited there and
never restated here. The mcp-connectors dev-doc now uses the same relative
path instead of an absolute one under a home directory.
CLAUDE.md had grown to 152 KB (~21k words, ~40k tokens) and is loaded into
every coding-agent session. The cost is not the cache read, it is attention:
the rules that are genuinely invariant were drowning in the mechanics of
subsystems that most tasks never touch.
The split criterion is blast radius, not importance. A rule a change anywhere
could violate stays in CLAUDE.md — the commit rule, the production/schema
constraint, domain neutrality, the event-bus rule, the crate boundaries, and
the module map. The mechanism of one subsystem moves to dev-docs/, opened on
entry to that subsystem via a routing table at the top of CLAUDE.md.
Nothing was rewritten: every section was moved verbatim by line range and
verified line-by-line against the original. The only edits are cross-reference
repairs ("see the DB section" -> a link), the promotion of headings in the
extracted files, and a condensed "Current state" whose full text now lives in
dev-docs/users-auth-and-boot.md.
CLAUDE.md: 152 KB -> 31 KB. Twelve subsystem files plus an index under
dev-docs/, which now carries the same standing rule as docs/ and CHANGELOG.md:
a change to a subsystem updates its dev-doc in the same change.
No CHANGELOG entry: this is documentation for coding agents with no observable
effect on the application.
Daniele