fix(docs): derive collection artifact counts from YAML at build time

[katriendg]

Replaced hardcoded artifact counts in the Docusaurus collection cards with build-time derivation from collection YAML manifests. Every time a skill, agent, or prompt was added to a collection, collectionCards.ts required a manual count update that could silently break the site. The counts are now computed automatically from collections/*.collection.yml during the Docusaurus build.

Contributing documentation and the PR template were updated to include npm run docs:test as a required validation step so contributors know to verify counts after collection changes.

Description

Build-Time Artifact Count Derivation

Eliminates the manual update bottleneck by reading collection YAML manifests at build time and injecting counts via Docusaurus customFields.

• Introduced countYamlPaths() in docusaurus.config.js to read each collections/*.collection.yml and count - path: entries, exposing the result map through customFields.collectionCounts
• Removed all hardcoded artifacts integers from the 12 card definitions in collectionCards.ts and introduced the CollectionCardDefinition interface that separates static metadata from dynamic counts
• Replaced the static collectionCards and metaCollections exports with pure resolver functions resolveCollectionCards(counts) and resolveMetaCollections(counts) that accept a counts record at runtime
• Updated index.tsx to read collectionCounts from useDocusaurusContext() and pass them through resolveCollectionCards() wrapped in useMemo
• Added three previously missing collections to the count list: gitlab, jira, and rai-planning

Test Infrastructure

• Added a useDocusaurusContext mock returning empty collectionCounts for Jest component tests
  • Registered in jest.config.js via moduleNameMapper
• Updated collectionCards.test.ts to import the new collectionCardDefinitions, resolveCollectionCards, and resolveMetaCollections exports
  • Tests now build counts dynamically from YAML rather than asserting against hardcoded values
  • Moved countYamlPaths() to module scope for reuse across test suites

Documentation and PR Template

• Added npm run docs:test to the Required Automated Checks section in the PR template
• Added step 8 in ai-artifacts-common.md instructing contributors to run npm run docs:test after collection manifest updates
• Added npm run docs:test to the automated validation command list in skills.md

Related Issue(s)

Fixes #1248
Fixes #1249

Type of Change

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

• Diff-based analysis: Verified all 9 changed files against the two commits; changes are consistent with the final squashed state.
• Security analysis: No sensitive data, credentials, or privilege escalation. fs.readFileSync runs at build time only, not in the browser bundle.
• All 8 required automated checks passed: lint:md, spell-check, lint:frontmatter, validate:skills, lint:md-links, lint:ps, plugin:generate, docs:test.
• Manual testing was not performed.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate
• Docusaurus tests: npm run docs:test

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A — no security script changes)

Additional Notes

• The countYamlPaths() regex (^\s*- path:) is consistent with the YAML structure used across all collection manifests.
• collectionCardDefinitions lists 12 collections; docusaurus.config.js counts 13 (includes hve-core-all for the meta-collection).
• Existing tests cross-validate counts by independently reading YAML files, providing a safety net against regex drift.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.71%. Comparing base (84ddd5d) to head (9cfee62).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1275      +/-   ##
==========================================
- Coverage   87.72%   87.71%   -0.02%     
==========================================
  Files          61       61              
  Lines        9320     9320              
==========================================
- Hits         8176     8175       -1     
- Misses       1144     1145       +1     

Flag	Coverage Δ
pester	85.31% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Advisory review, this PR is from a maintainer. Findings are informational only.

Review Overview

This PR cleanly eliminates the manual artifact-count maintenance burden in the Docusaurus collection cards by reading YAML manifests at build time. The architecture — separating static collectionCardDefinitions from dynamic resolveCollectionCards/resolveMetaCollections resolvers, injecting counts via customFields, and cross-validating with independent YAML reads in tests — is well-designed and idiomatic for Docusaurus. The documentation updates are consistent and the test infrastructure (mock + updated test) is correct.

Three minor advisory observations are left as inline comments.

---

Issue Alignment

✅ PR links Fixes #1248 and Fixes #1249. Based on the description, both issues relate to the manual-count maintenance problem. The changes directly address this by deriving counts automatically. Three previously missing collections (gitlab, jira, rai-planning) are added to the count list, which appears consistent with fixing a gap.

No scope creep detected.

---

PR Template Compliance

⚠️ Type of Change — only "Documentation update" is checked. The PR makes significant TypeScript/JavaScript code changes: a new CollectionCardDefinition interface, two new exported resolver functions, a new mock, and build configuration additions. "Documentation update" alone does not accurately describe these changes. A "New feature" checkbox (or at minimum a note under "Other") would better reflect the nature of the code refactor.

All other template sections are filled in correctly. Required Automated Checks are all marked as passed.

---

Coding Standards

✅ Changed TypeScript and JavaScript files do not fall under any instruction file's applyTo patterns in this repository (instructions cover .ps1, .sh, .py, .cs, .rs, .tf, .bicep, and markdown). No convention violations detected against the applicable instruction files.

Markdown documentation changes (.md files) follow the markdown conventions — no heading skips, proper frontmatter, and concise additions.

---

Code Quality

Three advisory observations (inline):

1. index.tsx line 13 — Unsafe as cast on customFields.collectionCounts bypasses the unknown type from Docusaurus's typing. A nullish-coalescing fallback would prevent a hard crash if the field is absent.
2. collectionCards.ts line 101 — ?? 0 silently swallows name mismatches between collectionCardDefinitions and collectionNames in docusaurus.config.js. Test coverage mitigates this, but a dev-mode console.warn would surface the issue earlier in the contribution loop.
3. docusaurus.config.js line 14 — fs.readFileSync throws a generic ENOENT on a missing YAML. A descriptive error message naming the offending collection would improve DX during collection renames or additions.

No bugs, security issues, breaking changes, or resource leaks detected.

---

Action Items

These are informational suggestions only (advisory mode). No changes are required for merge:

• Consider adding "New feature" to the Type of Change checkboxes to accurately reflect the code refactoring.
• Optionally harden the type assertion in index.tsx and the error message in docusaurus.config.js per the inline suggestions.

Note

🔒 Integrity filter blocked 2 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1248 issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1249 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

Generated by PR Review for issue #1275