docs(api): validate View Helpers section

[github-actions]

Summary

Agent-driven docs validation for the View Helpers section.

• Snapshot: docs/api/v4.0.0.json
• Edits scoped to: vendor/wheels/**/*.cfc (docblocks + narrow body fixes) and vendor/wheels/public/docs/reference/{scope}/{name}.txt
• Per-function status tracked in tools/docs-validation/state.json

Review checklist

• Each state.json entry with status: done has a sensible reference example file added or updated
• No CFC function signature changes (agent is forbidden from changing them — verify anyway)
• Any docblock/body edits hold up against the test suite
• state.json items with status: needs_human describe the open question in notes

[claude]

🔴 This PR adds vendor/wheels/public/docs/reference/controller/telfielditag.txt (note the stray i between telfield and tag) which is byte-for-byte identical to the correctly-named telfieldtag.txt also added in this PR. There is no telFieldITag view helper in Wheels — only telFieldTag (defined at vendor/wheels/view/formsplain.cfc:212) — and state.json only tracks function:telFieldTag with telfieldtag.txt in its files_changed, so the misnamed file is an untracked stray that will surface as a phantom reference page on the docs site. Please delete vendor/wheels/public/docs/reference/controller/telfielditag.txt before merging.

Extended reasoning...

What the bug is

The PR creates two new files for what should be a single helper reference:

• vendor/wheels/public/docs/reference/controller/telfieldtag.txt — the correctly-named reference for the telFieldTag() view helper.
• vendor/wheels/public/docs/reference/controller/telfielditag.txt — a misnamed duplicate (telfield + stray i + tag).

The two files are byte-for-byte identical (442 bytes each, diff produces no output). The trailing i in telfielditag is clearly an accidental keystroke, not a deliberate filename.

Why this slipped through

Looking at tools/docs-validation/state.json, the agent registered a single tracked entry:

"function:telFieldTag": {
  ...
  "files_changed": [
    "vendor/wheels/public/docs/reference/controller/telfieldtag.txt"
  ],
  ...
}

Only telfieldtag.txt is in files_changed. The telfielditag.txt file is not tracked by the docs-validation pipeline at all — it appears the agent wrote the file once with a typo, then wrote the correct file, but never deleted the bogus one.

Why existing code doesn't prevent it

There is no link checker that cross-references reference/controller/*.txt filenames against the actual function names exported from vendor/wheels/view/*.cfc. The PR's WRITE_GLOBS regex (in tools/docs-validation/lib/tools.mjs) accepts any [a-z][a-z0-9]+.txt filename in the controller directory, so a typo passes through unchallenged.

Step-by-step proof

1. diff vendor/wheels/public/docs/reference/controller/telfielditag.txt vendor/wheels/public/docs/reference/controller/telfieldtag.txt → produces no output (files are identical).
2. ls -l on both files → both are exactly 442 bytes.
3. grep -irn 'telFieldI\?Tag' vendor/wheels/view/ → only matches telFieldTag at vendor/wheels/view/formsplain.cfc:212 (function definition) and :223 ($args(name = "telFieldTag", ...)). No telFieldITag exists.
4. tools/docs-validation/state.json for function:telFieldTag lists only telfieldtag.txt in files_changed. There is no function:telFieldITag entry anywhere in the file.

Impact

1. Phantom doc page — depending on how the docs site enumerates reference/controller/ (e.g. by globbing *.txt), users may see a telFieldITag reference page that points to identical content as telFieldTag, confusing anyone searching the docs.
2. Silent rot — because the file is untracked in state.json, future docs-validation runs will not regenerate it. If the canonical telfieldtag.txt is updated, the stray will stay frozen at this version and slowly diverge.
3. Sitemap / link-checker confusion — any tool that walks the reference directory will treat both as valid documents.

How to fix

Delete the stray file before merging:

rm vendor/wheels/public/docs/reference/controller/telfielditag.txt

No other change is needed — the correctly-named telfieldtag.txt and the state.json entry are already correct.

[claude]

🔴 The newly added vendor/wheels/public/docs/reference/controller/telfield.txt was written with literal backslash-n sequences instead of real newline characters, so the entire ~700-character file is one unreadable line (wc -l returns 0 vs 10 for sibling files like urlfield.txt/emailfield.txt). The example block will render as one mangled line on the docs site rather than the three numbered examples. Fix: rewrite the file using real line breaks like its siblings.

Extended reasoning...

What's wrong

The new reference file vendor/wheels/public/docs/reference/controller/telfield.txt (added in this PR for the telField() view helper) contains the two-character sequence \ + n everywhere a line break should appear, instead of an actual 0x0A newline byte. As a result the whole file is a single ~700-character line.

Verification

$ wc -l vendor/wheels/public/docs/reference/controller/telfield.txt vendor/wheels/public/docs/reference/controller/urlfield.txt vendor/wheels/public/docs/reference/controller/emailfield.txt
   0 vendor/wheels/public/docs/reference/controller/telfield.txt
  10 vendor/wheels/public/docs/reference/controller/urlfield.txt
  10 vendor/wheels/public/docs/reference/controller/emailfield.txt

od -c confirms the bytes between examples are literal \ and n characters, not 0x0A:

0000100   r   t   y   `       -   -   -   >   \   n   #   t   e   l   F
0000220   "   )   #   \   n   \   n   <   !   -   -   -       A   d   d

The git diff for the file also shows it as a single line ending with the tell-tale \ No newline at end of file marker.

Step-by-step proof

1. Open the file: cat vendor/wheels/public/docs/reference/controller/telfield.txt
2. Observe a single line containing literal \n between examples instead of line breaks.
3. Compare with the file added for the same family of helpers, e.g. vendor/wheels/public/docs/reference/controller/urlfield.txt — that file has 10 real lines and renders as three numbered examples.
4. wc -l vendor/.../telfield.txt returns 0 (no newlines), while wc -l vendor/.../urlfield.txt returns 10.
5. od -c vendor/.../telfield.txt | head -5 shows \ followed by lowercase n (two chars), not the \\n shorthand od uses for an actual newline byte.

Why it matters

These reference files are consumed by the public docs site and by tools like cat/less/the IDE preview. The state.json summary describes the intent as "three idiomatic examples mirroring the textfield.txt reference" — that is not what readers will get. They'll see a single line of CFML wrapped with literal \n tokens, which is unreadable and obviously broken next to all the well-formatted siblings added in the same PR (urlfield.txt, emailfield.txt, colorfield.txt, datefield.txt, telfielditag.txt, telfieldtag.txt — all with real newlines).

Likely cause and fix

The writer agent appears to have passed a string containing the escape sequence \\n to the file-writer without that sequence being interpreted as newlines. The fix is to rewrite telfield.txt using real line breaks, mirroring the structure used by the sibling files added in this same PR. Note that telfielditag.txt and telfieldtag.txt (also added in this PR) have the intended content for telFieldTag correctly written with real newlines — telfield.txt is the only file with this corruption.