docs: restructure the agent guidelines into CLAUDE.md, CONVENTIONS.md and guidelines/

[totally-not-ai]

What & why

The repository had two overlapping agent-facing documents: CLAUDE.md (operational + a grab-bag of coding rules) and DESIGN_GUIDELINES.md (design + browser integration + Javadoc + testing + commit hygiene). Rules were duplicated between them, some had drifted out of date, and there was no single place to look up "what must this change comply with".

This adopts the same three-layer structure that the web-components and flow-components repositories already use:

Layer	Purpose
CLAUDE.md	Operational essentials only — repository overview, key modules, build/test/format commands, and pointers to the other two layers.
CONVENTIONS.md (new)	The canonical, checkable rules. Read in full when authoring or reviewing code, and before committing or opening a PR.
guidelines/	Topical chapters with the design-level reasoning, read selectively per topic.

Nothing from DESIGN_GUIDELINES.md is dropped — it is split by topic and moved (git tracks it as a rename to guidelines/design.md).

CLAUDE.md

• Trimmed from a mixed operational/conventions document to overview, technologies, key modules and commands.
• Fixed stale content: flow-router was listed as a module although routing lives in flow-server; added flow-plugins.
• Build commands now use -pl <module> -am instead of cd <module> && mvn …, and the single-IT example names its module.
• Keeps the four always-applicable rules inline (spotless before every commit, commit type prefix, Fixes #issuenumber, no @since) so they are visible without following a link, and widens the CONVENTIONS.md read trigger to cover committing and opening a PR — not just authoring/reviewing.

CONVENTIONS.md (new)

Collects the checkable rules that were spread across both old files into sections: Public API, Nullability, Client-Side JavaScript, Build & Dependencies, Javadoc, Testing, Code Style, Commit & PR Hygiene. On top of the existing material it adds rules derived from recurring pull request review feedback:

• Build plugin dependency scoping — do not add dev-runtime artifacts as compile/runtime dependencies of a build plugin module (they land in the plugin classloader for every build, including -Pproduction, break offline builds and show up in SBOM audits); provided is not a valid workaround because Maven only loads compile/runtime into the plugin realm; derive provisioned tool versions from the project's own dependency tree.
• Extract a shared utility instead of copying a class or method between modules.

It also documents the optional type(scope): commit prefix form (fix(flow-client):, chore(deps):) that most of the history already uses, and the ! breaking-change marker.

guidelines/

File	Contents
overview.md	Index of the chapters, plus pointers back to CONVENTIONS.md and CLAUDE.md.
repository.md	Tech stack, every top-level Maven module (not a subset), build plugins, code style, blast radius.
architecture.md	State tree, DOM abstraction, client-server communication, routing, component development.
design.md	The Java API-shape material from DESIGN_GUIDELINES.md (renamed file).
browser-integration.md	Supported browsers, JS file location and globals, executeJs parameter passing, DOM event naming, signalling patterns, bootstrap-time data, capability detection.
documenting.md	Javadoc expectations, documenting wrapped browser APIs.
testing.md	Unit and integration test expectations, debugging failures.

Cross-links were tightened so the layers actually resolve: design.md now points at the browser-integration.md, documenting.md and testing.md chapters that the rest of the browser-API-wrapper material moved to, repository.md points at the Build & Dependencies rules, and the module map CLAUDE.md calls "full" now really is complete. No remaining references to DESIGN_GUIDELINES.md are left in the repository.

Notes for reviewers

• Documentation only — no Java, TypeScript or build files are touched, so there are no API changes and no tests to add.
• The main thing worth checking is whether the rules landed in the right layer: something a reviewer would flag in a PR belongs in CONVENTIONS.md; the reasoning behind it belongs in a guidelines/ chapter.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Test Results

 1 434 files  ±0   1 518 suites  ±0   1h 33m 15s ⏱️ - 3m 26s
11 879 tests ±0  11 811 ✅ ±0  68 💤 ±0  0 ❌ ±0 
12 197 runs  ±0  12 129 ✅ ±0  68 💤 ±0  0 ❌ ±0 

Results for commit e22300b. ± Comparison against base commit 824e297.