usm/cli-generate

The usm generate command reads all .usm files and produces markdown, OpenAPI, Mermaid, ArchiMate, TOGAF, AGENTS.md, and Vitest test specs.

Usage

# Generate all docs from .usm files
usm generate

# Check if generated files are up to date (dry run)
usm generate --check

Why this exists

After scanning and enriching, generate produces all output artifacts from the .usm source. It runs 6 passes: per-file markdown, area overviews, aggregator docs, surface tables, Mermaid diagrams, and TOGAF deliverables.

How it works

Run usm generate (run-generate)

User runs usm generate to produce all documentation

1. Parse — all .usm files in monorepo
2. Observe — duplicate $id detection
3. Generate — per-file markdown for each validated .usm
4. Generate — aggregator docs (risks, roadmap, AGENTS.md, OpenAPI, test specs)
5. Generate — surface tables injected into overview.md files
6. Generate — Mermaid diagrams (architecture, ER, service deps)
7. Generate — TOGAF ADM phase deliverables

Guarantees

generate-from-source-only

Generate must read .usm files directly — never derive docs from other docs

Acceptance criteria:

• [ ] All outputs derived from parsed .usm data
• [ ] Duplicate $ids detected and warned
• [ ] --check mode compares without writing

Test specifications

generate-produces-outputs

Given:

• valid_usm_files: true

Then:

• assertion: markdown files written for each .usm
• assertion: aggregator docs written if system.usm present

generate-check-mode

Given:

• existing_outputs: true

Then:

• assertion: reports up-to-date or out-of-date without writing

Implementation

• Primary: src/cli/index.ts (generate command)
• Test code status: none

See Also

• usm/cli-scan