docs: improve new user onboarding with terminology, CLI plugins, and collections clarity

[katriendg]

Description

Improved the new user experience across the README, getting started docs, and CLI plugin documentation based on user research findings. The research identified 18 unanswered questions after reading the README, a critical naming collision where "hve-core" is used in 4 distinct contexts, and zero documentation on how to use agents after CLI plugin installation.

README Improvements

Addressing the "30-second test" failures: users could identify what HVE Core is and how to install it, but couldn't grasp key terminology or discover the CLI installation path.

• Expanded Hypervelocity Engineering with a parenthetical definition and replaced "constraint-based" with "convention-driven" plus an inline explanation
• Added one-click install badges using vscode:extension/ URI scheme for both flagship and all-collections extensions
• Added CLI plugin installation path in Quick Start for Copilot CLI users with marketplace registration and install commands
• Added collections context paragraph with RPI acronym expansion before the extension comparison table
• Added component-types callout after the What's Included table defining agents, prompts, instructions, and skills

CLI Post-Install Usage (docs/getting-started/methods/cli-plugins.md)

Filling the critical gap: users had zero guidance on what to do after copilot plugin install succeeds.

• Added "Using Agents After Installation" section documenting named commands vs agent mode interaction patterns
• Documented the CLI limitation that agent-specific prompts require switching to the agent first via /agent <name>
• Added example workflows showing the correct sequence and follow-up conversation patterns
• Listed available agents from the flagship collection with one-line descriptions

Collections Disambiguation (docs/getting-started/install.md)

• Added NOTE callout disambiguating "HVE Core" across repository, flagship extension, and all-collections extension contexts
• Added Mermaid diagram showing the repository → collections → extensions relationship
• Added decision aid ("Which Extension Should I Install?") mapping 4 user scenarios to recommended paths

Post-Install Activation (docs/getting-started/collections.md)

• Added "After Installing a Collection" section explaining automatic artifact activation across all 4 component types
• Documented verification steps and path to adding more collections later

Related Issue(s)

Related to #1519

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)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

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

Sample Prompts (for AI Artifact Contributions)

Testing

• Verified all changed files follow existing naming conventions
• Confirmed Mermaid diagram syntax is valid
• Validated badge URLs use correct shields.io format and vscode:extension/ URI scheme
• CLI commands match patterns established in existing cli-plugins.md documentation
• Manual review of rendered markdown formatting for callouts, tables, and code blocks
• Automated validation deferred to CI pipeline

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) (N/A — documentation-only changes)

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
• Plugin freshness: npm run plugin:generate
• Docusaurus tests: npm run docs:test

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A — no script changes)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.43%. Comparing base (57ea279) to head (15c1ff9).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1520      +/-   ##
==========================================
- Coverage   87.44%   87.43%   -0.01%     
==========================================
  Files          68       68              
  Lines       10335    10335              
==========================================
- Hits         9037     9036       -1     
- Misses       1298     1299       +1     

Flag	Coverage Δ
pester	84.79% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Advisory review — this PR is from a maintainer. Findings are informational only.

Overview

Well-structured documentation PR that directly addresses the user research findings from #1519. The changes are well-scoped, the descriptions are clear, and the CLI post-install guidance fills a real gap. Three content accuracy issues and a checklist compliance gap are noted below.

---

Issue Alignment ✅

The PR links to #1519 as "Related to" (appropriate if the issue stays open for further follow-up). Changes address the stated research findings: terminology definitions, CLI post-install documentation, and the naming disambiguation. Coverage looks thorough.

---

PR Template Compliance ⚠️

Several Required Automated Checks are unchecked without an (N/A — reason) annotation:

Check	Relevance to this PR
npm run lint:frontmatter	Docs files carry frontmatter — directly applicable
npm run lint:md-links	Links added throughout — directly applicable
npm run docs:test	Docusaurus content changed — directly applicable
npm run plugin:generate	N/A for docs-only, but annotation is missing

Per the template: "When a conditional checkbox's trigger condition is not met, annotate the checkbox inline with (N/A — {brief reason})." Please either run the applicable commands and check the boxes, or add explicit N/A annotations for the ones that genuinely don't apply.

---

Coding Standards ✅

Writing style is clear, professional, and consistent with the repo conventions. Docusaurus admonition syntax is used correctly. Mermaid <br/> line breaks follow the documented pattern.

---

Code Quality Findings

Three inline comments are attached. Summary:

1. install.md line 73 — The NOTE callout recommends the flagship HVE Core extension for most users, but the existing README text (line 65) and the decision aid directly below (line 89) both recommend HVE Core All for new/exploratory users. The three recommendations are inconsistent and will confuse first-time readers.

2. install.md line 83 — C1 --> C2 in the Mermaid diagram implies the flagship collection leads to domain collections, which misrepresents the architecture. Both collections are independent branches from the repository; the All Extension packages them together.

3. install.md line 71 — The disambiguation NOTE lists 3 of the 4 contexts the PR description says were identified as colliding. The CLI plugin context (hve-core as a plugin name) is missing.

---

No Security Concerns ✅

Documentation-only change. No credentials, no secrets, no executable code introduced.

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• #1519 issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by PR Review for issue #1520 · ● 897.3K

[github-actions]

Disambiguation is incomplete — The PR description states the research identified "a critical naming collision where 'hve-core' is used in 4 distinct contexts," but this NOTE callout only disambiguates three. The CLI plugin context is missing.

Consider adding a fourth bullet:

> * **CLI plugin** (`hve-core`) - installable via `copilot plugin install hve-core@hve-core`

Without this entry, users installing via CLI will still encounter the same naming confusion the PR aims to resolve.