docs(clients): lead with the setup; add Antigravity, Gemini folder trust, Copilot via the marketplace and one .mcp.json

[dgesteves]

Roadmap item: OS2-28.

What was wrong

• /docs/clients, the setup page for everyone not on the Claude Code plugin, opened with a 253-word paragraph on protocol eras, roots deprecation and project discovery before any setup.
• Gemini CLI starts MCP servers only in trusted folders, and the docs did not say so. With the config written as the docs showed, gemini mcp list (Gemini CLI 0.64.0) printed "Warning: MCP servers are configured but disabled because this folder is untrusted." and ○ onsystem: ... - Disabled. There was also no gemini mcp add one-liner.
• Antigravity CLI replaced Gemini CLI for unpaid-tier and Google One users on June 18, 2026, and keeps its MCP servers in mcp_config.json. The docs did not cover it.
• The documented Copilot CLI plugin install (copilot plugin install dgesteves/onsystem:plugins/onsystem-agent) prints "Direct plugin installs (repos, URLs, local paths) are deprecated." (Copilot CLI 1.0.98).
• The one .mcp.json that several clients read was only shown under "Claude Code without the plugin".

What changed

• docs/clients.md:
  • The page now opens with one line: "Pick your client below and add the server. Run it from the project, or pass --root ...".
  • A tip box near the top has the one .mcp.json to commit. It names the clients that read it (Claude Code, VS Code, GitHub Copilot CLI, Grok Build), says it needs no --root, and says Claude Code teams should use it instead of the plugin, not as well.
  • The protocol and project-discovery text moved, unchanged apart from being split into three paragraphs, to a closing "How the server finds your project" section. The lead links to it.
  • Gemini CLI gets the gemini mcp add -s user ... command, what each scope writes, and the trusted-folder rule. That covers /permissions and, for headless runs, --skip-trust or GEMINI_CLI_TRUST_WORKSPACE=true.
  • New "Antigravity (CLI and IDE)" block with the ~/.gemini/config/mcp_config.json and .agents/mcp_config.json paths and the same server entry.
  • Copilot CLI installs the plugin through the marketplace (copilot plugin marketplace add dgesteves/onsystem, then copilot plugin install onsystem@dgesteves). The Copilot CLI config block notes that it also reads a committed .mcp.json in a trusted folder.
  • Hook line: "The hook that checks each edit runs in Claude Code and Codex CLI". The Codex bullet already says it checks the files an apply_patch adds or updates (fix(hook): check the files a Codex apply_patch changes; init offers an AGENTS.md section #182).
  • "Claude Code without the plugin" now points to the .mcp.json box and no longer repeats the JSON.
• README.md: an Antigravity badge under "Also works with", and Antigravity in the list of client configs.
• site/app/docs/clients/page.tsx is unchanged. The page renders docs/clients.md after the two install buttons, so the new order shows on the site as it is.

No changeset: docs and site only.

How it was tested

New tests, both failing on main for the reasons above (7 of 7 and 3 of 3) and passing now:

• test/clients-docs.test.ts checks the following:
  • The lead is at most 50 words and has the --root line.
  • The last ## section is "How the server finds your project", and it holds the protocol text, which the intro no longer does.
  • The tip box has the .mcp.json and names the four clients.
  • Copilot installs only through the marketplace.
  • The hook wording covers Codex.
  • The Gemini block has the command and the trust note.
  • The Antigravity block has both paths and the same entry as Gemini.
  • The README lists Antigravity. The existing README test checks that the new badge's anchor exists.
• site/test/clients-page.test.ts renders /docs/clients and checks the following:
  • The first paragraph after the install buttons is the setup line.
  • The .mcp.json box sits above the first section.
  • "How the server finds your project" is the last section before the docs-search block.
  • The Antigravity and Gemini sections are there.

Gate, all passing: pnpm install --frozen-lockfile --prefer-offline, pnpm format:check, pnpm lint, pnpm typecheck, pnpm build, pnpm test (82 files passed, 1 skipped; 1049 tests passed, 3 skipped). Site: pnpm --filter site generate, test (17 files, 272 tests), typecheck, lint, build. I then served the built site locally and checked /docs/clients in a browser:

• The lead, the tip box with the JSON, and the Gemini and Antigravity sections render.
• "On this page" lists the new sections.
• The in-page link goes to #how-the-server-finds-your-project.
• The "Roll out to a team" link goes to /docs/rollout#give-every-agent-the-design-system.
• There is no horizontal overflow.

Setup commands: which were run, which were checked against docs

Run for real, each CLI installed with --ignore-scripts into its own folder and run under env -i with a throwaway HOME:

• Gemini CLI 0.64.0:
  • gemini mcp add -s user onsystem npx -y onsystem --root <app> wrote the args exactly as shown, with no -- needed. Without -s, it wrote .gemini/settings.json in the project.
  • gemini mcp list showed onsystem as Disabled in an untrusted folder. It showed ✓ onsystem ... - Connected once the folder was in trustedFolders.json, and again with GEMINI_CLI_TRUST_WORKSPACE=true.
  • --skip-trust is from gemini --help.
  • geminicli.com mentions a gemini trust command, but 0.64.0 has no such subcommand: it reads "trust" as a prompt. So the docs point to the trust prompt and /permissions.
• GitHub Copilot CLI 1.0.98:
  • The two marketplace commands gave "Marketplace "dgesteves" added successfully." and "Plugin "onsystem" installed successfully. Installed 1 skill.".
  • plugin list showed onsystem@dgesteves (v0.8.0), and mcp list showed Plugin servers: onsystem (local).
  • The old direct install printed the deprecation warning quoted above.
  • The committed .mcp.json was skipped in an untrusted folder ("No MCP servers configured."). Once the folder was trusted, it was listed under "Workspace servers", with Source: Workspace (.../.mcp.json).
  • copilot mcp add still writes ~/.copilot/mcp-config.json as the docs show.
• Codex CLI 0.163.0: codex plugin marketplace add dgesteves/onsystem and codex plugin add onsystem@dgesteves installed plugin 0.8.0. codex mcp add wrote the documented config.toml entry.
• Claude Code 2.1.299: claude mcp add --scope project onsystem -- npx -y onsystem wrote .mcp.json with the same command and args, plus "type": "stdio" and "env": {}.

Checked against current docs only (no CLI to run here):

• Antigravity: antigravity.google/docs/mcp gives the global and workspace mcp_config.json paths, the IDE menu path (MCP Servers, Manage MCP Servers, View raw config) and /mcp in the CLI.
• VS Code: its MCP configuration reference lists a workspace-root .mcp.json with mcpServers, under Workspace Trust.
• Grok Build: docs.x.ai says it loads project .mcp.json files.
• Codex: learn.chatgpt.com/docs/hooks says Codex skips plugin hooks until they are reviewed with /hooks.

Follow-ups (outside this item's files)

• plugins/onsystem-agent/README.md:25 still gives the deprecated copilot plugin install dgesteves/onsystem:plugins/onsystem-agent.
• site/lib/faq.ts:45 says the edit-time hook "ships for Claude Code only so far". Codex runs it too since fix(hook): check the files a Codex apply_patch changes; init offers an AGENTS.md section #182.
• The client lists in site/lib/docs.ts (the /docs/clients description) and docs/quickstart.md:42 don't name Antigravity yet.
• docs/tools.md links "how the server finds the project" to clients.md. It can now point to clients.md#how-the-server-finds-your-project.
• X2-22 (support tiers in docs/clients.md) builds on this rewrite.