docs: improve new user onboarding with terminology, CLI plugins, and collections clarity#1520
docs: improve new user onboarding with terminology, CLI plugins, and collections clarity#1520
Conversation
…collections clarity - add HVE/RPI definitions, component-type callout, and one-click install badges to README - add CLI plugin install path to Quick Start and Choose Your Extension sections - add post-install usage guide with named commands vs agent mode to cli-plugins.md - add collections disambiguation callout and decision aid to install.md - add "After Installing a Collection" section to collections.md 📚 - Generated by Copilot
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1520 +/- ##
==========================================
+ Coverage 85.46% 86.49% +1.02%
==========================================
Files 82 76 -6
Lines 11802 10743 -1059
==========================================
- Hits 10087 9292 -795
+ Misses 1715 1451 -264
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
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:
-
install.mdline 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. -
install.mdline 83 —C1 --> C2in 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. -
install.mdline 71 — The disambiguation NOTE lists 3 of the 4 contexts the PR description says were identified as colliding. The CLI plugin context (hve-coreas 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 | noneCo-authored-by: Copilot <copilot@github.com>
- specify CLI plugin installation command - differentiate between flagship and all collections for user clarity 🔍 - Generated by Copilot Co-authored-by: Copilot <copilot@github.com>
There was a problem hiding this comment.
PR Review Summary
Overall: The changes are well-motivated and address real usability gaps identified in the linked user research. The content additions to cli-plugins.md, install.md, and collections.md are clear and well-structured. One rendering bug in the README.md Quick Start section requires a fix before merging.
Issue Alignment ✅
The PR addresses the user research findings in #1519 — terminology confusion, missing CLI post-install guidance, and the "HVE Core" naming disambiguation. The scope is appropriately bounded and the changes directly match the stated goals.
PR Template Compliance ⚠️
- "Documentation update" is correctly checked and accurately describes all changes.
- Three automated validation items remain unchecked that apply to documentation changes:
npm run lint:frontmatter— should be run to verify existing frontmatter in the modifieddocs/files is still valid after edits.npm run lint:md-links— important given the new cross-doc links and badge URLs added throughout.npm run docs:test— relevant sinceinstall.mdgains a Mermaid diagram and Docusaurus builds this content.
Please run these and check them off (or annotate N/A with justification) before merging.
Code Quality ❌
README.md Quick Start — numbered list rendering bug (see inline comment):
HTML comment blocks (<!-- markdownlint-disable -->) are block-level elements in CommonMark/GFM and interrupt ordered lists. The badges are placed between list items using HTML comments, which causes the second list to restart at 1. instead of continuing at 2.. New users reading the Quick Start on GitHub will see two step-1s, which undermines the fix this PR is trying to deliver. Moving the badges above the ordered list resolves the issue without any markdownlint suppression needed.
Coding Standards ⚠️
docs/getting-started/collections.md — bolded-prefix list items (see inline comment):
writing-style.instructions.md prohibits the **Term** description list pattern. The "After Installing a Collection" section uses this pattern (**Agents** appear in...). Removing the bold from the component names while keeping the sentence structure intact satisfies the convention without losing clarity.
Positive Highlights ✅
- The
install.mdMermaid diagram correctly represents the repository → collection → extension relationship with proper<br/>line breaks per Docusaurus conventions. - The "Which Extension Should I Install?" decision aid in
install.mdis a genuinely useful addition and the format (scenario → recommendation) is clear. - The "Named Commands vs Agent Mode" table and
[!IMPORTANT]callout incli-plugins.mdfill a real documentation gap with accurate, actionable guidance. - The
[!NOTE]callout disambiguating "HVE Core" naming contexts is exactly the right solution for the naming collision problem.
Required Action Items
- Fix the numbered list restart in
README.mdQuick Start (see inline comment — move badges above the list). - Run
npm run lint:md-links,npm run lint:frontmatter, andnpm run docs:testand update the checklist.
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
There was a problem hiding this comment.
PR Review Summary
Overall: The two issues from the previous review have been addressed — the README Quick Start list restart is fixed and the bolded-prefix pattern in collections.md is resolved. One template compliance gap and one minor content inconsistency remain before this is ready to merge.
Previous Issues — Now Resolved ✅
- README.md numbered list restart: Fixed. The badges are now placed above the ordered list, so steps 1–3 render correctly without the CommonMark interruption.
collections.mdbolded-prefix list items: Fixed. The component type names in the "After Installing a Collection" ordered list no longer carry bold formatting.
PR Template Compliance ⚠️ (Blocking)
Three Required Automated Checks remain unchecked without (N/A — reason) annotations:
| Check | Why it applies to this PR |
|---|---|
npm run lint:frontmatter |
All four modified files are in docs/ and carry frontmatter |
npm run lint:md-links |
New internal cross-doc links and badge URLs were added throughout |
npm run docs:test |
install.md gains a Mermaid diagram; Docusaurus builds this content |
Per the PR template: "The following validation commands must pass before merging." Please either run these and check the boxes, or add (N/A — {reason}) annotations for any that genuinely do not apply (e.g., npm run validate:skills, npm run lint:ps, and npm run plugin:generate are reasonable N/A candidates for a docs-only change).
Issue Alignment ✅
The PR addresses the user research findings linked from #1519. Using "Related to" rather than "Fixes/Closes" is appropriate if the issue tracks broader follow-up work.
Coding Standards ✅
Writing style is clear and consistent with repo conventions. Docusaurus admonition syntax is used correctly. The Mermaid diagram uses <br/> line breaks per the documented pattern. The [!NOTE], [!TIP], and [!IMPORTANT] callouts follow the correct GitHub-flavored alert format.
Code Quality ⚠️
docs/getting-started/methods/cli-plugins.md — command name inconsistency (inline comment attached at line 120): The "Named Commands vs Agent Mode" table uses /git-commit while the "When to Use Each Mode" section references /git-commit-message. Readers following the documentation will encounter two different command names for what appears to be the same example. One reference needs to be corrected.
Required Actions
- Run the three applicable automated checks (
lint:frontmatter,lint:md-links,docs:test) and check the boxes in the checklist, or add explicit N/A annotations for checks that do not apply. - Reconcile the
/git-commitvs/git-commit-messagecommand name incli-plugins.md(see inline comment).
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
3 participants
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
vscode:extension/URI scheme for both flagship and all-collections extensionsCLI Post-Install Usage (docs/getting-started/methods/cli-plugins.md)
/agent <name>Collections Disambiguation (docs/getting-started/install.md)
Post-Install Activation (docs/getting-started/collections.md)
Related Issue(s)
Related to #1519
Type of Change
Select all that apply:
Code & Documentation:
Infrastructure & Configuration:
AI Artifacts:
prompt-builderagent and addressed all feedback.github/instructions/*.instructions.md).github/prompts/*.prompt.md).github/agents/*.agent.md).github/skills/*/SKILL.md)Other:
.ps1,.sh,.py)Sample Prompts (for AI Artifact Contributions)
Testing
Checklist
Required Checks
AI Artifact Contributions
/prompt-analyzeto review contributionprompt-builderreviewRequired Automated Checks
The following validation commands must pass before merging:
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run validate:skillsnpm run lint:md-linksnpm run lint:psnpm run plugin:generatenpm run docs:testSecurity Considerations