usm/vitepress-home-feedback-schema [built]

Refine the VitePress docs homepage into a clean, scannable technical reference (not a marketing duplicate), add a dual-mode Feedback/Report Issue button for humans and agents, and apply general polish (cross-links, CTAs, callouts). Iterates on the built vitepress-schema-polish feature.

Status: built

Why this exists

The current docs homepage (from vitepress-schema-polish) is rich but marketing-heavy — it duplicates the usm.dev marketing site with principle cards, benefit sections, and "Sound familiar?" content. The docs should be a clean technical reference: short intro, quick stats, quick start commands, and prominent links to key sections. Additionally, there is no way for readers to report issues or give feedback from the docs site itself. This feature adds a dual-mode feedback button (human → pre-filled GitHub issue; agent → MCP tool with page context + .usm map) and applies general polish to cross-links, CTAs, and VitePress callout usage.

Design decisions

homepage-simplify-not-remove [accepted]

Decision: Simplify the homepage by removing marketing content, not by removing the homepage entirely. Keep the spec-first diagram, quick stats, and quick start as the core reference content.

Rationale: The existing vitepress-schema-polish feature built a rich homepage. This feature refines it — removing the marketing duplication while keeping the technical reference value. The marketing content belongs on usm.dev (Next.js + shadcn), not docs.usm.dev (VitePress).

feedback-as-generated-page [accepted]

Decision: The feedback page is a generated markdown page (docs/feedback.md), not a custom Vue component. The nav bar link is added via VitePress themeConfig.nav.

Rationale: Keeps the build lightweight (no custom Vue components). The feedback page content is generated from system.usm (identity.repository for the issue tracker URL) and the USM version. The nav link is injected into the VitePress config during docs serve/build.

agent-feedback-via-existing-mcp [accepted]

Decision: The agent feedback path reuses the existing usm_report_feedback MCP tool (from usm/agent-feedback feature). The feedback page documents how agents should use it with page context.

Rationale: No new MCP tool needed. The existing agent-feedback protocol already handles structured feedback entries. The docs page teaches agents to include current page URL and .usm map context.

cross-links-in-generator [accepted]

Decision: Cross-links and next-steps sections are added in the markdown generator, not hand-edited into output.

Rationale: Dogfooding: all content must be generated from .usm. The generator already has access to system.usm index for building link maps.

How it works

Simplify homepage to technical reference (homepage-simplify)

Strip marketing-heavy content from the VitePress homepage. Keep it a clean, scannable reference that links to usm.dev for marketing.

1. Remove — Principle cards from VitePress features grid (keep in AGENTS.md only)
2. Remove — "Sound familiar?" / heavy benefit sections — replace with a single link to usm.dev
3. Keep — Short intro paragraph from system.summary
4. Keep — Quick Stats table (features, services, packages)
5. Add — Quick Start commands block (copy-pasteable install → init → scan → generate → serve)
6. Add — Prominent link cards to key sections: Schema Reference, Getting Started, Roadmap, CLI Reference, MCP Tools
7. Keep — Spec-first workflow Mermaid diagram
8. Keep — Sidebar navigation fully visible (no collapsed groups by default on homepage)

Add dual-mode Feedback / Report Issue button (feedback-button)

Add a visible feedback mechanism to the VitePress docs site. Supports two modes: human (pre-filled GitHub issue) and agent (MCP tool with structured context).

1. Add — Feedback link in VitePress nav bar (themeConfig.nav) — "Report Issue" pointing to a feedback page
2. Add — Feedback link in sidebar footer — same destination
3. Generate — docs/feedback.md page with two clear paths: human and agent
4. Render — Human path: pre-filled GitHub issue link with template (title, body with current page URL, USM version, browser info)
5. Render — Agent path: MCP tool instructions — usm_report_feedback with page context + .usm map reference
6. Add — VitePress themeConfig.editLink pointing to .usm source on GitHub (already exists, verify)

Stronger cross-links and CTAs (cross-links-ctas)

Add consistent next-steps sections, cross-links between related pages, and clear CTAs throughout the docs.

1. Add — "Next steps" section at bottom of Getting Started, Schema Reference, CLI Reference, MCP Reference
2. Add — Cross-links between related pages (e.g., Schema Reference ↔ CLI Reference, Getting Started ↔ Agent Setup Guide)
3. Add — CTA banner on homepage: "Using USM in production? → usm.dev"
4. Add — Footer link to usm.dev marketing site

General VitePress polish (general-polish)

Better use of VitePress callouts, tables, and diagrams. Ensure dark mode, mobile, and search work well.

1. Verify — Mermaid dark-mode aware (already implemented in vitepress-schema-polish)
2. Add — VitePress tip/warning/danger callouts where appropriate (e.g., prerequisites, common pitfalls)
3. Add — Responsive tables with horizontal scroll on mobile
4. Verify — VitePress local search indexes all pages
5. Add — Version badge in footer (already present, verify)

Guarantees

homepage-reference-first

Homepage is a clean technical reference, not a marketing duplicate.

Acceptance criteria:

• [ ] Short intro paragraph (2-3 sentences)
• [ ] Quick Stats table (feature count, service count, package count)
• [ ] Quick Start commands (copy-pasteable)
• [ ] Prominent link cards to Schema Reference, Getting Started, Roadmap
• [ ] Spec-first workflow Mermaid diagram
• [ ] No principle cards, benefit sections, or "Sound familiar?" content
• [ ] Single link to usm.dev for marketing content
• [ ] Sidebar fully visible (no collapsed groups by default)

feedback-dual-mode

Feedback button works for both humans and agents.

Acceptance criteria:

• [ ] Visible "Report Issue" link in nav bar and/or sidebar
• [ ] Dedicated feedback page with two clear paths
• [ ] Human path: pre-filled GitHub issue URL with template (title, body, page context)
• [ ] Agent path: MCP tool instructions (usm_report_feedback with page + .usm context)
• [ ] VitePress editLink points to .usm source on GitHub

all-content-generated

All new content is generated from .usm files — no hand-authored output pages.

Acceptance criteria:

• [ ] Homepage content derived from system.usm
• [ ] Feedback page generated by markdown generator
• [ ] Cross-links derived from system.usm index and feature refs
• [ ] Smart-merge preserved; re-running generate is idempotent

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 new ones
• [ ] usm docs serve / usm docs build succeed
• [ ] Existing feature/service/reference pages unchanged in substance

Test specifications

homepage-clean

Given:

• run_usm_generate: true
• inspect_homepage: true

Then:

• assertion: Homepage has short intro, Quick Stats, Quick Start commands, link cards
• assertion: No principle cards, benefit sections, or marketing-heavy content
• assertion: Single link to usm.dev present
• assertion: Sidebar fully visible with all groups expanded

feedback-page-exists

Given:

• run_usm_generate: true

Then:

• assertion: docs/feedback.md generated
• assertion: Contains human path with pre-filled GitHub issue link
• assertion: Contains agent path with MCP tool instructions
• assertion: Nav bar includes Report Issue link

docs-build-succeeds

Given:

• run_docs_build: true

Then:

• assertion: vitepress build exits 0
• assertion: Homepage renders clean reference layout
• assertion: Feedback page accessible and functional

validate-clean

Given:

• run_usm_validate: true

Then:

• assertion: 0 errors across all .usm files

cross-links-present

Given:

• inspect_generated_docs: true

Then:

• assertion: Getting Started has next-steps section
• assertion: Schema Reference has cross-links to CLI Reference and Getting Started
• assertion: CLI Reference has cross-links to MCP Reference and Schema Reference

existing-pages-intact

Given:

• run_usm_generate: true
• diff_against_previous: true

Then:

• assertion: Feature docs unchanged in substance
• assertion: Service docs unchanged
• assertion: No dead links introduced

Implementation

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

See Also

• usm/vitepress-schema-polish
• usm/agent-feedback
• usm/gen-markdown
• usm/cli-docs