Skip to content

docs(onboarding): overhaul marketplace onboarding and documentation site#982

Merged
WilliamBerryiii merged 28 commits intomainfrom
docs/overhaul-marketplace-onboarding
Mar 15, 2026
Merged

docs(onboarding): overhaul marketplace onboarding and documentation site#982
WilliamBerryiii merged 28 commits intomainfrom
docs/overhaul-marketplace-onboarding

Conversation

@WilliamBerryiii
Copy link
Copy Markdown
Member

@WilliamBerryiii WilliamBerryiii commented Mar 12, 2026

Description

This PR overhauled the documentation and onboarding experience to guide users through a marketplace-first funnel rather than a developer-centric reference layout. The root README, docs landing page, getting-started section, Docusaurus site infrastructure, and all 11 plugin READMEs were restructured to prioritize discoverability and audience-appropriate navigation.

Marketplace-First Restructuring

The root README.md was rewritten as a marketplace-first user funnel with a concise value proposition, 3-step Quick Start, and a "Choose Your Extension" comparison table contrasting HVE-Core and HVE Installer. The previous Project Structure ASCII tree was removed in favor of the streamlined entry points.

docs/README.md was rewritten as an audience-router (165→116 lines) with thematic sections and a "Find Your Path" four-lane router targeting newcomers, workflow users, customizers, and reference seekers.

Getting-Started Decomposition

The monolithic install.md was reduced from 232 to 114 lines by factoring content into focused pages:

  • Three clear install paths replaced the former 10-method decision matrix: Marketplace Install (recommended), Selective Install (HVE Installer), and Developer Setup (fork/clone).
  • collections.md was added with an HVE-Core vs HVE Installer comparison table, 11-row collections availability table, Mermaid relationship diagram, and selection guidance.
  • troubleshooting.md was added covering four common installation problems and four FAQ items.
  • methods/README.md was added as a setup methods overview with an 8-method comparison table.
  • methods/comparison.md was added with the decision matrix, ASCII decision tree, and 3-tier method categorization extracted from the former install page.
  • Sidebar positions cascaded +1 on four subsequent getting-started pages to accommodate the new collections.md at position 2.

Docusaurus Site Infrastructure

  • Added client-side search via @easyops-cn/docusaurus-search-local with lunr-based indexing, search term highlighting, and hashed indexes.
  • Replaced the single autogenerated sidebar with a curated 5-group hierarchy: Home, Get Started, Workflows, Customize, and Reference. Each group wraps auto-discovered content within curated categories. Sidebar gained hideable and autoCollapseCategories options.
  • Collapsed the navbar from 9 topic-dropdown items to 4 audience-segmented items (Get Started, Workflows, Customize, Reference).
  • Migrated all navigational links from /docs/category/* to /docs/*/ across config, hubCards, footer, and navbar, aligning with the new doc-type category landing pages.
  • Added a CollectionCards React component with Fluent-inspired card styles, maturity badges (Stable/Preview/Experimental), and jest-axe accessibility tests. Added to the homepage alongside a Mermaid collection relationship diagram.

Category Landing Page Migration

Converted 15+ _category_.json files from generated-index type to doc type pointing at hand-authored section README files. This replaced Docusaurus auto-generated category pages with curated overview pages containing context, tables, and diagrams. New overview pages were added for announcements and templates sections.

Plugin Generation Pipeline

Updated PluginHelpers.psm1 to enrich generated plugin READMEs through three pipeline changes:

  • Collection overview injectionNew-PluginReadmeContent gained a $CollectionContent parameter that injects content from collections/*.collection.md files as ## Overview sections.
  • Notice injection — added support for a notice key on the collection hashtable, used by the security collection to propagate a [!CAUTION] blockquote into the generated README.
  • Skill description enrichment — skill descriptions now read from SKILL.md frontmatter via Get-ArtifactFrontmatter instead of using bare directory names, with "Brought to you by microsoft/hve-core" attribution.

All 11 plugin READMEs were regenerated with new Overview sections and expanded skill table descriptions.

Collection Manifest Corrections

  • Corrected the RPI phase count from "five-phase" to "four-phase" in hve-core.collection.md and project-planning.collection.md.
  • Added a notice field to security-planning.collection.yml with a CAUTION blockquote warning that security agents are assistive tools only.

Related Issue(s)

None

Type of Change

Select all that apply:

Code & Documentation:

  • Bug fix (non-breaking change fixing an issue)
  • New feature (non-breaking change adding functionality)
  • Breaking change (fix or feature causing existing functionality to change)
  • Documentation update

Infrastructure & Configuration:

  • GitHub Actions workflow
  • Linting configuration (markdown, PowerShell, etc.)
  • Security configuration
  • DevContainer configuration
  • Dependency update

AI Artifacts:

  • Reviewed contribution with prompt-builder agent and addressed all feedback
  • Copilot instructions (.github/instructions/*.instructions.md)
  • Copilot prompt (.github/prompts/*.prompt.md)
  • Copilot agent (.github/agents/*.agent.md)
  • Copilot skill (.github/skills/*/SKILL.md)

Other:

  • Script/automation (.ps1, .sh, .py)
  • Other (please describe):

Sample Prompts (for AI Artifact Contributions)

Testing

  • Verified all 6 required automated checks pass (markdown linting, spell checking, frontmatter validation, skill structure validation, link validation, PowerShell analysis).
  • Plugin READMEs regenerated via npm run plugin:generate and validated with npm run plugin:validate.
  • CollectionCards component tested with 8 unit tests including jest-axe accessibility validation.

Checklist

Required Checks

  • Documentation is updated (if applicable)
  • Files follow existing naming conventions
  • Changes are backwards compatible (if applicable)
  • Tests added for new functionality (if applicable)

AI Artifact Contributions

  • Used /prompt-analyze to review contribution
  • Addressed all feedback from prompt-builder review
  • Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

  • Markdown linting: npm run lint:md
  • Spell checking: npm run spell-check
  • Frontmatter validation: npm run lint:frontmatter
  • Skill structure validation: npm run validate:skills
  • Link validation: npm run lint:md-links
  • PowerShell analysis: npm run lint:ps

- add collection-level notice field to plugin generation pipeline
- fix skill descriptions in generated READMEs via SKILL.md frontmatter
- correct hub card link, collection descriptions, and category metadata
- add missing announcements, customization, and templates landing pages
- remove orphan directories with no tracked content

🐛 - Generated by Copilot
- add hideable sidebar and autoCollapseCategories to Docusaurus config (R6)
- fix navbar, footer, hub card, and README links from /docs/category/ to /docs/ paths

📚 - Generated by Copilot
- convert 13 _category_.json files from generated-index to doc type links
- create getting-started/methods/README.md as Setup Methods landing page
- update navbar, footer, and hub card links to use section paths
- replace all /docs/category/ URLs with /docs/<section>/ equivalents

📄 - Generated by Copilot
Remove developer-centric sections (Prompt Engineering Framework,
Enterprise Validation Pipeline, Project Structure) and add
documentation table links to architecture and contributing pages.
Format table alignment in getting-started methods page.

Phase 7 of documentation overhaul.
- Create getting-started/collections.md with collection system overview
- Add comparison table with 11 collections and artifact counts
- Include Mermaid relationship diagram
- Explain hve-core vs hve-installer extension choices

📚 - Generated by Copilot
- Restructure install.md around marketplace, selective, and developer paths
- Extract decision matrix and method tables into methods/comparison.md
- Fix sidebar_position collisions across getting-started pages

✨ - Generated by Copilot
- Add collections link to docs/README.md Getting Started section
- Add collections row to root README.md Documentation table
- Link Choose Your Extension section to collections overview
- Update install.md description to match Phase 9 simplification

🤖 - Generated by Copilot
- add CollectionContent parameter to New-PluginReadmeContent
- inject Overview section from collection .md files between description and Install
- read collection .md file in Write-PluginDirectory and pass to readme builder
- regenerate all 11 plugin READMEs

🤖 - Generated by Copilot
- Replace autogenerated sidebar with 5 curated groups

- Groups: Home, Get Started, Workflows, Customize, Reference

- Use autogenerated items within categories for maintainability

🤖 - Generated by Copilot
…position

- Replace opening paragraph with concise value proposition

- Add extension cards for HVE Core and HVE Installer

- Add audience lanes for New User, Team Lead, Contributor, Advanced

- Move 10-role table reference to HVE Guide roles page

🤖 - Generated by Copilot
…page

- add CollectionCards React component with maturity badges and a11y tests

- add Mermaid collection relationship diagram to landing page

- integrate collections section between features and footer

- reformat markdown tables in README, collections, and comparison pages

📇 - Generated by Copilot
…ison guides

- restore .md extensions on 29 relative links in install.md and comparison.md
- apply table column alignment formatting from format:tables to docs/README.md

🔗 - Generated by Copilot
- Install @easyops-cn/docusaurus-search-local for offline search
- Configure with English language and search term highlighting
- Enable hashed index for cache invalidation

🤖 - Generated by Copilot
…collection issues

- Create troubleshooting page with common installation problems and collection FAQ
- Cover extension loading, agent visibility, collection conflicts, and version issues
- Add FAQ for extension selection, switching, simultaneous use, and updating
- Update install.md troubleshooting link to reference new page

🤖 - Generated by Copilot
…son pages

- add ms.topic frontmatter and remove duplicate H1 in troubleshooting.md
- convert bold-prefix list patterns and em-dashes to pass lint rules
- reformat table column widths in comparison.md via format:tables

✨ - Generated by Copilot
- adopt Flagship Collection naming from PR #965
- upgrade agent bundle selection callout to IMPORTANT
- restore Label Management section from PR #953
@WilliamBerryiii WilliamBerryiii requested a review from a team as a code owner March 12, 2026 16:10
…CAUTION

- fix 8 broken relative links across agents and docs files
- add missing frontmatter fields to collections.md and methods/README.md
- remove duplicate CAUTION blockquote from security-planning collection
- fix 2 broken anchor references to non-existent install heading
- regenerate security-planning plugin output

🔗 - Generated by Copilot
…lace-onboarding

# Conflicts:
#	collections/security-planning.collection.yml
#	docs/getting-started/install.md
- add Project Planning references to docs hub Agent Systems and Going Deeper sections
- rename security-planning to security in collections table, mermaid, and card data
- restore CAUTION notice field dropped during security collection rename
- extract inline CSS to styles.module.css in docusaurus homepage
- regenerate plugin outputs and format tables

📚 - Generated by Copilot
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 12, 2026

Dependency Review

The following issues were found:

  • ✅ 0 vulnerable package(s)
  • ✅ 0 package(s) with incompatible licenses
  • ✅ 0 package(s) with invalid SPDX license definitions
  • ✅ 0 package(s) with unknown licenses.
  • ⚠️ 6 packages with OpenSSF Scorecard issues.

View full job summary

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Mar 12, 2026

Codecov Report

❌ Patch coverage is 55.55556% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.92%. Comparing base (0a90f57) to head (29abb95).
⚠️ Report is 6 commits behind head on main.

Files with missing lines Patch % Lines
scripts/plugins/Modules/PluginHelpers.psm1 55.55% 8 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #982      +/-   ##
==========================================
- Coverage   86.03%   85.92%   -0.11%     
==========================================
  Files          30       30              
  Lines        5412     5428      +16     
==========================================
+ Hits         4656     4664       +8     
- Misses        756      764       +8     
Flag Coverage Δ
pester 85.92% <55.55%> (-0.11%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
scripts/plugins/Modules/PluginHelpers.psm1 76.44% <55.55%> (-1.88%) ⬇️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Template files like extension/templates/README.template.md contain
relative LICENSE links that resolve correctly in packaged output
but not in the source tree. Adding ^LICENSE$ to ignorePatterns
prevents false failures during link validation.
@WilliamBerryiii WilliamBerryiii changed the title docs(docs): overhaul documentation for marketplace onboarding docs(onboarding): overhaul marketplace onboarding and documentation site Mar 13, 2026
Copy link
Copy Markdown
Contributor

@katriendg katriendg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments where it seems our collection names for HVE Core & HVE Core All may be mixed up. Otherwise valuable updates to these docs, thanks!

Bill Berry and others added 2 commits March 13, 2026 17:09
…ency

- rename "HVE Core" to "HVE Core All" where full bundle is described
- fix install.md to describe flagship hve-core collection (40 artifacts)
- fix troubleshooting conflict section and FAQ to reference hve-core-all
- update docs/README.md and root README.md extension tables
- pin docusaurus-search-local from ^0.55.1 to 0.55.1

📝 - Generated by Copilot
WilliamBerryiii added a commit that referenced this pull request Mar 20, 2026
🤖 I have created a release *beep* *boop*
---


##
[3.2.0](hve-core-v3.1.46...hve-core-v3.2.0)
(2026-03-20)


### ✨ Features

* add -OutputPath parameter to Validate-MarkdownFrontmatter.ps1
([#1134](#1134))
([fdf1bcf](fdf1bcf)),
closes [#1006](#1006)
* add action version consistency scan workflow
([#1127](#1127))
([4229df1](4229df1))
* **agent:** MVE Experiment Designer
([#976](#976))
([70f86ca](70f86ca))
* **agents:** add ADO Backlog Manager orchestrator agent
([#800](#800))
([fae3987](fae3987))
* **agents:** add meeting analyst agent for transcript analysis using
work-iq ([#502](#502))
([5345b5b](5345b5b))
* **agents:** add quick-reference line to RPI Phase 5 suggestions
([#897](#897))
([9a90f39](9a90f39))
* **agents:** add RAI Planner, enhance SSSC Planner, and redesign
Security Planner
([#979](#979))
([06f826c](06f826c))
* **agents:** add symmetric cross-system handoff to GitHub Backlog
Manager ([#952](#952))
([ba34a35](ba34a35))
* **agents:** Functional Code Review Agent — pre-PR functional
correctness reviewer
([#733](#733))
([9cf63b7](9cf63b7))
* **build:** add Python extensions and uv 0.10.8 to devcontainer
([#920](#920))
([9ca0579](9ca0579))
* **build:** add uv ecosystem to Dependabot configuration
([#913](#913))
([2a4bd39](2a4bd39))
* **build:** enable npm pinning enforcement in dependency scan
([#838](#838))
([4e9e31f](4e9e31f))
* **build:** migrate attestation actions to v4.1.0 and add SBOM
verification docs
([#841](#841))
([ca1e65b](ca1e65b))
* **collections:** add four new validator checks (orphan, duplicate,
companion, coverage)
([#869](#869))
([1a96b73](1a96b73))
* **devcontainer,security:** add enterprise artifact hub configuration
([#1032](#1032))
([1d56d25](1d56d25))
* **docs:** add Rust coding standards and guidelines
([#809](#809))
([d4c4899](d4c4899))
* **extension:** add Microsoft logo icon to VS Code Marketplace listings
([#906](#906))
([82aca41](82aca41))
* **github:** add declarative label management
([#953](#953))
([a1a6845](a1a6845))
* **instructions:** add ADO backlog shared infrastructure
([#786](#786))
([1914078](1914078))
* **instructions:** add ADO backlog sprint planning and capacity
tracking ([#788](#788))
([d6fb77d](d6fb77d))
* **instructions:** add ADO triage workflow and prompt
([#787](#787))
([cde0190](cde0190))
* **instructions:** add shared story quality conventions and sprint
planning ([#803](#803))
([a2f18e3](a2f18e3))
* **prompts:** add ADO discovery and work item prompts with agent
routing ([#790](#790))
([7e74523](7e74523))
* **prompts:** add security review prompts
([#1118](#1118))
([ad30967](ad30967))
* **scripts:** add dynamic Python skill discovery for lint/test
([#957](#957))
([0a90f57](0a90f57))
* **scripts:** add Get-StandardTimestamp utility to CIHelpers module
([#1126](#1126))
([b273a4b](b273a4b))
* **scripts:** add Python copyright header validation
([#905](#905))
([67df902](67df902))
* **scripts:** add Python skill support to Validate-SkillStructure
([#903](#903))
([68479d9](68479d9))
* **scripts:** add workflow npm command scanning to dependency pinning
([#837](#837))
([6b5ae06](6b5ae06))
* **security:** add basic security reviewer agent with owasp skills
([#1008](#1008))
([cb1fd05](cb1fd05))
* **security:** add sigstore attestation bundles and fix
component-detection action
([#1148](#1148))
([f79c272](f79c272))
* **skills:** add Atheris fuzz harness with CI workflow integration
([#1102](#1102))
([d337e1d](d337e1d))
* **skills:** add PowerPoint automation skill with YAML-driven deck
generation ([#868](#868))
([00465cd](00465cd))
* **skills:** convert hve-core-installer agent to self-contained skill
([#846](#846))
([1d821fb](1d821fb))
* **skills:** enhance pr-reference skill with flexible filtering and
base branch detection
([#1095](#1095))
([26a32ea](26a32ea))
* **workflows:** add devcontainer infrastructure change log workflow
([#899](#899))
([8aca446](8aca446))
* **workflows:** add milestone auto-close on stable and pre-release
publishes ([#834](#834))
([79362b1](79362b1))
* **workflows:** add ms.date documentation freshness checking
([#969](#969))
([3ed441c](3ed441c))
* **workflows:** add Python linting CI workflow with Ruff
([#951](#951))
([f89f0eb](f89f0eb))
* **workflows:** add Python testing CI workflow with pytest and Codecov
([#934](#934))
([5e8306f](5e8306f))
* **workflows:** add uv and Python package sync to copilot-setup-steps
([#921](#921))
([45d517d](45d517d))


### 🐛 Bug Fixes

* **build:** override Linguist vendored flag for Python skill files
([#1155](#1155))
([0eee5b6](0eee5b6))
* **build:** override serialize-javascript to &gt;=7.0.3 for RCE fix
([#876](#876))
([e49039a](e49039a))
* **build:** resolve Pinned-Dependencies alerts for vsce npm commands in
extension workflows
([#782](#782))
([89dad9d](89dad9d))
* **build:** update undici and yauzl overrides for security audit
([#1030](#1030))
([2c2f92f](2c2f92f))
* **docs:** add CLI Plugins to install.md navigation surfaces
([#902](#902))
([79d6595](79d6595))
* **docs:** add sidebar ordering for Design Thinking documentation
([#832](#832))
([551fddc](551fddc)),
closes [#830](#830)
* **docs:** graduate design-thinking to preview and correct stale
collection references
([#831](#831))
([5110e35](5110e35))
* **docs:** include project-planning in UX Designer install guidance
([#908](#908))
([e7aa9bc](e7aa9bc))
* **docs:** remediate writing-style convention violations
([#865](#865))
([68b04bc](68b04bc))
* **docs:** remove draft content announcement banner
([#825](#825))
([b45de80](b45de80))
* **docs:** remove unbounded path-to-regexp override breaking SSG
([#1153](#1153))
([d810018](d810018))
* **docs:** use actual clone paths instead of folder display names in
multi-root workspace settings
([#984](#984))
([5dbab82](5dbab82))
* **instructions:** replace black with ruff in uv-projects
([#898](#898))
([b0c06d9](b0c06d9))
* **scripts:** cover .github/ skill files in copyright header validation
([#1055](#1055))
([#1098](#1098))
([27fbd33](27fbd33))
* **scripts:** eliminate phantom git changes from plugin generation
([#1035](#1035))
([e49a1b5](e49a1b5))
* **scripts:** enable JSON log output for lint:version-consistency
([#1033](#1033))
([52b0885](52b0885))
* **security:** calculate compliance score from total scanned
dependencies ([#930](#930))
([c112c3d](c112c3d))
* **skills:** add AST validation and namespace restriction for
content-extra.py
([#1027](#1027))
([c50c7a3](c50c7a3))
* **skills:** add depth limits to recursive PowerPoint processing
functions ([#1028](#1028))
([bf08994](bf08994))
* **skills:** harden XML parsing and blob writes in powerpoint extract
([#1053](#1053))
([89d24b1](89d24b1))
* **skills:** resolve ruff lint and format violations in powerpoint
skill ([#1048](#1048))
([17bbe7a](17bbe7a))
* **workflows:** add uv.lock dependencies submission have fork-skip
condition ([#1109](#1109))
([dec56ac](dec56ac))
* **workflows:** automate weekly SHA staleness check with issue creation
([#975](#975))
([1ea4caa](1ea4caa))
* **workflows:** close Codecov integration gaps for Pester and pytest
flags ([#1106](#1106))
([cca29b7](cca29b7))
* **workflows:** propagate uv sync errors in copilot-setup-steps
([#961](#961))
([df88d7c](df88d7c))
* **workflows:** resolve release-please skip cascade and Python project
discovery ([#1043](#1043))
([79993e2](79993e2))
* **workflows:** scan only commit subjects for breaking change detection
([#1157](#1157))
([a38a657](a38a657))


### 📚 Documentation

* clarify HVE Core Extension vs Installer messaging across documentation
([#965](#965))
([0fceb8f](0fceb8f))
* **docs:** add ADO integration user documentation
([#935](#935))
([ec89302](ec89302))
* **docs:** add Project Planning agent documentation
([#936](#936))
([3a3a0fd](3a3a0fd))
* **onboarding:** overhaul marketplace onboarding and documentation site
([#982](#982))
([4309e10](4309e10))


### ♻️ Refactoring

* **build:** merge code-review collection into coding-standards
([#863](#863))
([8027e7b](8027e7b))
* **workflows:** rename release pipeline workflows and add marketplace
automation triggers
([#829](#829))
([b6397f4](b6397f4))


### 🔧 Maintenance

* **build:** add clean:logs npm script
([#1122](#1122))
([f85fe02](f85fe02)),
closes [#988](#988)
* **build:** add JSON reporter for cspell
([#1123](#1123))
([6d59f67](6d59f67))
* **ci:** add multi-arch support to copilot-setup-steps binary downloads
([#955](#955))
([8d0c706](8d0c706))
* **deps-dev:** bump cspell from 9.6.4 to 9.7.0 in the npm-dependencies
group ([#839](#839))
([3fa16ff](3fa16ff))
* **deps:** bump actions/dependency-review-action from 4.8.3 to 4.9.0 in
the github-actions group across 1 directory
([#942](#942))
([1a9b858](1a9b858))
* **deps:** bump cairosvg from 2.8.2 to 2.9.0 in
/.github/skills/experimental/powerpoint
([#1025](#1025))
([f4deda7](f4deda7))
* **deps:** bump dompurify from 3.3.1 to 3.3.2 in /docs/docusaurus
([#924](#924))
([d2060d6](d2060d6))
* **deps:** bump svgo from 3.3.2 to 3.3.3 in /docs/docusaurus
([#880](#880))
([6dc2406](6dc2406))
* **deps:** bump the github-actions group across 1 directory with 4
updates ([#1100](#1100))
([2290dc0](2290dc0))
* **deps:** bump the github-actions group with 6 updates
([#840](#840))
([f57bc01](f57bc01))
* **docs:** correct New-MsDateReport table rendering and refresh stale
docs ([#1114](#1114))
([c2b806f](c2b806f))
* **settings:** remove orphaned Checkov config and stale gitignore
entries ([#870](#870))
([98fcd74](98fcd74))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com>
Co-authored-by: Bill Berry <wberry@microsoft.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants