Getting Started

Universal System Map — a structured source of truth for agentic systems. A single .usm/ directory describes apps, services, features, flows, contracts, and decisions in YAML validated by a JSON Schema, and generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Five minutes to a living system map

Install → usm init → usm scan → usm generate → usm docs serve. Everything below is copy-pasteable.

The first-run loop

sequenceDiagram
  participant You
  participant USM as usm CLI
  participant Disk as .usm/ + docs
  You->>USM: npm i -g @smithgray/usm
  You->>USM: usm init
  USM->>Disk: usmconfig.json
  You->>USM: usm scan
  USM->>Disk: .usm/**/*.usm
  You->>USM: usm generate
  USM->>Disk: docs, Mermaid, AGENTS.md, OpenAPI…
  You->>USM: usm docs serve --audience help
  USM-->>You: http://localhost:5173

Quick start

1. Install

npm install -g @smithgray/[email protected]
# or: pnpm add -g @smithgray/usm
usm --version

2. Init + scan

cd your-project
usm init                 # creates usmconfig.json
usm scan                 # detects services, routes, data
# Review .usm/ — this is your source of truth

3. Generate + serve

usm generate
pnpm add -D vitepress    # once, if you want local docs
usm docs serve --audience help
# Open the printed localhost URL

4. Wire agents

usm mcp serve            # MCP for Cursor / Claude / Copilot
# See Agent Setup Guide for IDE config

Example feature spec

From this project (.usm/features/cli/init.usm):

$schema: https://usm.dev/schema/v1.json
$id: usm/cli-init
$type: feature
$version: 1
$last_updated: "2026-06-19"
summary: The usm init command analyzes the repo and generates a starter usmconfig.json.

$system: usm/system
$service: usm/cli
command: init
intent: |
  New users need a config file that tells usm scan where to look. Init detects apps, packages, Prisma schemas, and Docker Compose services from the repo structure and writes a usmconfig.json so the next scan can work immediately.

flows:
  - id: run-init
    name: Run usm init
    description: User runs usm init in the repo root to generate a usmconfig.json
    steps:
      - id: s1
        action: setup
        target: repo root directory
      - id: s2
        action: parse
        target: apps/* and packages/* directories for package.json
      - id: s3
        action: parse
        target: prisma schema files
      - id: s4
        action: generate
        target: usmconfig.json with services, shared, data, outputs sections

contracts:
  - id: init-creates-config
    description: usm init must create a valid usmconfig.json at the specified output path
    must_have:
      - "Config has version: '1'"
# … truncated

usm generate turns this into markdown, Mermaid, OpenAPI, AGENTS.md, and tests.

Common first-run issues

Node / package manager

USM requires Node ≥ 18. Prefer pnpm 9+ in monorepos. If usm is not found after install, check your global bin is on PATH.

usm docs serve fails with "VitePress is not installed"

VitePress is an optional peer dependency. Install it once in the project:

pnpm add -D vitepress
# or: npm install -D vitepress

Validation warnings about $version

A warning (not an error) means a file's $version differs from the schema version this USM understands. Additive schema changes do not require a bump — only breaking ones do. Run usm upgrade to adopt new optional capabilities.

Agents inventing bugs.md / ad-hoc tracking files

Configure feedback policy with usm feedback (or usm upgrade --apply). Default is human-gate: agents must ask before filing. Rules files forbid root-level ad-hoc trackers.

GitHub Actions can't create the version PR

The release workflow uses a user token (CS_GITHUB_TOKEN) so version PRs auto-create. See the contributing docs / release workflow comments if you self-host the package.

Who uses this system

• Human Developer — Reviews feature specs before approving implementation. Discusses features
• AI Agent — Reads .usm files via MCP tools to understand system context before
• New Visitor — Finds USM on GitHub or npm and visits usm.dev to evaluate whether to use
• Team Member — Joins a project that uses USM and needs to understand the system
• Technical Lead — Reviews system design, tracks risks and roadmap, ensures architectural

Where to go next

Page	Why
Schema Reference	Field-by-field answers for every .usm type
CLI Reference	Every command and flag
MCP Tools	Spec-first tools for agents
Agent Setup Guide	Cursor / Claude / Copilot wiring
Roadmap	What's shipping next

Next Steps

• Browse the Services — 2 service(s)
• Read the Features — 37 feature spec(s)
• View the Architecture
• Check the Roadmap
• View on GitHub