Dynamically generate Docusaurus collection pages from YAML manifests

[WilliamBerryiii]

Summary

After PR #1316 (closes #1256) introduced auto-generated collection.md files from YAML manifests for GitHub and extension packaging, Docusaurus still maintains two parallel, hand-coded data sources that duplicate information already available in the collection YAML manifests. These should be replaced with dynamically generated content sourced from the same YAML manifests.

Problem

The Docusaurus site has two hand-maintained sources that duplicate collection metadata:

1. docs/getting-started/collections.md — A manually written table listing all 14 collections with descriptions, per-type artifact counts (Agents, Prompts, Instructions, Skills), maturity levels, and marketplace install links. Also includes a Mermaid dependency diagram.

2. docs/docusaurus/src/data/collectionCards.ts — 12 hard-coded CollectionCardDefinition objects with name, description, maturity, and href fields. The resolveCollectionCards(counts) function merges artifact counts from customFields.collectionCounts at runtime.

When a collection is added, renamed, or updated, maintainers must update three separate locations: the YAML manifest, collections.md, and collectionCards.ts. This creates drift risk and maintenance overhead.

Existing Infrastructure

docusaurus.config.js already reads collection YAML manifests at build time via countYamlPaths() to populate customFields.collectionCounts, which feeds artifact count badges on the homepage. This means the YAML-to-Docusaurus pipeline partially exists — it just needs to be extended to cover descriptions, maturity, and page content.

Proposed Approach

Phase 1: Replace collectionCards.ts hard-coded definitions

• Source card definitions (name, description, maturity, href) from collection YAML manifests at build time via docusaurus.config.js custom fields.
• Remove the 12 hard-coded CollectionCardDefinition objects from collectionCards.ts.
• Keep resolveCollectionCards() as a thin adapter that merges the YAML-sourced definitions with counts.

Phase 2: Auto-generate the collections.md page

• Generate docs/getting-started/collections.md (or a replacement) from collection YAML manifests and their companion collection.md files.
• Preserve the existing table structure (description, artifact counts, maturity, install links) but source all data dynamically.
• Consider whether the Mermaid dependency diagram can also be generated from manifest metadata.

Phase 3: Add per-collection Docusaurus pages (optional)

• Generate individual Docusaurus pages for each collection, sourced from the auto-generated collections/*.collection.md files.
• Add a "Collections" category to sidebars.js linking to individual collection pages.
• Update card hrefs to point to individual collection pages instead of the shared overview.

Files to Modify

File	Current State	Change
docs/docusaurus/src/data/collectionCards.ts	12 hard-coded card definitions	Source from YAML manifests via custom fields
docs/getting-started/collections.md	Hand-maintained table with 14 collections	Auto-generate from YAML manifests
docs/docusaurus/docusaurus.config.js	Reads YAML for counts only via countYamlPaths()	Extend to read descriptions, maturity, install links
docs/docusaurus/sidebars.js	No collection category	Add collection category (Phase 3)
docs/docusaurus/src/pages/index.tsx	Renders cards from resolveCollectionCards()	No change expected (adapter pattern preserved)

Acceptance Criteria

• Homepage collection cards are sourced from YAML manifests with zero hard-coded definitions
• The collections overview page content is generated from YAML manifests
• Adding a new collection requires only updating the YAML manifest (and running generation)
• npm run docs:build succeeds with onBrokenLinks: 'throw'
• No visual regression on the homepage or collections page

Context

• PR feat(collections): auto-generate collection.md with maturity filtering #1316 / Issue collection.md: auto-generation, maturity safety, and custom header support #1256: Introduced auto-generated collection.md files for GitHub and extension contexts
• The auto-generated files live at collections/*.collection.md, which is outside the Docusaurus docs include path
• docusaurus.config.js already demonstrates the pattern of reading YAML manifests at build time