[dgesteves]

Roadmap item: X2-22-onsystem (the onsystem part of X2-22: support tiers and a 4-week integration freeze).

What was wrong

• docs/clients.md gave all 12 client setups, plus the plugins, the same standing. Nothing on the page said which had been run in the client. It has no "tested" or "verified" anywhere (grep -ciE 'tested|verified' gives 0). Seven of them (Cursor, VS Code, Claude Desktop, Windsurf, JetBrains, Zed, Antigravity) have never been run in their client by any commit, PR or CI job.
• CONTRIBUTING.md said nothing about holding new integrations back.

What changed

• docs/clients.md:
  • A new "Support tiers" section, before "How the server finds your project", which stays the last section. Tier 1, tested: CI runs it on every pull request, or the setup as the docs give it was run in the client and worked. Tier 2, documented: written from the client's docs, and not run in the client yet, or only installed. The table has one row per setup, with "Last checked" (the date and client version, or "Not yet") and "What was checked", linking the PR that shows it.
    • Tier 1: the MCP server over stdio (pnpm smoke and pnpm pack-test in CI), the Claude Code plugin and Claude Code without the plugin (Claude Code 2.1.299, docs(clients): lead with the setup; add Antigravity, Gemini folder trust, Copilot via the marketplace and one .mcp.json #185), Gemini CLI (0.64.0, docs(clients): lead with the setup; add Antigravity, Gemini folder trust, Copilot via the marketplace and one .mcp.json #185), and Agent Skills (skills 1.7.2, feat(plugins): package onsystem for Agent Skills, Agent Plugins 1.0 and Cursor #73).
    • Tier 2 with a partial check: Codex CLI 0.163.0 and Copilot CLI 1.0.98 (install only, docs(clients): lead with the setup; add Antigravity, Gemini folder trust, Copilot via the marketplace and one .mcp.json #185), and Grok Build 1.0.50 (grok mcp doctor connected, but under the package's old name, docs: add setup for GitHub Copilot CLI, Windsurf, JetBrains IDEs and Grok Build #34).
    • Tier 2, "Not yet": Cursor (its plugin passes Cursor's template validator, feat(plugins): package onsystem for Agent Skills, Agent Plugins 1.0 and Cursor #73, but was never run in Cursor), VS Code, Claude Desktop, Windsurf (Devin Desktop), JetBrains IDEs, Zed, Antigravity.
  • The intro links the table. A line under the table says that the CLI, the GitHub Action and the ESLint plugin run in CI on every pull request, and how to move a setup to Tier 1.
• CONTRIBUTING.md: a "New integrations" section after the intro. For the first four weeks after the public launch, no new integration (a client, a framework or another way to install or run onsystem) unless a user asks for it in an issue, with how to ask. It ends on a named date, Thursday 2026-11-19, four weeks after the 2026-10-22 launch. It links the tiers table and says how to move a Tier 2 setup to Tier 1.

No changeset: docs only.

Different from the brief

The brief's Tier 2 list includes Gemini CLI and Grok. #185 ran Gemini CLI 0.64.0 for real: gemini mcp add -s user ... wrote the documented entry, and gemini mcp list showed onsystem ... - Connected in a trusted folder. That is the same kind of check that puts Claude Code in Tier 1 (#185's claude mcp list with 2.1.299), so Gemini CLI is Tier 1 here. Grok Build stays Tier 2: #34's grok mcp doctor found the 5 tools, but that was before the rename to onsystem, so the setup as the page gives it now has not been run. The dates are the author dates of the commits that recorded each check: 2026-10-16 for the Gemini, Codex and Copilot runs (ebf5edd) and 2026-10-21 for the Claude Code runs (ffd8a7e).

How it was tested

test/support-tiers-docs.test.ts, new. All 7 tests fail on main (7 of 7) and pass on this branch. It checks:

• the table has a row for every <details> client on the page, plus the Claude Code plugin and Agent Skills, with no duplicates;
• every row is Tier 1 or 2. "Every pull request" rows are Tier 1 and name the pnpm command. "Not yet" rows are Tier 2. A dated row gives the client version and links the pull request that shows the check;
• the Tier 1 setups are exactly the five above, and the seven unrun clients say "Not yet". A setup that moves to Tier 1 has to update this list too, which CONTRIBUTING.md says;
• the intro links #support-tiers;
• CONTRIBUTING.md has the "New integrations" section, with the four-week wording, the issue link and the link to the tiers anchor, and no year in it.

Gate, all passing: pnpm install --frozen-lockfile --prefer-offline, pnpm format:check, pnpm lint, pnpm typecheck, pnpm build, pnpm test (92 files passed, 1 skipped; 1137 tests passed, 3 skipped). The existing test/clients-docs.test.ts, test/rollout-docs.test.ts and test/docs.links.test.ts pass unchanged. Site: pnpm --filter site generate and pnpm --filter site test (17 files, 272 tests). I also rendered /docs/clients with renderToStaticMarkup, as site/test/clients-page.test.ts does. The output has one table with the 15 rows, the PR links, /docs/ci and /docs/eslint, and the intro link to #support-tiers. The h2 order is: plugins-for-other-agents, cursor-and-vs-code, other-clients, support-tiers, how-the-server-finds-your-project, search-these-docs-from-your-agent. I did not run next build or open the page in a browser.

Follow-ups (outside this PR's files)

• VS Code's team file stays as main has it (.vscode/mcp.json). VS Code's docs label .vscode/mcp.json deprecated, but offer the workspace-root .mcp.json only behind the experimental chat.mcp.workspaceRootConfig.enabled setting, and do not say what happens when both files exist. The tip box (VS Code starts the server from the root .mcp.json) and docs/rollout.md:82 (commit .vscode/mcp.json) can still give a team both files. Settle it after a run in VS Code, which also moves VS Code to Tier 1.
• Before launch, an hour in Cursor and VS Code, the clients the launch copy names, would move them to Tier 1 (the finding's own suggestion).