[dgesteves]

What and why

Roadmap item X2-23-onsystem (the onsystem part of X2-23, a compatibility statement for the three repos).

No compatibility statement. The README gave the Node.js floor in the Quickstart and the ESLint versions in passing, and nothing else: no list of what CI runs and nothing on TypeScript, React, Tailwind, shadcn/ui bases or MCP clients. This PR adds a short ## Compatibility table before ## Docs. Each row says only what package.json or CI shows:

• Node.js: 20.19 or later (engines). CI runs the tests on Node.js 22, 24 and 26, and the built package on 20.19.
• Operating system: Linux, macOS and Windows. CI runs the tests and the pack test on each.
• ESLint: 8.57, 9 and 10, for the ESLint plugin only. eslint is an optional peer.
• TypeScript: onsystem reads code with its own TypeScript 6.0, which is a dependency, not a peer. The project's TypeScript is not used.
• React: components written for React 18 (forwardRef) or 19 (ref as a prop). The tests cover both.
• Tailwind CSS: v4 @theme and v3 tailwind.config, or no Tailwind.
• shadcn/ui: both bases, Radix (asChild) and Base UI (render).
• MCP clients: any stdio client. pnpm smoke connects on the 2025-11-25 and 2026-07-28 protocols. The row links the clients page without an anchor, because X2-22-onsystem adds the support tiers table there.

Node 20 stays. The finding proposed dropping Node 20, which reached end of life on 2026-04-30. The owner decided to keep >=20.19: adopters run onsystem through npx in their own CI, the floor costs one CI job (node20), and dropping it would break those runs for no gain. The README says "Node.js 20.19 or later" and names the versions CI runs.

Dependabot is unchanged. The finding asked for one github-actions cadence across the three repos. onsystem's .github/dependabot.yml already checks github-actions monthly, like signoff-ui. ondocs is still weekly and moves to monthly in its own PR in wave 6. The npm ecosystem is weekly in all three repos, so it already matches.

README.md:78 was wrong about dist-only packages (the follow-up from the OS2-49 review, #194). The Quickstart said: "From a package that publishes only compiled code, installed apps get the token rules but no component, prop, variant or native-element checks." Since 0.9.0, an app on a package published as dist/ plus .d.ts gets every rule. I checked this on main before editing:

• test/installed-declarations.test.ts passes ("every rule runs in the app").
• A throwaway probe used a package set up the way init sets it up. With dist/index.d.ts, check reported no-unknown-component and prefer-design-system-component. With no .d.ts, it reported no-hardcoded-color only, plus "No design-system components found: the component rules did not run."

The sentence now says that apps read the components from the published sources, or from the type declarations when the package publishes only compiled dist/, and get every rule either way. Only a package with no type declarations gets the token rules alone. #202 (OS2-76) keeps the same "no component, prop, variant or native-element checks" wording in src/init.ts for that case, so the README and init still agree after it merges.

One file outside the listed boundary. test/readme.test.ts had a test that pinned the old sentence word for word. This PR updates that one test case so it checks the new sentence. No other wave 4 PR touches that file.

How it was tested

• New test/compatibility.test.ts, which reads package.json, .github/workflows/ci.yml, scripts/smoke.mjs and the installed MCP SDK's latest protocol version. It checks that:

  • the README's Node floor matches engines, wherever the README names one (the Compatibility section and the Quickstart);
  • the section names the CI test matrix, and the node20 job runs the floor;
  • the systems match the test, os and pack jobs;
  • the ESLint list matches the peer floor, the eslint-v9 alias and the eslint devDependency;
  • the TypeScript version matches dependencies.typescript, and TypeScript is not a peer;
  • the MCP protocols match what pnpm smoke connects with;
  • the section links the clients page.

• The updated case in test/readme.test.ts checks both halves of the dist-only sentence.

• On main, before the README edit, all 6 cases fail: 5 because there is no ## Compatibility section, and the README one because the Quickstart still has the old sentence. All pass after the edit.

• Gate, all passing: pnpm install --frozen-lockfile --prefer-offline, pnpm format:check, pnpm lint, pnpm typecheck, pnpm test (92 files passed, 1 skipped; 1136 tests passed, 3 skipped), pnpm build. I did not run pnpm smoke, because this PR does not touch the MCP server or tools.

• Tests cover the change, with realistic fixtures

• pnpm lint, pnpm typecheck, pnpm test and pnpm build pass (pnpm smoke not needed: no server change)

• A changeset (pnpm changeset) for a user-facing change: none, this is a docs-only change

• The docs (docs/*.md), the README, schema.json and .github/assets are updated if the change affects them

Follow-ups (not in this PR)

• X2-22-onsystem adds the support tiers to docs/clients.md, which the MCP clients row points to. Merge it with this PR or after it.
• docs/quickstart.md says "It needs Node.js 20.19 or later." That matches today, but it is owned by another PR, so the new test checks only the README.
• CONTRIBUTING.md says the tests run "on Node 22 and 24". CI also runs 26. X2-22 owns that file in this wave.
• X2-23-ondocs (wave 6) covers AI SDK 6 support in ondocs and moves its github-actions Dependabot cadence to monthly.