usm/gen-help-reference [in-progress]

Help docs reference expansion — adds usage/options/prerequisites fields to feature schema, and new generators for CLI reference, config reference, schema reference, and MCP tools reference pages. Gives help docs the depth that Vitest-style docs have.

Status: in-progress

Intent

The help docs currently show feature specs (summary, intent, flows) but lack practical reference material: CLI command usage with flags, config file field reference, schema field reference, and a consolidated MCP tools table. Visitors can't look up "what does --merge do?" or "what fields does usmconfig.json have?" without reading source code. This feature adds the schema fields and generators to produce these reference pages from the .usm source of truth.

Decisions

usage-in-feature-spec [accepted]

Decision: Add usage/options/prerequisites to FeatureUsm schema (optional fields)

Rationale: The .usm spec is the source of truth. If CLI usage examples and flag references live in the .usm feature specs, they're available to both the help doc generator and MCP tools (agents can query usage). The alternative — parsing --help output at generation time — is brittle and produces terse output.

Alternatives considered:

• Parse commander --help output at generation time — rejected: Terse output, brittle parsing, not available to MCP tools
• Hand-write reference pages in markdown — rejected: Not generated from source, will drift, not generic

Consequences: Feature specs for CLI commands need updating with usage/options fields — one-time effort

config-reference-from-schema [accepted]

Decision: Generate usmconfig reference from usmconfig-v1.json schema descriptions

Rationale: The JSON schema already has descriptions for every field. Generating a human-readable reference from the schema means it's always in sync. No need for a separate .usm spec for the config file.

Consequences: Config reference page is only as good as the schema descriptions — may need enriching

schema-reference-from-v1-json [accepted]

Decision: Generate schema reference from v1.json schema descriptions

Rationale: Same principle — the v1.json schema has descriptions for every field. Generate a human-readable reference showing required vs optional, types, and descriptions for each .usm file type.

Consequences: Schema reference is comprehensive but may be dense — could add examples later

Flows

Generate CLI reference page from feature specs (generate-cli-reference)

Scan all CLI feature specs for usage/options/prerequisites fields and generate a single cli-reference.md page with command examples, flag tables, and prerequisites for each command.

1. parse → all feature .usm files in features/cli/
2. extract → usage, options, prerequisites fields from each
3. generate → cli-reference.md with per-command sections
4. write → .usm-workspace/docs/cli-reference.md

Generate usmconfig reference from JSON schema (generate-config-reference)

Read usmconfig-v1.json and generate a config-reference.md page with field descriptions, types, defaults, and examples.

1. read → schema/usmconfig-v1.json
2. parse → properties, descriptions, defaults, types
3. generate → config-reference.md with tables
4. write → .usm-workspace/docs/config-reference.md

Generate .usm schema reference from v1.json (generate-schema-reference)

Read v1.json and generate a schema-reference.md page showing all fields for each .usm file type (system, service, feature, data).

1. read → schema/v1.json
2. parse → oneOf schemas, properties, required fields, descriptions
3. generate → schema-reference.md with per-type tables
4. write → .usm-workspace/docs/schema-reference.md

Generate MCP tools reference page (generate-mcp-reference)

Consolidate all MCP tool feature specs into a single mcp-reference.md with a table of all 12 tools, their inputs, and when to use each.

1. parse → all feature .usm files in features/mcp/
2. extract → summary, intent from each tool spec
3. generate → mcp-reference.md with tools table
4. write → .usm-workspace/docs/mcp-reference.md

Contracts

cli-reference-has-all-commands

CLI reference page includes all CLI commands with usage

Acceptance criteria:

• [ ] Every feature in features/cli/ with usage field appears in the reference
• [ ] Each command shows usage examples and options table

config-reference-from-schema

Config reference is generated from usmconfig-v1.json

Acceptance criteria:

• [ ] Every field in usmconfig-v1.json appears in the reference
• [ ] Each field shows type, description, and default

schema-reference-covers-all-types

Schema reference covers system, service, feature, and data types

Acceptance criteria:

• [ ] Each .usm type has a field table
• [ ] Required vs optional clearly marked

mcp-reference-has-all-tools

MCP reference lists all 12 tools

Acceptance criteria:

• [ ] All read tools (8) and write tools (4) appear in the table
• [ ] Each tool shows summary and when to use

Tests

cli-reference-generated

Given:

• cli_features_with_usage: true

Then:

• assertion: cli-reference.md exists
• assertion: contains usage examples for scan, init, generate, enrich

config-reference-generated

Given:

• usmconfig_schema_exists: true

Then:

• assertion: config-reference.md exists
• assertion: contains field descriptions from schema

schema-reference-generated

Given:

• v1_schema_exists: true

Then:

• assertion: schema-reference.md exists
• assertion: contains field tables for system, service, feature types

mcp-reference-generated

Given:

• mcp_features_exist: true

Then:

• assertion: mcp-reference.md exists
• assertion: lists all 12 MCP tools

Implementation

• Primary: src/generators/markdown.ts
• Test code status: none

See Also

• usm/gen-markdown
• usm/cli-docs
• usm/gen-docs-split