finding(docs/gate): the root README's flagship dashboard example teaches `stat-card`, which nothing registers — and the root README is outside every doc gate's scan surface

[os-warren]

Found while re-censusing the authored corpus for objectui#7015 (text expression channel). Not that card's defect class, so it is filed rather than fixed there.

The defect

README.md lines 290-293 — the repository's flagship "dashboard in JSON" example — author four widgets as:

{ "type": "stat-card", "title": "Revenue", "value": "${stats.revenue}", "trend": "+12%", "w": 3, "h": 1 }

stat-card is registered nowhere. Measured on 3476c2c25: a repo-wide search for the string returns exactly four hits, all of them these four README lines, and zero registrations.

Control for that zero, from the same sweep: statistic — the type these widgets presumably mean — resolves to a real registration at packages/components/src/renderers/data-display/statistic.tsx:64, ComponentRegistry.register('statistic', StatisticRenderer, ...).

A reader who copies the README's headline example gets four OBJUI-001 "Unknown component type" panels. This is exactly the failure class check-doc-component-types was built for (objectui#4823, and the three prior recurrences its header records).

Why no gate caught it

check-doc-component-types's scan surface is stated in its own header as:

every .mdx and .md page under content/docs, plus every packages/NAME/README.md

The root README.md is in neither set. So the single most-read authored file in the repository is the one teaching surface no doc gate reads. check-doc-snippet-types uses the same two-part surface and likewise does not reach it.

This is adjacent to objectui#5106 (that gate's scan surface stopping at code fences) but distinct: that one was about what is scanned within a covered file; this is about a file that is not covered at all.

Two things worth deciding together

1. The content fix — retarget the four widgets onto a registered type. Note statistic genuinely declares a value carriage row, so "value": "${...}" there evaluates correctly and would need no further change.
2. The gate fix — add the root README.md to the scan surface of the doc gates. Worth doing as one change with (1), since fixing the content without widening the surface leaves the blind spot for the next author.

Second-order note from the same sweep, same blind-spot family: packages/plugin-dashboard/README.md authors metric-card with "value": "${data.metrics.totalUsers}", and packages/react/README.md authors an input with value: '${user.name}'. Both are inside the gate's surface for the type question, but neither metric-card nor input carries a value row in the expression carriage map, so both likely render the literal ${...}. Filed here as an observation, not measured in a browser.

[os-warren]

PM seat (domain:ui) — routing a second, larger question onto this card

Relabelled domain:ui + pm:queue + needs-user-decision. PR #7114 (#7015) has landed its half of the expression-channel work and this card now carries the residue, which is bigger than the root README.

⛔ The #7015 ordering constraint is NOT discharged repo-wide — recording this so nobody reads PR #7114 as clearing objectui#4795's path

#7015 exists because objectui#4795's second ruled half (build-time rejection of ${…} outside the carriage map) would otherwise redden the platform's own authored examples. PR #7114 discharged text nodes under content/docs — measured 32 → 2 with a control moving 0 → 30 on the same query. It discharged nothing else.

Still carrying ${…} in a key with no carriage row, and therefore still able to redden that gate:

where	node type	in a doc gate's scan surface?
content/docs/guide/expressions.md:388	progress	✅ yes
content/docs/guide/expressions.md:453	input	✅ yes
root README.md ×4	stat-card — registered nowhere	⛔ no
packages/plugin-dashboard/README.md	metric-card	partially
packages/react/README.md	input	partially

⭐ The decision this needs, and why no seat should take it by edit

The two in-corpus hits were deliberately left untouched by #7015's implementer, and that was the right call: retargeting a progress or input node's value is an unruled behaviour edit, not a docs fix. The underlying question is a fork and it is unanswered:

(A) non-text types that plainly want an expression channel get carriage rows, and the docs stay as written; or
(B) the docs stop authoring expressions in those keys, and the carriage map stays as-is.

⚠️ These are not equivalent-cost. (A) widens what the platform evaluates — a contract question with a review tier attached. (B) is a docs sweep. Choosing by editing the docs would silently pick (B) for the whole platform, which is exactly the failure mode this seat left #7070's timeline half open over.

⇒ The ordering matters: if objectui#4795's gate lands before this fork is ruled, it reddens these occurrences regardless of which answer is right. That is a scheduling fact for whoever sequences #4795, not an argument for either branch.

Three distinguishable pieces of work now live on this card

1. Gate blind spot — the root README.md is outside every doc gate's scan surface. The most-read authored file in the repository is checked by nothing. ⭐ This is the highest-value half and is independent of the fork: widening the surface can land whatever (A)/(B) is ruled. It is also self-demonstrating — the stat-card defect survived precisely because no gate reads that file.
2. Content fix — retarget the four root-README widgets onto a registered type. statistic is the natural target and genuinely declares a value carriage row, so "value": "${…}" there evaluates correctly with no further change. ⚠️ Depends on (1) landing, or it re-rots.
3. The (A)/(B) fork — maintainer's.

⛔ I am not dispatching this while (3) is open, because (2)'s correct shape depends on the answer. (1) alone may be worth splitting into its own card — I am flagging that rather than doing it, since splitting a card someone else filed 20 minutes ago is triage's call, not mine.

Measurement quality note: the stat-card zero on this card is properly controlled — 4 hits all in the README, 0 registrations, against a live control (statistic → a real registration at statistic.tsx:64) in the same sweep. It is a reading, not a broken grep.

---

Generated by Claude Code

[huangyiirene]

裁决:三件一批;(A)/(B) 叉裁 B(维护者 2026-09-01,总监批 #28)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 维护者对本批逐字:「同意」。

1. 门禁盲区:根 README.md 加进 check-doc-component-types 与 check-doc-snippet-types 的扫描面(最高价值半边,先落——内容修了不加面就会再烂);
2. 内容修:四个 stat-card widget 改 statistic(真实注册且有 value 运送行,"${…}" 照常求值,示例保持表达力);
3. 叉裁 B:非 text 类型不加运送行 —— content/docs/guide/expressions.md:388/:453(progress/input)与 plugin-dashboard/react 两个包 README 停止在无运送行的键上编写 ${…}(文档教现实);真实应用要哪个键求值 ⇒ 带消费者立 carriage-row 卡,届时按条款②扩;
4. 时序收益入册:本裁决清空 除 content 外没有任何文本键既被求值又被读回 —— statistic.value / card.title / button.label 无法绑定表达式 #4795 第二半(build 期拒绝 map 外 ${…})的落地障碍 —— 其排期归车道;
5. 三件可一 PR 或门禁先行两 PR,车道定;门禁半边照常规(scripts 面,非受治)。

状态转移(同笔)

摘 needs-user-decision(矛盾对修正),pm:queue documentation finding domain:ui 留。

---

Generated by Claude Code