Document eDSL host-syntax principle - #1496

Reviewed at e8dd27ecb5c1b24d88ad40e38e49d92925d0c2e9.

This and #1495 are the same change written twice. Both insert ### 5.8 at the same
point in AGENTS.md from the same pre-image (f4164b61d), so they conflict by
construction: whichever lands first makes the other a conflict, and resolving that
conflict naively would leave two sections both numbered 5.8 stating the same
principle. 5.8 is correct as the next free number (main ends at 5.7 CLI parameters over environment variables), and the ## Contents list is top-level only, so no TOC
edit is needed either way.

Both are accurate and neither has a CHANGELOG obligation — §8.3 names AGENTS.md
explicitly. So this is only a question of which one to keep, and I'd keep this one:

The precedents it cites are checkable and they check out. fjs/types/rtti/types.ts
defines Type = Const | (() => readonly['const', Const] | Info0<Tag0> | Info1<Tag1, Type> | ...)
— a constant genuinely is its own schema, and array(number) genuinely is the case
that needs the thunk, so "constants can describe themselves, while constructions such
as array(number) need DSL syntax" is exact rather than illustrative. Same for the
NaNVM claim: Value = Const | Special with Info = ['function'] | ['ref', string] | ['throw']
is precisely "references, function values, and expected throws need special forms".
#1495 makes the same appeal to RTTI and the operator data in its PR body but not in
the text it adds, so a reader of AGENTS.md gets the rule without the evidence.

It states the layering as guidance, not just as permission. "Do not expose a
tagged-union AST as the authoring API merely because it is convenient for the
implementation… optimize the public eDSL for the person writing and reading it" is the
half of the principle that actually decides a design review. #1495 says only that the
two representations "do not need to be identical", which permits the layering without
saying which side the public API belongs on.

Its scope is safer. #1495 directs the principle at "HTML, BNF, RTTI" by name. BNF's
tagged encoding is deliberate and settled; naming it as a target reads as an invitation
to revisit it. "New eDSLs and when improving existing ones" avoids that without losing
any reach.

One ordering note if this is the keeper: the NaNVM operator-test data it cites arrives
with #1489, which is still open. Nothing breaks if this merges first — the text names no
paths and adds no links — but the precedent only becomes real once #1489 lands.

Still a draft, so no approval yet. Content-wise I have nothing against it.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d07450f2e8

Reviewed at d07450f2e86936fa66d615100802d3d8988a2ac5. Approving.

The duplication concern from my earlier comment is gone — #1495 is closed, so this is the
single version and the ### 5.8 collision can't happen. Against current main this is still
a clean 31-line addition: main ends at 5.7 CLI parameters over environment variables, the
new section lands at 426 and ## 6. Coding style follows at 459, so the numbering is right
and the top-level ## Contents list needs no edit. GitHub reports it mergeable, and §8.3
exempts AGENTS.md from a CHANGELOG entry.

The precedents it cites still check out on this tree. fjs/types/rtti/types.ts defines
Type = Const | (() => readonly['const', Const] | Info0<Tag0> | Info1<Tag1, Type> | …), so
"constants can describe themselves, while constructions such as array(number) need DSL
syntax" is exact rather than illustrative — array and number are both still real rtti
constructors. Broken relative markdown links are 144, identical to main.

Worth noting that #1498 has since become a second, independent piece of evidence for the
principle this section states. The JSON rtti schemas are exactly the "ordinary values, tagged
forms only where a literal can't express it" shape described here, and the practical lesson
that came out of that PR — that a recursive schema needs its neighbours named by typeof so
the emitted declaration stays exact — is the kind of thing this section's "keep the ergonomic
authoring syntax separate from the normalized machine-oriented representation" framing
anticipates.

The one thing I flagged before still stands and is still non-blocking: the NaNVM
operator-test data cited as a precedent arrives with #1489, which is open. No paths or links
are named, so nothing breaks if this merges first; the precedent simply becomes real later.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 269300224f