Summary

The extension installation experience is buried too deep in the documentation. Users arriving at the root README or Docusaurus homepage must navigate through multiple pages before they understand what collections are available, what each contains, or how to get started with the VS Code Marketplace extensions. This issue proposes surfacing the installation path, showcasing extension collections with marketplace links, and framing the entire improvement as a guided RPI tutorial that contributors can follow end-to-end.

Problem

Current user journey has too many hops

1. Root README — Has a marketplace badge and a "Quick Start" section, but points users to docs/getting-started/install.md before they see what they're installing.
2. Docusaurus homepage — Six icon cards and four box cards. None mention the VS Code extension, marketplace, or collections directly. The "Getting Started" card links to /docs/category/getting-started, adding another hop.
3. Collection visibility — 12 collections exist (hve-core, hve-core-all, ado, github, coding-standards, data-science, design-thinking, project-planning, security-planning, installer, code-review, experimental) but users only see ise-hve-essentials.hve-core on the marketplace badge. The domain-specific extensions are invisible until someone reads extension/PACKAGING.md or docs/getting-started/methods/cli-plugins.md.
4. No collection comparison page — There is no single doc page where a user can compare all collections side by side, see what agents/prompts/instructions each includes, and click through to the corresponding marketplace extension.

What's missing

• A direct "Install the Extension" call-to-action on the Docusaurus homepage with a marketplace link.
• A dedicated Collections Overview page showing all collections with descriptions, artifact counts, and marketplace links (https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.{collection-id}).
• First-click access from the root README to the collections overview.
• A clear visual showing the relationship: Marketplace Extension → Collection → Agents + Prompts + Instructions + Skills.

Proposed Solution

1. Docusaurus homepage updates (docs/docusaurus/src/data/hubCards.tsx and docs/docusaurus/src/pages/index.tsx)

Add an "Install" or "Get Started" call-to-action to the hero section or as a prominent icon card that links directly to the marketplace and/or the new collections overview page. Consider:

• A new icon card with an install/download icon: "Install" → "Get the VS Code extension" linking to the marketplace URL https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core
• A secondary link to the collections overview page for users who want a focused subset

2. New Collections Overview documentation page (docs/getting-started/collections.md or docs/collections.md)

Create a single reference page that surfaces all available collections. For each collection:

Note: The Code Review collection (1 agent, 1 prompt, 1 instruction) is planned for merger into Coding Standards — see #860.

Each row should expand into a short description section below the table (or link to the collection's .collection.md content rendered as a details block) so users can see the specific agents and prompts included.

3. Root README updates (README.md)

Add a "Browse Collections" link near the existing marketplace badge, pointing to the new collections overview page. Keep the primary CTA as the full hve-core marketplace install, but make it obvious that focused collections exist.

4. Cross-link from docs/getting-started/install.md

The existing installation decision matrix should link to the new collections overview page so users choosing the extension method can immediately see what's available beyond the default bundle.

5. Marketplace README template update (extension/templates/README.template.md)

Add a "Browse All Collections" section to the marketplace README template that links back to the collections overview page on the Docusaurus site, so users discovering one extension on the marketplace can find the others.

Tutorial: Implementing This Issue Using the RPI Workflow

This issue is scoped to documentation and site changes, making it an ideal candidate for the full RPI (Research, Plan, Implement, Review) workflow. Below is a complete walkthrough showing how to use the task-* agents to solve this issue, commit the changes, and open a pull request.

Prerequisites

• VS Code with the HVE Core extension installed from the Marketplace
• GitHub Copilot active
• A feature branch created from main:

  git checkout -b feat/simplify-extension-install-docs

Phase 1: Research (task-researcher)

Open Copilot Chat (Ctrl+Alt+I), select the task-researcher agent from the agent picker, and enter:

Research the current extension installation documentation experience in hve-core.
I need to understand:
1. How users currently discover and install VS Code extensions from the docs
2. What collections exist and how they map to marketplace extensions
3. The current Docusaurus homepage structure and navigation
4. How the root README surfaces the extension install path
5. Gaps between what's available (12 collections with marketplace extensions) and what's visible to users
Focus on docs/getting-started/, collections/*.collection.md, extension/templates/,
docs/docusaurus/src/, and README.md

What happens: The researcher searches the codebase, reads relevant files, and produces a research document at .copilot-tracking/research/{date}/extension-install-docs-research.md with findings, evidence links, and recommendations.

What to look for in the output:

• Citations pointing to specific files and line numbers
• A clear picture of user journey gaps
• Verified artifact counts per collection
• Marketplace URL patterns confirmed

Phase 2: Plan (task-planner)

In a fresh Copilot Chat session, select the task-planner agent and enter:

Create an implementation plan for simplifying the extension installation experience.

Reference the research at .copilot-tracking/research/{date}/extension-install-docs-research.md

The plan should cover these changes:
1. New collections overview page at docs/getting-started/collections.md with a comparison
   table, marketplace links, and expandable descriptions for each of the 12 collections
2. Docusaurus homepage update adding an install CTA icon card linking to the marketplace
3. Root README update adding a "Browse Collections" link near the marketplace badge
4. Cross-link from docs/getting-started/install.md to the new collections page
5. Marketplace README template update adding a "Browse All Collections" section

Break this into phases: Phase 1 for the new collections page (largest piece),
Phase 2 for homepage/README/cross-link updates, Phase 3 for template updates.

What happens: The planner reads the research document, creates a phased implementation plan at .copilot-tracking/plans/{date}/simplify-extension-install-plan.instructions.md, and validates it against the research findings. A planning log tracks the process.

What to look for:

• Clear phase boundaries with specific files to create or edit
• Acceptance criteria per phase
• Risk flags for any changes that might break existing links

Phase 3: Implement (task-implementor)

In a fresh Copilot Chat session, select the task-implementor agent and enter:

Implement the plan at .copilot-tracking/plans/{date}/simplify-extension-install-plan.instructions.md

Start with Phase 1: Create the collections overview page.

What happens: The implementor reads the plan, executes the changes file by file, and tracks progress in a changes log at .copilot-tracking/changes/{date}/simplify-extension-install-changes.md. Each file created or modified is recorded with before/after context.

After Phase 1 completes, continue in sequence:

Continue with Phase 2 of the plan.

Continue with Phase 3 of the plan.

What to look for:

• Each phase produces concrete file changes
• The changes log records every modification
• New files follow Docusaurus frontmatter conventions (title, description, sidebar_position, author, ms.date, ms.topic)

Phase 4: Review (task-reviewer)

In a fresh Copilot Chat session, select the task-reviewer agent and enter:

Review the implementation against the plan at
.copilot-tracking/plans/{date}/simplify-extension-install-plan.instructions.md

Changes log is at .copilot-tracking/changes/{date}/simplify-extension-install-changes.md

What happens: The reviewer validates every change against the plan's acceptance criteria, checks for convention compliance, and produces a review document at .copilot-tracking/reviews/{date}/simplify-extension-install-review.md with findings graded by severity.

What to look for:

• All plan phases marked complete or flagged with issues
• Markdown conventions followed (frontmatter, heading hierarchy, link format)
• No broken cross-references between new and existing pages
• Marketplace URLs correctly formed

Phase 5: Commit and Pull Request

Stage and commit

Use the /git-commit-message prompt to generate a conventional commit message from your staged changes:

git add docs/getting-started/collections.md
git add docs/docusaurus/src/data/hubCards.tsx
git add README.md
git add docs/getting-started/install.md
git add extension/templates/README.template.md

In Copilot Chat, run:

/git-commit-message

Expected output (something like):

feat(docs): add collections overview page and simplify extension install path

- create collections comparison table with marketplace links
- add install CTA to Docusaurus homepage
- cross-link README and install guide to collections page
- update marketplace README template with collection discovery

📝 - Generated by Copilot

Review and commit:

git commit

Create the pull request

Push your branch and use the /pull-request prompt:

git push -u origin feat/simplify-extension-install-docs

In Copilot Chat, run:

/pull-request branch=origin/main

What happens: The prompt generates a PR reference XML at .copilot-tracking/pr/pr-reference.xml, launches parallel subagent reviews of each diff chunk, and produces a complete PR description at .copilot-tracking/pr/pr.md following the repository's PR template. The description includes a security analysis, change summary, and linked context.

To create the PR directly via GitHub (if MCP tools are configured):

/pull-request branch=origin/main createPullRequest=true

Alternative: Use the RPI Agent for Full Automation

Instead of running each task-* agent individually, use the RPI Agent for autonomous orchestration:

/rpi auto=partial task="Simplify the extension installation experience in the docs by creating a collections overview page with marketplace links, updating the Docusaurus homepage with an install CTA, and cross-linking from the README and install guide"

The RPI agent coordinates all five phases (Research → Plan → Implement → Review → Discover) automatically, presenting options at decision points when auto=partial is set.

Acceptance Criteria

Documentation changes

• New Collections Overview page exists at docs/getting-started/collections.md (or equivalent location)
• Page includes a comparison table with all collections showing: name, description, artifact counts (agents/prompts/instructions/skills), and marketplace install link
• Each collection has an expandable or linked description showing the specific agents and capabilities included
• Marketplace links use the pattern https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.{collection-id}
• Page follows Docusaurus conventions (frontmatter with title, description, sidebar_position, author, ms.date, ms.topic)

Homepage and navigation updates

• Docusaurus homepage (docs/docusaurus/src/data/hubCards.tsx) includes a new card or CTA linking to the marketplace or collections overview
• Root README.md includes a "Browse Collections" link near the existing marketplace badge
• docs/getting-started/install.md cross-links to the collections overview page from the extension installation method section

Template updates

• extension/templates/README.template.md includes a "Browse All Collections" or equivalent section linking to the Docusaurus collections overview page

Quality gates

• All new and modified markdown passes npm run lint:md
• All links resolve (npm run lint:md-links)
• Frontmatter validates (npm run lint:frontmatter)
• No broken navigation in Docusaurus build

Implementation Notes

• Collection descriptions should be sourced from collections/*.collection.md files to stay in sync. Consider whether the collections page should be partially generated or manually maintained.
• The ise-hve-essentials publisher ID and {collection-id} naming convention for marketplace extensions is established in extension/PACKAGING.md and the extension-publish-marketplace.yml workflow.
• Artifact counts per collection can be derived from collections/*.collection.yml by counting items grouped by kind.
• The Design Thinking collection is marked Preview maturity — surface this status in the overview table.
• The Experimental collection is marked Experimental — surface this status similarly.
• The Code Review collection is planned for merger into Coding Standards — see refactor(collections): merge code-review collection into coding-standards #860.
• Related issue: feat: Convert hve-core-installer agent into a Skill #635 (Convert installer agent to Skill) may affect the installer collection entry.

Files Likely Affected