USM

Appearance

usm/mcp-setup-guides [built] ​

Add per-editor MCP setup guides for all 35 MCP-ready editors as dedicated pages under /mcp-setup in the help docs, plus update the marketing site ToolLogos to show the top 10 editors. Each setup page covers MCP connection config AND the installable rules/skills file for editors that support always-on hooks.

Status: built

Why this exists ​

Every USM user needs to connect their AI editor to the USM MCP server and, for editors that support it, install the always-on rules/skills file that enforces the spec-first workflow on every message. Currently only 3 editors are documented. Covering all 35 MCP-ready editors with per-editor setup guides (MCP config + rules file where applicable) makes USM instantly usable by anyone, regardless of editor choice — matching the bar set by shadcn's MCP setup page.

Design decisions ​

all-35-in-docs [accepted] ​

Decision: Generate per-editor setup pages for all 35 editors

Rationale: Maximizes compatibility coverage. Any USM user using any MCP-ready editor can find their setup. Matches shadcn's coverage bar.

Consequences: 35 markdown files under .usm-workspace/docs/mcp-setup/ plus index.md

top-10-logos [accepted] ​

Decision: Marketing site ToolLogos shows top 10 editors only

Rationale: 35 logos would overwhelm the marketing hero area. Top 10 covers the most popular. Full 35 coverage lives in the docs.

Consequences: tool-logos.tsx updated with top 10, sorted by popularity

index-plus-per-editor [accepted] ​

Decision: Index page plus per-editor pages (shadcn pattern)

Rationale: Best UX. Users land on a grid, click their editor, get exact config. Matches the shadcn setup pattern users are familiar with.

Consequences: 1 index page + 35 editor pages = 36 markdown files

rules-files-per-editor [accepted] ​

Decision: Document rules/skills file installation on each editor page where supported

Rationale: The always-on rules file is a key USM differentiator. Editors that support always-on hooks (opencode, Claude Code, Cursor, Copilot, Codex) should document both the MCP config AND the rules file install.

Consequences: Per-editor pages include a Rules File section when the editor supports always-on hooks; pages for editors without hook support note this.

stdio-config-pattern [accepted] ​

Decision: Use the standard USM stdio pattern (usm mcp serve) for all editors

Rationale: USM's MCP server is stdio-based. Most editors accept the command/args JSON pattern. HTTP-only clients use mcp-remote as a bridge.

Consequences: Configs use command usm args mcp serve. HTTP-only editors get a mcp-remote bridge note.

How it works ​

Editor setup flow (setup-flow) ​

User lands on the MCP setup index, sees a grid of 35 editor cards, clicks their editor, gets the exact MCP config and rules file installation.

  1. Navigate — docs.usm.dev/mcp-setup
  2. Scan — grid of editor cards grouped by category
  3. Click — their editor card
  4. Read — exact MCP config snippet + restart flag
  5. Install — rules/skills file for editors that support always-on hooks
  6. Copy — config into their editor

Flow Diagrams ​

mermaid
sequenceDiagram
    participant User
    participant Browser

    User->>Browser: navigate to docs.usm.dev/mcp-setup
    User->>Browser: scan grid of editor cards grouped by category
    User->>Browser: click their editor card
    User->>Browser: read exact MCP config snippet + restart flag
    User->>Browser: install rules/skills file for editors that support always-on hooks
    User->>Browser: copy config into their editor

Guarantees ​

mcp-setup-index ​

Index page at /mcp-setup with a grid of all 35 editor cards

Acceptance criteria:

  • [ ] Grid layout of 35 editor cards grouped by category
  • [ ] Each card links to a per-editor setup page
  • [ ] Cards show editor name and one-line setup summary

per-editor-pages ​

One dedicated setup page per editor (35 total) with exact config

Acceptance criteria:

  • [ ] H1 with editor name
  • [ ] Exact MCP config snippet (JSON/TOML/YAML/CLI command depending on editor)
  • [ ] Restart-required flag where applicable
  • [ ] Rules/skills file installation for editors that support always-on hooks
  • [ ] Link back to the index page

rules-files-coverage ​

Editors with always-on hook support document the rules file install

Acceptance criteria:

  • [ ] opencode: .opencode/skills/usm-workflow/SKILL.md + .opencode/usm-instructions.md
  • [ ] Claude Code: CLAUDE.md + .claude/skills/usm-workflow/SKILL.md
  • [ ] Cursor: .cursor/rules/usm.mdc + .cursor/rules/usm-always.mdc
  • [ ] Copilot: .github/copilot-instructions.md + .github/instructions/usm-iron-rules.md
  • [ ] Codex: AGENTS.md
  • [ ] Other editors: note if always-on hooks are not supported

tool-logos-top-10 ​

Marketing site ToolLogos updated with top 10 editors

Acceptance criteria:

  • [ ] Top 10: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, opencode, Codex, Zed, Continue
  • [ ] SVG paths from Simple Icons where available, fallback Terminal icon otherwise

help-audience ​

Setup pages are in the help docs (public audience), not developer docs

Acceptance criteria:

  • [ ] Pages sit under .usm-workspace/docs/mcp-setup/
  • [ ] Accessible at docs.usm.dev/mcp-setup
  • [ ] Sidebar entry under Getting Started

Implementation ​

  • Primary: web/src/components/tool-logos.tsx
  • Test code status: none

See Also ​

  • usm/cli