docs: bound optional heml editor overlays

Make hemx-build diagnostics and the documented .heml syntax surface the authority for any editor overlay, while rejecting a second template language, selector model, formatter, or custom editor framework.

req: diagnostics/004

AGENTS.md

@@ -57,6 +57,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file
 - Use `cargo run -p hemx-xtask -- app new PATH` for the generic page/form/keyed-row/notice starter, and `cargo run -p hemx-xtask -- app new --mobile PATH` for the phone-first starter with host capabilities, recovery truth, and release-kit commands. req: ceremony/005 req: ceremony/006
 - The public component-reuse explanation lives in `docs/recipes/reusable-partials.md`; do not grow a client component framework to explain partial composition.
 - The stable public `.heml` authoring surface lives in `docs/hemplate-syntax.md`; Hemlate examples must use that real hemplate syntax, not Vue/Handlebars sketches.
+- Optional `.heml` editor overlays must share authority with `hemx-build` diagnostics and `docs/hemplate-syntax.md`; do not create a second template language, selector model, formatter, or custom editor framework. req: diagnostics/004
 - JS runtime changes must preserve root-scoped lookup and avoid selectors, VDOM, expressions, and per-node listeners.
 - Host capability adapters must stay at the `hemx-host` boundary: they may call host APIs and return host events, but they must not mutate DOM or own app/domain state. req: host/002
 - Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, or stored `EffectBatch` truth without a proven reusable contract. req: local/001 req: local/002

REQUIREMENTS.md

@@ -675,6 +675,9 @@ what a valid business email is.
 ### req: diag/003
 003	Internal terms (`ResourceId`, `ScopeKey`, `EffectBatch`) must not appear in beginner-facing diagnostics unless `--verbose` is enabled.
 
+### req: diag/004
+004	Optional `.heml` editor overlays must treat `hemx-build` diagnostics and the documented `.heml` syntax surface as authority; they may present compiler-shaped diagnostics, completion, hover, and navigation, but must not own a second template language, formatter, selector model, or custom editor framework. [north_star]
+
 ---
 
 ## test

docs/diagnostics.md

@@ -57,6 +57,16 @@ Avoid beginner-facing messages that suggest `ResourceId`, `ResourceRef`, raw
 escape hatch is genuinely required, say that it is advanced and name the safer
 normal path first. req: public_api/002 req: public_api/005
 
+## Editor overlay boundary
+
+A `.heml` editor overlay is optional and subordinate to the compiler. It may read
+`docs/hemplate-syntax.md`, run or reuse `hemx-build` diagnostics, and present
+compiler-shaped diagnostics, completion, hover, and navigation for documented
+syntax and generated targets. It must not define a second template language,
+formatter, selector targeting model, JavaScript expression layer, or custom editor
+framework. If editor feedback disagrees with `hemx-build`, `hemx-build` wins.
+req: diagnostics/004
+
 ## Verification anchors
 
 Current recurring checks cover the most common classes: