[albertwoo]

What this does

CUI 1.4 shipped the instrument components and documented itself in the headers. This takes both, and then fixes what the first pass left in the documentation it carried.

Four commits, in order:

c232b49	Sync to CUI 1.4 and draw the instruments
0306ec5	Carry CUI's documentation out to the C# developer
07fcd9e	Take the last junk out of the documentation, and close three override holes
c88f5dc	Rename sync-cui to cui-sync, and give the runbook a faster start

1. CUI 1.4 (5a9c12b)

DotChart, EventTrack, Readout and DotDisplay reach C#, on a new gallery page (29). The generator learned record arrays, double arrays and in-place primitive arrays, and a new override: a capacity is the array's length, so it leaves the signature and the wrapper passes .Length — two numbers for one buffer is a buffer overrun the type system cannot see. That is the only public surface this release removes (CurveEditor, GradientEditor, KvEditor, QueryBuilder, EventTrack); the only one it adds beyond the new components is DotChart taking ReadOnlySpan<DotSeries>, the way every other chart takes its series.

Seven public …Count fields also went, derived from their array instead.

2. Documentation

The generator used to read one of the five places CUI writes documentation: the comment above a declaration. It now reads all of them — above the declaration, beside it (CUI_API void cui_spacer(...); /* flexible space */, which libclang does not attach), above the definition in the C source, the paragraph above the options struct, and the paragraph above an item record or enum when the widget is the only reader of it. Measured on the artifacts a consumer sees:

	before	after
struct fields documented only by their C type	2001	786
wrapped functions whose summary is only cui_button_ex	206	94
DotChartOpts.Unit	const char * unit	after values in the readout, e.g. "MG"
BlameOpts	cui_blame_opts	Source with who last changed each line…

Two things are never a summary, and ShippedDocTests fails if either reaches the package's XML: a section title bar (---- Terminal ----, which libclang attaches to the declaration beneath it) and a note CUI writes to its own next reader (left to right in any interface: see cui__keep_ltr, which had become the summary of fifteen widgets including ui.CodeEditor and ui.Gantt).

The tests read the summaries through their XML nodes rather than XElement.Value, which silently drops <paramref> and <see> — and they assert on CuiSharp.xml, the file an IDE reads, not on the generator's own output.

3. Override holes closed

Each failed silently before: capacityParams had no entry in ValidateOverrides (a typo'd array name passed and left a count meant for nothing); PrimitiveElement spelled a bool element byte while the span said bool, which would have emitted an uncompilable CopyTo; ReadBeside parsed a wrapped declaration's first line twice.

4. cui-sync

Renamed from sync-cui, and restructured for a shorter start: 162 lines of procedure, with the binding rules and the error→override table in references/bindings.md and the traps in references/traps.md, each read only when the runbook points at it. New scripts/sync-status.ps1 answers "where does this sync stand" in one command — pinned tag vs newest, version drift across the three places it lives, the coverage totals, and whether the numbers quoted in README.md and bindings/README.md still match coverage.txt. It exits 1 on a PENDING or a stale number; run against this branch it found nine stale numbers, all corrected here.

Verification

Every gate ran against this tree, and printed its own success line:

• dotnet build -warnaserror, dotnet test — 1 002 tests (974 + 28), format clean
• tools/regen.ps1 -NoNative -NoDiff — no diff, 15 generator contract checks (one new), export-api: no diff
• tools/api-surface.ps1 — reviewed by set difference: 8 removals, all four capacity parameters
  (CurveEditor, GradientEditor, KvEditor, QueryBuilder, in both their extension and static
  form); 79 additions. Seven friendly …Count fields also went, and a line-set difference cannot see
  those — other structs still carry identically-shaped field Int32 …Count lines — so they were
  checked per struct instead.
• tools/verify-template.ps1 — 83.5 s, pack → new → build → test → AOT → dotnet cui
• AOT gallery 2 918 400 B, zero IL2xxx/IL3xxx; every shape inside its SIZE.md budget
• frames 0.83 ms mean, p50 0.70, p95 1.16, 0 B allocated per frame
• sync-status.ps1 exits 0

Review notes

• docs/API-SURFACE.txt is the approval file — review it by set difference, not by reading. Note the
  blind spot above: a field whose shape exists elsewhere in the surface does not show as removed.
• bindings/coverage.txt: 496 functions, 0 PENDING, 175 MANUAL each naming its member and file.
• The one behaviour worth a second look is the in-place array copy-back: a primitive array is copied back every frame even when the override carries changedWhen, because native sorts and clamps in place and the index it reports refers to its order. Only the record conversion is gated, because that is the one that allocates. InstrumentTests.TheEventTrackSortsAndClampsTheEventsItWasGiven pins it.