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

README.md

@@ -1,8 +1,8 @@
 ---
 title: HVE Core
-description: Hypervelocity Engineering prompt library for GitHub Copilot with constraint-based AI workflows and validated artifacts
+description: Hypervelocity Engineering prompt library for GitHub Copilot with convention-driven AI workflows and validated artifacts
 author: Microsoft
-ms.date: 2026-03-22
+ms.date: 2026-05-04
 ms.topic: overview
 keywords:
   - hypervelocity engineering
@@ -24,32 +24,48 @@ estimated_reading_time: 3
 [![Documentation](https://img.shields.io/badge/docs-microsoft.github.io%2Fhve--core-blue)](https://microsoft.github.io/hve-core/)
 <!-- markdownlint-enable MD013 -->
 
-Hypervelocity Engineering (HVE) Core gives you specialized agents, auto-applied coding instructions, reusable prompts, and validated skills for GitHub Copilot. Turn Copilot into a constraint-based engineering workflow that scales from solo developers to enterprise teams.
+Hypervelocity Engineering (HVE) Core (accelerating software delivery through AI-augmented workflows) gives you specialized agents, auto-applied coding instructions, reusable prompts, and validated skills for GitHub Copilot. Turn Copilot into a convention-driven engineering workflow (agents follow your repository's standards automatically) that scales from solo developers to enterprise teams.
 
 > [!TIP]
 > Install from the VS Code Marketplace in under 30 seconds. See the [Installation Guide](docs/getting-started/install.md) for all options.
 
 ## Quick Start
 
 1. Install the [HVE Core extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) from the VS Code Marketplace.
-2. Open any project and launch GitHub Copilot Chat (`Ctrl+Alt+I`).
-3. Select an agent from the picker (try **rpi-agent**, **task-researcher**, or **memory**) and start a conversation.
+<!-- markdownlint-disable MD013 -->
+   [![Install HVE Core - Flagship Collection](https://img.shields.io/badge/VS%20Code-Install%20HVE%20Core-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) [![Install HVE Core - All Collection](https://img.shields.io/badge/VS%20Code-Install%20All%20Collections-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all)
+<!-- markdownlint-enable MD013 -->
+1. Open any project and launch GitHub Copilot Chat (`Ctrl+Alt+I`).
+2. Select an agent from the picker (try **rpi-agent**, **task-researcher**, or **memory**) and start a conversation.
 
 That's it. Agents, instructions, and prompts activate automatically once the extension is installed.
 
+**Using GitHub Copilot CLI?** Install as a plugin instead:
+
+```bash
+copilot plugin marketplace add microsoft/hve-core
+copilot plugin install hve-core-all@hve-core
+```
+
+See [CLI Plugins](docs/getting-started/methods/cli-plugins.md) for usage details.
+
 Ready for more? Follow the [Getting Started Guide](docs/getting-started/README.md).
 
 ## Choose Your Extension
 
 Two VS Code extensions serve different needs:
 
+Collections are curated bundles of agents, prompts, instructions, and skills targeting specific workflows or domains. The **HVE Core** extension installs the flagship collection (41 artifacts for RPI (Research → Plan → Implement) workflows). Install **HVE Core All** for the complete bundle (221 artifacts across all domains).
+
 | Extension                                                                                             | What it includes                                                | Best for                                                                |
 |-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------------|
 | [HVE Core All](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all)   | Every collection: all agents, prompts, instructions, and skills | Individual developers and teams that want the full library              |
 | [HVE Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) | Selective installation of specific collections                  | Teams that want to pick only the collections relevant to their workflow |
 
 Not sure which to choose? Start with HVE Core All. You can switch to HVE Installer later if you need finer control over which collections are active. See the [Collections Overview](docs/getting-started/collections.md) for a comparison of all available bundles.
 
+**Copilot CLI users:** All collections are also available as [CLI plugins](docs/getting-started/methods/cli-plugins.md) via `copilot plugin install <collection>@hve-core`.
+
 ## What's Included
 
 | Component    | Count | Description                                                          | Documentation                                  |
@@ -60,6 +76,14 @@ Not sure which to choose? Start with HVE Core All. You can switch to HVE Install
 | Skills       | 11    | Self-contained packages with cross-platform scripts and guidance     | [Skills](.github/skills/)                      |
 | Scripts      | N/A   | Validation tools for linting, security, and quality                  | [Scripts](scripts/README.md)                   |
 
+> [!TIP]
+> **Component types at a glance:**
+>
+> * Agents - Specialized AI personas with domain expertise (e.g., Task Researcher, Security Planner)
+> * Prompts - Predefined commands that trigger specific workflows (e.g., `/task-research`, `/git-commit`)
+> * Instructions - Coding standards and conventions auto-applied to matching files
+> * Skills - Reusable tool packages that extend agent capabilities
+
 ## Documentation
 
 Full documentation is available at **<https://microsoft.github.io/hve-core/>**.

docs/getting-started/collections.md

@@ -95,6 +95,19 @@ If you prefer a leaner workspace or need to standardize which artifacts are avai
 > [!TIP]
 > You can always switch later. Start with `hve-core-all` to explore, then move to the installer approach when you know which collections your team needs.
 
+## After Installing a Collection
+
+Once a collection is installed, its artifacts activate automatically:
+
+1. **Agents** appear in the Copilot Chat agent picker (press `Ctrl+.` or use the dropdown).
+2. **Prompts** are available as slash commands (type `/` in Copilot Chat to see them).
+3. **Instructions** apply automatically to matching files based on their `applyTo` patterns.
+4. **Skills** extend agent capabilities without additional configuration.
+
+To verify installation, open Copilot Chat and check that collection-specific agents appear in the agent picker. For example, installing the `hve-core` collection adds Task Researcher, Task Planner, Task Implementor, and Memory agents.
+
+To add more collections later, search "HVE" in the VS Code Extensions marketplace or use the selective install commands from the table above.
+
 ---
 
 <!-- markdownlint-disable MD036 -->

docs/getting-started/install.md

@@ -63,6 +63,35 @@ Teams that only need specific domains can use the **HVE Installer** extension to
 
 ⭐ **VS Code Extension** is the recommended method for most users who don't need customization.
 
+> [!NOTE]
+> The term "HVE Core" refers to different things depending on context:
+>
+> * **Repository** (`microsoft/hve-core`) - source for all 221 artifacts
+> * **Extension** (`HVE Core`) - installs the flagship collection (41 artifacts)
+> * **Extension** (`HVE Core All`) - installs all collections (221 artifacts)
+> * **CLI plugin** (`hve-core`) - installable via `copilot plugin install hve-core@hve-core`
+>
+> Most users who only need Research, Plan, and Implement workflows should start with the **HVE Core** extension. To explore all domains, install **HVE Core All** instead.
+
+### How the Pieces Fit Together
+
+```mermaid
+graph LR
+    REPO["microsoft/hve-core<br/>(source repository)"]
+    REPO --> C1["hve-core<br/>(flagship collection)"]
+    REPO --> C2["ado, github, security...<br/>(domain collections)"]
+    C1 --> EXT1["HVE Core Extension<br/>(41 artifacts)"]
+    C1 --> EXT2["HVE Core All Extension<br/>(221 artifacts)"]
+    C2 --> EXT2
+```
+
+### Which Extension Should I Install?
+
+* **I want to try it out quickly** → Install **HVE Core All** (everything included, explore at your pace)
+* **I only need Research, Plan, Implement workflows** → Install **HVE Core** (flagship, 41 artifacts)
+* **My team needs specific domains only** → Install **HVE Installer** (pick collections individually)
+* **I want to contribute or modify source** → Clone the repository (see [Developer Setup](#developer-setup))
+
 ## Collection Packages
 
 HVE Core organizes artifacts into role-based collections. The VS Code extension installs the **HVE Core Workflow** collection (flagship RPI workflow and core artifacts). For the complete set across all collections, use the `hve-core-all` CLI plugin or installer skill. Clone-based methods also support filtering which agents to copy by collection bundle.

docs/getting-started/methods/cli-plugins.md

@@ -107,6 +107,73 @@ project's `.github/instructions/` directory.
 
 * Skills require skill-compatible agent environments
 
+## Using Agents After Installation
+
+After installing a plugin, agents and named commands are available in your CLI session.
+
+### Named Commands vs Agent Mode
+
+CLI plugins provide two distinct interaction patterns:
+
+| Mode          | Command                  | Behavior                                                     |
+|---------------|--------------------------|--------------------------------------------------------------|
+| Named Command | `/git-commit`            | Executes a predefined workflow, then returns to default mode |
+| Agent Mode    | `/agent Task Researcher` | Switches to the agent for open-ended conversation            |
+
+Named commands (prompts) run a specific workflow and produce structured output. Agent mode enables freeform conversation with a specialized agent until you exit.
+
+> [!IMPORTANT]
+> The CLI does not support prompts that switch to a custom agent directly.
+> Prompts like `/task-research` are designed to run within a specific agent
+> context. To use them, first switch to the agent, then run the prompt:
+>
+> ```text
+> /agent Task Researcher
+> /task-research topic="API authentication patterns"
+> ```
+>
+> Prompts that do not require an agent context (e.g., `/git-commit`,
+> `/git-merge`) work directly from the default mode.
+
+### Example: Research Workflow
+
+Switch to the agent first, then run the prompt:
+
+```text
+> /agent Task Researcher
+Switched to Task Researcher
+> /task-research topic="API authentication patterns"
+[Agent executes research workflow, creates research document]
+```
+
+Continue with follow-up questions in the same agent context:
+
+```text
+> What are common API authentication patterns for REST APIs?
+[Research conversation continues]
+> How do OAuth2 and API keys compare for microservices?
+[Follow-up within same agent context]
+> /exit
+```
+
+### Available Agents
+
+After installing the hve-core plugin, these agents are available via `/agent <name>`:
+
+* Task Researcher - deep research and technical investigation
+* Task Planner - implementation planning with phased execution
+* Task Implementor - code changes following plans
+* Memory - persistent context across sessions
+* PR Review - pull request analysis and feedback
+
+For the complete list, run `/help` in a CLI session to see all available commands and agents.
+
+### When to Use Each Mode
+
+* Use **named commands** (`/git-commit-message`, `/git-merge`) directly from default mode for workflows that do not require a custom agent.
+* Use **agent mode** (`/agent <name>`) first, then run agent-specific prompts (`/task-research`, `/task-plan`) for structured workflows that need agent context.
+* Stay in **agent mode** for exploratory conversations, follow-up questions, or tasks that don't fit a predefined prompt.
+
 ---
 
 <!-- markdownlint-disable MD036 -->