usm/vitepress-schema-polish [built]

Evolve the generated VitePress docs into an outstanding, adoption-accelerating showcase and reference that demonstrates USM principles perfectly, and make the JSON schema a first-class, living, field-by-field reference. Covers a rich data-driven homepage, restructured sidebar, comprehensive schema reference, upgraded Getting Started, and general polish — all generated from .usm/schema with smart-merge preserved.

Status: built

Intent

The current docs are functional but plain: the homepage is a flat list, the sidebar groups don't match how users explore, the schema reference is shallow, Mermaid is hardcoded to the light theme (breaks dark mode), and there is no visual showcase of USM's spec-first loop. This feature turns the docs into USM's best onboarding and marketing surface while strictly honoring dogfooding: every page is generated from .usm/schema, no hand-authored output that can drift.

Decisions

schema-as-single-source [accepted]

Decision: The schema reference is generated entirely from schema/v1.json; terse field descriptions are enriched in-place in the schema so the reference is self-generating and never drifts.

Rationale: schema/v1.json is already the authoritative source for type/required/constraints. Co-locating rich descriptions avoids a second hand-maintained doc and honors 'generated from .usm/schema'.

Alternatives considered:

• A separate .usm annotation file describing each field — rejected: duplicates the schema and will drift from it

homepage-from-system-usm [accepted]

Decision: Homepage hero, tagline, principle cards, and CTAs are derived from system.usm (identity, summary, principles, repository) so every USM project gets a reflective homepage.

Rationale: Dogfooding: the generator must work for any project, not just USM's own docs.

mermaid-dark-mode-aware [accepted]

Decision: Inject a small theme-bridge script so Mermaid follows VitePress isDark instead of the hardcoded 'default' theme.

Rationale: Hardcoded 'default' makes diagrams unreadable in dark mode.

declarative-sidebar-groups [accepted]

Decision: Sidebar group order/names are driven by a declarative group-to-paths mapping while still only emitting links to pages that exist.

Rationale: Makes the requested group structure explicit and easy to evolve without breaking existence-checking that prevents dead links.

native-vitepress-containers [accepted]

Decision: Use VitePress native containers and Mermaid code fences for visuals — no custom Vue components or heavy deps.

Rationale: Keeps the build lightweight and avoids custom-component maintenance.

priority-ordering [accepted]

Decision: Deliver schema-reference and homepage/getting-started first; visuals/polish last.

Rationale: Schema reference + onboarding are the highest-leverage surfaces; polish is additive.

Flows

Comprehensive schema reference (HIGHEST PRIORITY) (schema-reference-overhaul)

Rebuild generateSchemaReference to produce a deep, scannable, field-by-field reference for every major type, sourced from schema/v1.json + enriched descriptions.

1. parse → schema/v1.json — extract every $def (systemFile, serviceFile, featureFile, feedbackFile, and shared sub-schemas) with properties, types, required, enums, constraints
2. render → one section per type, each with a field table and per-field detail blocks
3. render → per-field detail: description+intent, type, required/optional, constraints, YAML example, generator/MCP/validation impact, best-practice & pitfall
4. render → VitePress details containers for scannable collapsible groups; cross-link examples
5. enrich → update terse descriptions in schema/v1.json as the single rich source

Rich, data-driven homepage (rich-homepage)

Replace the flat-list README with a showcase homepage generated from system.usm.

1. render → VitePress hero (name, tagline from summary, action buttons) from system.identity
2. render → Mermaid workflow diagram of the spec-first loop
3. render → benefit/principle cards from system.principles in a features grid
4. render → featured example with tabs (minimal .usm YAML vs generated output)
5. render → CTAs + footer with version badge and last-generated timestamp

Upgrade Getting Started (getting-started-upgrade)

Make first-run smooth and visual.

1. render → tabbed examples (install/init/scan/generate) with copyable code
2. render → Mermaid of the first-run sequence
3. render → Common first-run issues callout (node/pnpm, vitepress, $version, gh auth)
4. render → next-steps links into Core Concepts / Workflows / Schema Reference

Restructure sidebar navigation (sidebar-restructure)

Regroup the auto-generated sidebar to match how users explore.

1. render → group order Getting Started, Core Concepts, Workflows, Schema Reference, Generated Outputs, Roadmap, Contributing
2. refactor → declarative group-to-paths mapping, only existing pages linked
3. render → feature areas nest appropriately; status badges preserved

Visuals + general polish (visuals-and-polish)

Dark-mode-aware diagrams, callouts, tables, typography, mobile, badges, CTAs.

1. fix → Mermaid dark-mode aware (theme follows VitePress isDark)
2. render → VitePress containers/callouts and improved tables across pages
3. render → version badge + last-generated timestamp
4. polish → typography, mobile responsiveness, search, GitHub/Discord CTAs

Contracts

fully-generated-from-usm

All new homepage/schema/getting-started content is generated from .usm files and schema/v1.json — no hand-authored output pages that can drift.

Acceptance criteria:

• [ ] Homepage hero/cards/example derived from system.usm + schema, not hardcoded literals
• [ ] Schema reference fully derived from schema/v1.json
• [ ] Smart-merge preserved; re-running generate is idempotent

schema-reference-comprehensive

The schema reference answers 'what does this field do?' for every major type.

Acceptance criteria:

• [ ] Covers system, service, feature, feedback file types plus shared sub-schemas (flow step, contract, test, decision, usage, options)
• [ ] Each field shows description/intent, type, required/optional, constraints, YAML example, generator/MCP/validation impact, best-practice
• [ ] Scannable tables + collapsible detail blocks; cross-links to examples

no-breakage

Existing pages, generators, and the docs build remain healthy.

Acceptance criteria:

• [ ] usm validate passes with 0 errors
• [ ] usm generate produces all existing pages plus the new ones (no dead links, none removed)
• [ ] usm docs serve / usm docs build succeed
• [ ] Existing feature/service/reference pages unchanged in substance

dark-mode-and-mobile

The site looks correct in both themes and on mobile.

Acceptance criteria:

• [ ] Mermaid diagrams switch theme with VitePress light/dark
• [ ] Layout, tables, code blocks responsive on narrow viewports
• [ ] Typography/contrast consistent across themes

smart-merge-preserved

Generator changes never clobber hand-edits.

Acceptance criteria:

• [ ] Pages still written between USM markers; content outside markers untouched
• [ ] Re-generating over an existing tree does not discard human edits

lightweight

The site stays fast with no heavy runtime dependencies.

Acceptance criteria:

• [ ] Mermaid loaded via CDN only; no new heavy client bundles
• [ ] VitePress local search retained; build time does not regress materially

Tests

validate-clean

Given:

• run_usm_validate: true

Then:

• assertion: 0 errors across all .usm files

generate-clean

Given:

• run_usm_generate: true

Then:

• assertion: schema-reference.md, README/index homepage, getting-started.md all produced
• assertion: no dead links introduced; existing pages intact

docs-build-succeeds

Given:

• run_docs_build: true

Then:

• assertion: vitepress build exits 0
• assertion: homepage renders hero + mermaid + cards + example

schema-reference-covers-types

Given:

• inspect_schema_reference: true

Then:

• assertion: sections for system, service, feature, feedback + flow/contract/test/decision sub-schemas
• assertion: each field has type, required, constraints, example, impact, best-practice

homepage-data-driven

Given:

• inspect_homepage: true

Then:

• assertion: hero text from system.identity/summary, not a hardcoded literal
• assertion: principle cards from system.principles
• assertion: featured example shows YAML and a generated output

sidebar-groups

Given:

• inspect_sidebar: true

Then:

• assertion: groups include Getting Started, Core Concepts, Workflows, Schema Reference, Generated Outputs, Roadmap, Contributing
• assertion: only existing pages linked (no dead links)

mermaid-dark-mode

Given:

• inspect_vitepress_config: true

Then:

• assertion: mermaid theme follows site dark/light, not hardcoded 'default'

smart-merge-idempotent

Given:

• generate_twice: true

Then:

• assertion: hand-edits outside USM markers preserved
• assertion: second generate produces no destructive diff

Implementation

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

See Also

• usm/gen-markdown
• usm/cli-docs
• usm/schema-v1