[dgesteves]

Roadmap item: OS2-34 (findings os-site/os-agent-setup-prompt and os-site/os-playground-phone-findings). Site and docs only: no release, no changeset. The roadmap schedules it for Fri 23, not Thu 22.

What was wrong

• No setup path for agents. @shadcn/lint's quickstart is one prompt to paste into an agent ("Read …/SETUP.md and set up @shadcn/lint in this project"). onsystem had no such prompt anywhere, and llms.txt had an Install list but no step-by-step setup: it never mentions init. https://onsystem.vercel.app/setup.md returns 404.
• Phones don't see the playground's findings. At 390x844 on main, the editor (Agent draft) starts at y=542 and is 1,355 px tall, and the Findings panel starts at y=1,989: 2.4 screens down. The status in the editor bar ("8 errors · 3 warnings") is a plain span, not a link. (Measured with Playwright against next dev on main.)

What changed

• /setup.md (site/app/setup.md/route.ts, built from setupMd() in site/lib/llms.ts, static): the steps an agent follows.

  1. Look at the project: React, the Node.js version, the package manager, installed dependencies, and the folder CI will check.
  2. npx -y onsystem init --yes for the config and the baseline. If a config already exists, keep it (no --force), and if there is no onsystem.baseline.json beside it, record one with npx -y onsystem check . --update-baseline. This is the case after quickstart step 1, where the user runs init by hand and it only offers the baseline. If no design system is found, inspect --explain, then --components/--tokens.
  3. Add it to the agent it runs in: the Claude Code plugin in .claude/settings.json, .cursor/mcp.json, .vscode/mcp.json, the Codex plugin commands, the stdio command for any other client, and the AGENTS.md line.
  4. The GitHub Action workflow.
  5. check . --require-design-system, with what each exit code means: 0 passes; 1 means errors that are not in the baseline, which the agent lists for the user and does not fix; 2 means no design system or an unreadable config, so back to step 2. Then the report to the user.

  The configs and the workflow are taken from the titled blocks in docs/rollout.md and docs/required-check.md at build time, so they cannot drift from the docs. The Codex commands are CODEX_COMMANDS in site/lib/site.ts, which the home page's Codex tab and /setup.md both use, and tests check them against docs/clients.md. Every command uses npx -y: without it, npx asks before it installs, and an agent's terminal cannot answer.

• The prompt, Read https://onsystem.vercel.app/setup.md and set up onsystem in this project., is in:

  • the home page's first screen: "Or ask your agent to set it up" with a copy button, on the same row as "Try it in the browser". A <label> wraps the text and the CopyButton, so a click on either copies, and the full prompt is the label's title and in the button's accessible name. Touch screens never show a title, so below sm (640 px) the label also shows the prompt it copies, in quotes, on the line under the control. From sm up that line is hidden and the control stays on one line.
  • step 2 of the quickstart (docs/quickstart.md), as a titled block to copy, before the per-agent options.
  • llms.txt, with a line that sends agents to /setup.md.

• Playground on phones (site/components/playground.tsx): below lg, when the check has findings, the editor bar's status becomes a "Jump to 11 findings ↓" link to #findings, which is now the Findings section's id. It lands with the section 80 px from the top, below the sticky header, and "Apply 9 fixes" at 125 px. From lg up the bar still shows the counts, since the findings sit beside the editor. While a check runs, with no findings, or after an error, the bar shows the status as before.

First screen, measured on next start against main (fed7086):

	main	this branch
1440x900: install tabs top	586	584
1440x900: proof row bottom (fold at 900)	877	875
390x844: finding card top	645	713

On a phone the row wraps and the prompt takes two lines, so the card starts 68 px lower, still inside the first screen. From sm up the prompt stays in the title and the button's name only, which keeps the 1440x900 first screen as it was.

How it was tested

New tests. The site tests fail on main, where /setup.md and the prompt do not exist; the baseline and exit-code cases also fail on this PR's first commit. The root test checks that the commands /setup.md gives do what it says.

• site/test/setup.test.ts: /setup.md is static Markdown; its five steps; the commands it gives (init --yes, inspect --explain, check . --update-baseline, check . --require-design-system, check . --ignore-baseline); the --update-baseline line for a config with no baseline, and what exit codes 0, 1 and 2 mean; one entry per agent; no npx without -y in the prose; the configs, the workflow and the plugin and Codex commands word for word as the docs have them; absolute links that resolve to docs pages and their headings; the prompt in quickstart step 2 and in llms.txt.
• site/test/first-screen.test.ts: the prompt control comes after "Try it in the browser" and before the card, in the same flex-wrap row, and copies the prompt; below sm it shows the prompt in full (sm:hidden, on its own line).
• site/test/playground.test.ts: the editor bar links to #findings with "Jump to 11 findings" and is lg:hidden; the counts are max-lg:hidden; the Clean draft has no link.
• test/setup-steps.test.ts: runs the commands /setup.md gives on copies of the demo app, with no terminal, as an agent would:
  • with no config: init --yes writes the config and the baseline and prints the counts by rule; check . --require-design-system then exits 0; --ignore-baseline lists the findings; a second init --yes exits 2 and says the config exists.
  • with the demo's config and no baseline (the user ran init by hand and declined the baseline): init --yes exits 2 ("already exists"), check . --require-design-system exits 1, check . --update-baseline exits 0 and records 10 findings in 1 file, and the check then exits 0.
  • with no design system found: init --yes exits 2, and --components/--tokens then work.

Gate, all passing: pnpm install --frozen-lockfile --prefer-offline, pnpm format:check, pnpm lint, pnpm typecheck, pnpm test (72 files passed, 1 skipped; 943 tests passed, 3 skipped), pnpm build. Site, as CI runs it: pnpm --filter site generate, test (16 files, 269 tests), typecheck, lint, build. The build lists /setup.md as static. pnpm smoke was not run: the MCP server and tools are unchanged.

In a real browser (Chromium 1248 through playwright-core 1.64.1, on next start of the production build), at 390x844 (touch) and 1440x900, light and dark, for this revision:

• No horizontal scroll on / or /playground. The prompt control has nothing past the page edge at 320, 639, 640, 1023 and 1024 px; its prompt line shows at 639 px and is hidden from 640 px.
• Tapping the prompt's text at 390 and clicking the label's text at 1440 each copy the exact prompt.
• Cumulative layout shift at load, the highest of 3 runs per page, size and theme: 0 on / and /playground at 390; at 1440, 0.0017 on / and 0.0044 on /playground. main gave the same highest figures. The shift on /playground at 1440 is text nodes re-laid out about 42 ms after navigation starts, which looks like the font swap.
• /setup.md is served as text/markdown; charset=utf-8.

From the first commit, for the playground, which this revision does not change: the jump link shows below 1024 px and the counts from 1024 px (checked at 1023 and 1024), and the editor bar stays 36 px tall through a re-check ("Checking…", then the link again).

Not part of this change: at 320 px, the How it works cards on the home page overflow by 8 px. They were not touched here.