microsoft / microsoft/hve-core
docs: reconcile marketplace docs with shared .github/plugin.json manifest model
- 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
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