microsoft / microsoft/hve-core

docs: reconcile marketplace docs with shared .github/plugin.json manifest model

Open Beginner friendly
#2,690 2 comments 0 reactions 0 assignees View on GitHub
agent-ready documentation good first issue needs-triage
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Component

Documentation

## Bug Description

PR #2689 (commit 278eb12, "fix(plugins): add missing plugin.json to .github directory") replaced the optional generated `plugins//plugin.json` per-package validation with a required shared manifest check at `.github/plugin.json`. `scripts/plugins/Validate-Marketplace.ps1` now requires `.github/plugin.json` to exist and removed the per-package identity/`x-hve`-absence checks against `plugins//plugin.json`.

`docs/getting-started/methods/cli-plugins.md` was updated in the same push to describe the new shared-source-tree/shared-manifest install model (all entries install from the shared `.github` tree via `.github/plugin.json`; component declarations only filter what the CLI loads, not what gets copied).

However, two other documents that describe the same plugin/manifest model were **not** updated and now conflict with the new behavior:

* `docs/customization/packages.md` (`## Recipe Authority` section) still states only `.github/plugin/marketplace.json` is the operational distribution definition and says `x-hve` "never appears in generated `plugin.json` files" — it does not mention the new required shared `.github/plugin.json` manifest at all, nor the "one shared manifest for the whole catalog" model.
* `docs/contributing/ai-artifacts-common.md` (`### Plugin Directory Structure` table) still documents "Root plugin manifest | Generated `plugin.json` for Copilot clients" as if each generated package directory has its own generated manifest — this is stale relative to the shared-manifest contract now enforced by `Validate-Marketplace.ps1`.

## Expected Behavior

`docs/customization/packages.md` and `docs/contributing/ai-artifacts-common.md` should describe the current shared `.github/plugin.json` manifest contract consistently with `docs/getting-started/methods/cli-plugins.md`: a single required shared manifest under `.github/`, package entries in `marketplace.json` selecting components rather than filtering copied files, and generated per-package ZIPs being a separate release-asset concept.

## Steps to Reproduce

1. See commit 278eb128b562f839e884b30a30f0df72d6594f54 (PR #2689) diff to `scripts/plugins/Validate-Marketplace.ps1` (adds required `.github/plugin.json` check, removes per-package `plugins//plugin.json` identity check).
2. Compare against `docs/customization/packages.md` "Recipe Authority" section and `docs/contributing/ai-artifacts-common.md` "Plugin Directory Structure" table, which still describe the prior per-package generated-manifest model.

## Additional Context

* Code: `scripts/plugins/Validate-Marketplace.ps1`, `.github/plugin.json`
* Docs to update: `docs/customization/packages.md`, `docs/contributing/ai-artifacts-common.md`
* Reference (already updated correctly): `docs/getting-started/methods/cli-plugins.md`

> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/31646860922) · auto · 39.4 AIC · ⌖ 2.21 AIC · ⊞ 11.1K · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)

Contributor guide

Open the contributing guide

Research direction

Read docs/getting-started/methods/cli-plugins.md as the current reference, then inspect docs/customization/packages.md and docs/contributing/ai-artifacts-common.md alongside scripts/plugins/Validate-Marketplace.ps1 and .github/plugin.json. Update the two identified sections so they consistently describe the required shared manifest, component selection, and separate ZIP release assets. Done means both documents match the enforced model and no longer describe per-package generated manifests.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, powershell
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.