docs(guide): react-pages.md contradicts the framework's sources on four points — Tailwind styling, record:* scope, adapter.find options, and the block inventory

[os-elon]

Filed from the framework repo (objectstack-ai/objectstack) while porting
content/docs/guide/react-pages.md into the customer docs site as
content/docs/ui/react-pages.mdx — framework issue
#10210, PR
#10281.

The port was explicitly instructed to re-verify every claim against the framework's
sources rather than copy, and to report contradictions rather than silently pick a
side. Four came up. All were measured against objectstack@502dc6fe7; none was carried
into the new page.

This guide is not dead material — @object-ui/react-runtime's README links it — so the
divergence is live.

---

1. Tailwind styling — the guide teaches the primitive an ADR amendment retracted

The guide's headline react example styles with Tailwind:

<div className="grid grid-cols-2 gap-4">

and the "What is in scope" section instructs:

Layout containers are deliberately not injected. In react mode you compose layout
with real HTML and Tailwind [...] use <div className="flex gap-4">.

objectstack/docs/adr/0080-ai-authored-ui-jsx-source.md carries an explicit header
amendment:

Amendment (2026-06-30 — ADR-0065 styling correction). The "HTML + Tailwind"
framing for page source is superseded on styling. A page's source is runtime
metadata, so the console's build-time Tailwind never scans it — authored utility
classNames silently produce no CSS (the exact failure ADR-0065 was written to
prevent; the Task Desk modal's bg-black/50 backdrop rendered transparent). [...]
Do not author Tailwind classes in page source.

ADR-0065 gives the mechanism: the console's CSS scans only apps/console/src, there is
no safelist, so a class in page metadata renders only if it coincidentally appears in
objectui's own source.

Corroborating, in the framework repo:

• the generated react contract (skills/objectstack-ui/references/react-blocks.md):
  "Do NOT use Tailwind className in page source."
• packages/lint/src/validate-responsive-styles.ts raises style-classname-tailwind:
  "these are not compiled from metadata and will silently do nothing."
• all three real kind:'react' pages in examples/app-showcase contain zero
  className and style exclusively with inline style objects and
  hsl(var(--token)) colors.

This is the highest-cost item: a reader following the guide gets a page that renders
with correct structure, correct data, and no styling, and nothing reports anything.

The half of that paragraph that is still correct — layout containers are not injected
on the react tier — is confirmed by buildComponentScope in
packages/components/src/renderers/layout/react-page.tsx (if (!tag || cfg.isContainer) continue;). Only the "so use Tailwind" conclusion needs replacing.

2. record:* blocks are offered as an in-scope example, and the publish gate rejects them

The guide's scope table says:

The block tags come from the curated public contract (PUBLIC_BLOCKS), converted
from kebab-case to PascalCase: object-grid → <ObjectGrid>, record:details →
<RecordDetails>.

The tag mapping is accurate — buildComponentScope really does inject every public
non-container block, record:* included, so <RecordDetails> resolves at runtime. But
the framework withdrew the family from the tier (REACT_RECORD_BLOCK_ALTERNATIVES and
the ledger above it in packages/spec/src/ui/react-blocks.ts), and os validate now
fails the build on it. Measured against the real CLI:

 ✗ Author-time rules failed (1 issue)
 • page "showcase_renewals_pipeline" › RecordHighlights: RecordHighlights renders
 "record:highlights", which reads its record from the record context a record page
 mounts — a kind:'react' page never mounts one, so the block renders empty no matter
 how it is bound (its objectName/recordId are not read by the renderer).
 rule: react-block-needs-record-context

So the guide's illustrative example is the one tag class that cannot ship. Suggest
keeping the mapping rule and changing the example, plus a line noting the exclusion.

3. The Live data sample passes an option key the adapter does not read

adapter.find('showcase_project', { filters: [['status', '=', 'open']] })

filters is not a QueryParams key. packages/types/src/data.ts declares $select,
$filter, $orderby, $skip, $top, $expand, $search, $count, and
ObjectStackAdapter.find reads $filter (array form via translateFilterArray). An
unprefixed filters reaches no branch and is dropped, so the sample returns the
object's records unfiltered, with no error.

The framework's own react page uses the working spelling:
{ $filter: ['account', '=', sel] }.

4. The block inventory does not match the published contract

The guide lists the injected data blocks as <ObjectGrid>, <ListView>,
<ObjectForm>, <ObjectKanban>, <ObjectChart>, <ObjectMetric>, <Markdown>, and
demonstrates <ObjectGrid objectName pageSize={25}> and <Block type="object-tree">.

Two different things are being conflated, and both are true separately:

• the runtime scope is everything public and non-container, which is roughly the
  guide's list;
• the authored contract — what has published props, is checked by os validate, and
  is what an author (human or AI) should write against — is
  REACT_BLOCKS: ObjectForm, ListView, ObjectChart, Block. The generated
  contract's own footer routes the rest through the escape hatch: "Kanban/calendar/
  gantt/timeline/map of an object = <ListView navigation={…} /> with the matching
  visualization, or <Block type="object-kanban" …/>."

pageSize is also not a published prop on any of them (pagination is).

Suggest stating the two-tier distinction explicitly rather than listing tags, and
linking the generated contract as the prop authority.

---

What the port did

Resolved every point toward the framework's sources, and said so in the PR body rather
than quietly choosing. No file in this repo was touched — the framework card's scope
forbids it. The three claims the guide gets right and that were carried over, for the
record: the new Function / no-sandbox security boundary, the react-pages capability
plus OS_PAGE_REACT=off kill switch, and the implicit-export default source-shape
rule (verified against normalizeCode in packages/react-runtime/src/index.tsx).

[claude]

Claim: PM loop round 21
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5413-react-pages-contradictions
Worktree: objectui-issue-5413
Domain: repo:objectui
File surface: content/docs/guide/react-pages.md (stop on breach; explain in the report)
Container & model: M, mode:subagent
Clause-②: no — docs only
Serial constraints cleared: none; ⛔ do NOT edit content/docs/utilities/index.md (sibling card #5360 in flight)

---

Generated by Claude Code

[os-support-ai]

{
 "issue": 5413,
 "status": "done",
 "branch": "claude/issue-5413-react-pages-contradictions",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5462",
 "premise_still_valid": true,
 "summary": "All four contradictions still held on current main and all four came out SETTLED, so all four were fixed and none goes to the decision inbox. Re-measured against objectstack@f094214b3 and objectui@77f846a8b -- the card's pin 502dc6fe7 had moved 65 commits; nothing had been fixed upstream, so no axis is moot. (1) Tailwind: settled not by the ADR-0080 amendment's own status but by a live shipped rule -- packages/lint/src/validate-page-source-styling.ts, rule `page-source-className-tailwind`, fires on kind html/react/jsx, registered in authoring-rules.ts:741 (tier advisory), RELEASED in @objectstack/lint@11.5.0 whose changelog ec7175d says it 'corrects ... ADR-0080/0081 away from the HTML + Tailwind framing'; the amendment points back to ADR-0065 which is ACCEPTED. Replaced the teaching with the per-tier primitive and added a Styling section. (2) record:*: settled by validate-react-page-props.ts:913 REACT_BLOCK_NEEDS_RECORD_CONTEXT, severity ERROR, matched by TYPE PREFIX (so Block type='record:...' is caught too, broader than the card said); kept the accurate tag-derivation rule, added the exclusion + real error text + the REACT_RECORD_BLOCK_ALTERNATIVES table. (3) adapter.find: settled by convertQueryParams building a FRESH options object from $-prefixed reads only; filters: -> $filter. (4) inventory: settled -- REACT_BLOCKS is exactly ObjectForm/ListView/ObjectChart/Block vs a runtime scope of every public non-container block; stated as two tiers with react-blocks.md named as prop authority. Three of the card's own citations had drifted and are corrected in the PR body: the card's Tailwind corroborator (validate-responsive-styles.ts) never reads page source at all (counter-probed: zero occurrences of 'source'; it walks regions[].components[]), QueryParams lives in objectui not the framework, and the record gate is by type prefix not by the four withdrawn tags.",
 "tests": "All gates re-derived and re-run on the FINAL commit 42a1d7359 (git rev-parse --short HEAD after committing); exit code captured per gate, never through a pipe. objectui has no scripts/pm/dispatch-gates.mjs, so the list was derived from the two actual changed paths (content/docs/guide/react-pages.md, .changeset/react-pages-guide-source-contradictions-5413.md). EXIT=0 check-doc-component-types.mjs ('Every documented component type is registered' -- 183 doc files, 1054 code blocks, 887 type literals, 742 registered / 145 exempted); EXIT=0 check-doc-links.mjs ('Links are valid across 13 scan roots'); EXIT=0 check-control-bytes.mjs ('OK -- scanned 4521 tracked text files, skipped 85 binary'); EXIT=0 check-changeset-presence.mjs ('No source of a released package changed in this range, so no changeset is owed'); EXIT=0 check-changeset-no-major.mjs. Baseline was captured green BEFORE editing on doc-types and doc-links, so the post-edit green is a comparison, not an assumption. Standing clause: control-byte self-scan on the changed files with grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]' -- clean. ONE GATE NARROWED, DECLARED NOT SKIPPED: check:doc-snippets compiles every ts/tsx fence in a covered document against built dist/*.d.ts and react-pages.md IS covered (absent from UNGATED_DOCS -- verified, not assumed). Its only input from this file is a single tsx fence, and that fence is BYTE-IDENTICAL before and after: extracted programmatically from git show HEAD:<path> vs the working file, 1 ts/tsx fence before, 1 after, IDENTICAL: True, with its `doc-snippet: fragment` marker still on the line immediately above it. The gate's verdict on this file therefore cannot move, and CI runs it on a built tree regardless; running it locally would have required a full workspace build behind the shared verify lock for a provably unchanged input. NO ABLATION was run and none is owed: nothing here is a gate-can-fail claim -- this is prose plus jsx fences, and jsx is explicitly NOT in TS_FENCE_LANGUAGES ({ts, tsx, typescript}), so no fence I edited is compiled by anything. No test was skipped, disabled or quarantined. Per the 2026-08-10 ruling, CI convergence is left to the PM; no CI wait was performed.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #5461 (objectui, unassigned, no label -- concrete defect for PM triage): three objectui sources still teach the retracted 'HTML + Tailwind' page-source framing -- packages/types/src/layout.ts:616 (a PUBLISHED TSDoc on PageSchema.kind that ships in the .d.ts AND links this very guide, so it will contradict the guide once this PR lands) and packages/components/src/renderers/layout/react-page.tsx:24 and :49 on buildComponentScope. Exact analogue of objectstack#10286, which just fixed the spec side. Outside this card's declared file surface (content/docs/guide/react-pages.md only), so filed rather than fixed.",
 "filed as objectstack#10479 (unassigned, attached as a SUB-ISSUE of the already-dispatched objectstack#10288): examples/app-showcase/src/ui/pages/crm-workbench.page.ts passes `limit: 200` to adapter.find -- same dropped-option class as #10288, but a second file that #10288's stated fix ('top: 500 -> $top: 500 in both calls; no other change', both in renewals-pipeline.page.ts) does not reach. Searched first: #10288 and the closed objectstack#10470 were the only near-duplicates, and neither covers this call site."
 ]
}

---

Generated by Claude Code