feat(scripts): promote docs frontmatter fields from recommended to required

.github/instructions/docusaurus-edits.instructions.md

@@ -9,29 +9,48 @@ These instructions apply automatically when editing any file under `docs/`. Foll
 
 ## Frontmatter
 
-Every documentation page requires these frontmatter fields:
+Every documentation page requires these frontmatter fields. `npm run lint:frontmatter` fails when any of them is missing or empty, and the check runs in PR validation:
 
 * `title`: Page title displayed in the browser tab and sidebar
 * `description`: One-sentence summary for SEO and social sharing
-* `sidebar_position`: Integer controlling page order within its category (1, 2, 3...)
+* `author`: Author or team responsible for the content
+* `ms.date`: Last review or update date in `YYYY-MM-DD` format
+* `ms.topic`: One of `overview`, `concept`, `tutorial`, `reference`, `how-to`, `troubleshooting`, `architecture`
+* `keywords`: Non-empty list of content categorization terms
 
 Optional fields:
 
+* `sidebar_position`: Integer controlling page order within its category (1, 2, 3...)
 * `sidebar_label`: Override the sidebar display text when it should differ from `title`
-* `keywords`: Array of terms for search indexing
 * `tags`: Array of tags for content categorization
+* `estimated_reading_time`: Positive integer in minutes
 
 ```yaml
 ---
 title: The RPI Workflow
 description: How the Research-Plan-Implement-Review loop structures AI-assisted development
+author: Microsoft
+ms.date: 2026-08-04
+ms.topic: concept
+keywords:
+  - rpi
+  - research
+  - plan
+  - implement
+  - review
 sidebar_position: 2
 sidebar_label: RPI Workflow
-keywords: [rpi, research, plan, implement, review]
 tags: [build-the-work, rpi, workflow]
 ---
 ```
 
+Update `ms.date` to the current date whenever you review or change a page.
+
+Two subtrees follow different rules:
+
+* Architecture Decision Records under `docs/planning/adrs/` are governed by `adr-frontmatter.schema.json`. They use `tags` for categorization and must not declare `keywords`.
+* Pages under `docs/reference/` are generated by `npm run docs:generate`, which emits the required fields automatically. Do not hand-edit their frontmatter.
+
 ## Admonitions
 
 Both Docusaurus admonitions (`:::note`, `:::tip`, `:::warning`) and GitHub-style alerts (`> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`) are supported. GitHub-style alerts render correctly in Docusaurus via `remark-github-blockquote-alert` and on GitHub natively. Prefer GitHub-style alerts for content that must render on both platforms.
@@ -167,10 +186,15 @@ Structure pages so a reader who stops after section 2 has gotten value. If they
 
 ## Search Keywords
 
-Include a `keywords` array in frontmatter for pages that serve as reference or entry points. Keywords should include terms users might search for, not just terms used on the page:
+Every page carries a non-empty `keywords` array, so treat the field as a search-tuning opportunity rather than a checkbox. Choose terms users might search for, not just terms already used on the page:
 
 ```yaml
-keywords: [backlog, triage, sprint planning, github issues, prioritization]
+keywords:
+  - backlog
+  - triage
+  - sprint planning
+  - github issues
+  - prioritization
 ```
 
 ## Educational Tone

docs/agents/project-planning/README.md

@@ -3,8 +3,12 @@ title: Project Planning Agents
 description: Agents for requirements gathering, architecture decisions, and security planning
 sidebar_position: 1
 author: Microsoft
-ms.date: 2026-06-29
+ms.date: 2026-08-01
 ms.topic: concept
+keywords:
+  - project planning
+  - agents
+  - requirements
 ---
 
 Four agents and **three** portable skills support structured project planning across requirements, architecture, security, **and performance**. Each agent follows a guided workflow to produce specific deliverables, from business requirements documents to security assessment plans and reliability targets.

docs/agents/project-planning/adr-creation.md

@@ -3,8 +3,12 @@ title: ADR Creator
 description: Redirect to the canonical ADR Creator agent and identity instructions
 sidebar_position: 3
 author: Microsoft
-ms.date: 2026-06-27
+ms.date: 2026-08-01
 ms.topic: tutorial
+keywords:
+  - adr creator
+  - architecture decision record
+  - project planning
 ---
 
 The canonical agent definition has moved. The ADR Creator agent now lives alongside the other repository agents, and its behavior is governed by a dedicated identity instructions file.

docs/agents/project-planning/arch-diagram-builder.md

@@ -3,8 +3,12 @@ title: Architecture Diagrams Skill
 description: Use the portable architecture-diagrams skill to generate ASCII or Mermaid architecture diagrams from infrastructure source files
 sidebar_position: 4
 author: Microsoft
-ms.date: 2026-06-29
+ms.date: 2026-08-01
 ms.topic: how-to
+keywords:
+  - architecture diagrams
+  - mermaid
+  - infrastructure as code
 ---
 
 The [architecture-diagrams skill](pathname://../../../.github/skills/hve-core/architecture-diagrams/SKILL.md) is the recommended way to generate ASCII or Mermaid architecture diagrams from infrastructure source files. It is especially useful for ADRs, onboarding guides, and design reviews when you want a quick, text-based view of a system's structure.

docs/agents/project-planning/brd-prd-builders.md

@@ -3,8 +3,12 @@ title: BRD & PRD Builders
 description: Twin agents for creating business and product requirements documents through guided Q&A
 sidebar_position: 2
 author: Microsoft
-ms.date: 2026-06-29
+ms.date: 2026-08-01
 ms.topic: tutorial
+keywords:
+  - brd builder
+  - prd builder
+  - requirements
 ---
 
 The BRD Builder and PRD Builder share a common architecture for producing requirements documents through structured question-and-answer sessions. Both are driven by the `requirements-author` skill, which loads each phase's guidance on demand. The BRD Builder runs a three-phase lifecycle focused on business justification, and the PRD Builder runs a seven-phase lifecycle focused on product specifications with measurable requirements.

docs/agents/project-planning/security-plan-creator.md

@@ -3,8 +3,12 @@ title: Security Planner (Moved)
 description: This page has moved to the Security Planning documentation
 sidebar_position: 5
 author: Microsoft
-ms.date: 2026-06-29
+ms.date: 2026-08-01
 ms.topic: tutorial
+keywords:
+  - security planner
+  - security planning
+  - project planning
 ---
 
 This page has moved. The former Security Plan Creator agent is now the **Security Planner**, documented under the Security agents section.

docs/architecture/README.md

@@ -5,6 +5,10 @@ sidebar_position: 1
 author: Microsoft
 ms.date: 2026-08-01
 ms.topic: concept
+keywords:
+  - architecture
+  - system design
+  - hve core
 ---
 
 HVE Core provides a Copilot customization framework that enables teams to extend GitHub Copilot with project-specific context, workflows, and automation. The framework organizes reusable AI artifacts, development scripts, and documentation into a cohesive system that integrates with VS Code and GitHub workflows.

docs/architecture/ai-artifacts.md

@@ -5,6 +5,11 @@ sidebar_position: 2
 author: Microsoft
 ms.date: 2026-08-03
 ms.topic: concept
+keywords:
+  - ai artifacts
+  - agents
+  - prompts
+  - instructions
 ---
 
 HVE Core provides a four-tier artifact system for customizing GitHub Copilot behavior. Each tier serves a distinct purpose in the delegation chain, enabling structured, reusable AI guidance that flows from user intent to technology-specific standards and executable utilities.

docs/architecture/testing.md

@@ -5,6 +5,10 @@ sidebar_position: 4
 author: Microsoft
 ms.date: 2026-08-01
 ms.topic: concept
+keywords:
+  - testing
+  - pester
+  - powershell
 ---
 
 ## Overview

docs/architecture/workflows.md

@@ -5,6 +5,10 @@ sidebar_position: 3
 author: WilliamBerryiii
 ms.date: 2026-08-04
 ms.topic: overview
+keywords:
+  - github actions
+  - workflows
+  - ci/cd
 ---
 
 HVE Core uses GitHub Actions for continuous integration, quality validation, security scanning, and release automation. The workflow architecture emphasizes reusable components and parallel execution for fast feedback.

docs/contributing/ai-artifacts-common.md

@@ -5,6 +5,10 @@ sidebar_position: 2
 author: Microsoft
 ms.date: 2026-08-03
 ms.topic: reference
+keywords:
+  - contributing
+  - ai artifacts
+  - standards
 ---
 
 This document defines shared standards, conventions, and quality gates that apply to **all** AI artifact contributions to hve-core (agents, prompts, instructions, and skills).

docs/contributing/custom-agents.md

@@ -5,6 +5,10 @@ sidebar_position: 5
 author: Microsoft
 ms.date: 2026-08-02
 ms.topic: how-to
+keywords:
+  - contributing
+  - custom agents
+  - standards
 ---
 
 This guide defines the requirements, standards, and best practices for contributing GitHub Copilot agent files (`.agent.md`) to the hve-core library.

docs/contributing/documentation-maintenance.md

@@ -3,7 +3,7 @@ title: Documentation Maintenance
 description: How the automated ms.date freshness system detects and flags stale documentation for review
 sidebar_position: 8
 author: Microsoft
-ms.date: 2026-07-08
+ms.date: 2026-08-01
 ms.topic: reference
 keywords:
   - documentation
@@ -92,9 +92,22 @@ The workflow runs on Mondays at 09:00 UTC via `cron: '0 9 * * 1'`. Use `workflow
 
 ## Requirements
 
-* All documentation files under `docs/` must include a `ms.date` frontmatter field.
-* Dates must follow `YYYY-MM-DD` format.
-* Contributors are expected to update `ms.date` whenever they review or update a documentation file.
+Every documentation file under `docs/` must carry these frontmatter fields. `npm run lint:frontmatter` fails when any of them is missing or empty.
+
+| Field         | Requirement                                                                                         |
+|---------------|-----------------------------------------------------------------------------------------------------|
+| `title`       | Page title.                                                                                         |
+| `description` | One-line summary of the page content.                                                               |
+| `author`      | Author or team responsible for the content.                                                         |
+| `ms.date`     | Last review or update date in `YYYY-MM-DD` format.                                                  |
+| `ms.topic`    | One of `overview`, `concept`, `tutorial`, `reference`, `how-to`, `troubleshooting`, `architecture`. |
+| `keywords`    | Non-empty list of content categorization keywords.                                                  |
+
+Architecture Decision Records under `docs/planning/adrs/` are governed by `adr-frontmatter.schema.json` instead. They use `tags` for categorization and must not declare `keywords`.
+
+Pages under `docs/reference/` are generated by `npm run docs:generate`, which emits these fields automatically. Do not hand-edit their frontmatter.
+
+Contributors are expected to update `ms.date` whenever they review or update a documentation file.
 
 <!-- markdownlint-disable MD036 -->
 *🤖 Crafted with precision by ✨Copilot following brilliant human instruction,

docs/contributing/instructions.md

@@ -5,6 +5,10 @@ sidebar_position: 3
 author: Microsoft
 ms.date: 2026-08-02
 ms.topic: how-to
+keywords:
+  - contributing
+  - instructions
+  - standards
 ---
 
 This guide defines the requirements, standards, and best practices for contributing GitHub Copilot instruction files (`.instructions.md`) to the hve-core library.

docs/contributing/prompts.md

@@ -5,6 +5,10 @@ sidebar_position: 4
 author: Microsoft
 ms.date: 2026-08-02
 ms.topic: how-to
+keywords:
+  - contributing
+  - prompts
+  - standards
 ---
 
 This guide defines the requirements, standards, and best practices for contributing GitHub Copilot prompt files (`.prompt.md`) to the hve-core library.

docs/contributing/release-process.md

@@ -5,6 +5,10 @@ sidebar_position: 9
 ms.date: 2026-08-03
 ms.topic: how-to
 author: WilliamBerryiii
+keywords:
+  - release process
+  - release-please
+  - publishing
 ---
 
 ## Overview

docs/docusaurus/README.md

@@ -2,8 +2,12 @@
 title: HVE Core Documentation Site
 description: Docusaurus 3 documentation site for HVE Core
 author: Microsoft
-ms.date: 2026-07-16
+ms.date: 2026-08-01
 ms.topic: reference
+keywords:
+  - docusaurus
+  - documentation site
+  - build
 ---
 
 ## Local Development

docs/getting-started/methods/cli-plugins.md

@@ -5,6 +5,10 @@ sidebar_position: 2
 author: Microsoft
 ms.date: 2026-08-02
 ms.topic: how-to
+keywords:
+  - copilot cli
+  - plugins
+  - installation
 ---
 
 Install the complete HVE Core component set as a Copilot CLI plugin for terminal-based AI-assisted development workflows.

docs/getting-started/packages.md

@@ -5,6 +5,10 @@ sidebar_position: 3
 author: Microsoft
 ms.date: 2026-08-03
 ms.topic: overview
+keywords:
+  - packages
+  - channels
+  - identity
 ---
 
 ## Package Choices

docs/planning/brds/brd-builder-agent-brd.md

@@ -3,8 +3,12 @@ brd_id: "BRD-2026-Q2-BRD-BUILDER"
 title: "BRD Builder Agent Requirements"
 description: "Business Requirements Document for the BRD Builder agent, capturing business goals, requirements, and traceability for the project-planning collection's BRD authoring workflow."
 author: "HVE Core Maintainers"
-ms.date: "2026-06-28"
+ms.date: "2026-08-01"
 ms.topic: "reference"
+keywords:
+  - brd builder
+  - business requirements
+  - project planning
 status: "approved"
 version: "1.0.0"
 owners: ["microsoft/hve-core"]

docs/planning/brds/docusaurus-accessibility-conformance-brd.md

@@ -3,8 +3,12 @@ title: "Docusaurus Accessibility Conformance - Business Requirements Document"
 description: "Business requirements for achieving and continuously verifying WCAG 2.1 AA accessibility conformance on the HVE-Core documentation site"
 sidebar_position: 2
 author: "HVE-Core Maintainers"
-ms.date: 2026-06-30
+ms.date: 2026-08-01
 ms.topic: reference
+keywords:
+  - accessibility
+  - wcag
+  - business requirements
 ---
 
 Version 0.1 (Draft) | Status In Progress | Owner HVE-Core Maintainers | Sponsor Core Maintainers & Repo Writers | Date 2026-06-13 | Business Unit HVE-Core (Open Source)

docs/planning/brds/prd-builder-agent-brd.md

@@ -3,8 +3,12 @@ brd_id: "BRD-2026-Q2-PRD-BUILDER"
 title: "PRD Builder Agent Requirements"
 description: "Business Requirements Document for the PRD Builder agent, capturing business goals, requirements, and traceability for migrating PRD authoring onto the shared requirements-author skill."
 author: "HVE Core Maintainers"
-ms.date: "2026-06-28"
+ms.date: "2026-08-01"
 ms.topic: "reference"
+keywords:
+  - prd builder
+  - business requirements
+  - project planning
 status: "approved"
 version: "1.0.0"
 owners: ["microsoft/hve-core"]

docs/planning/brds/privacy-planner-brd.md

@@ -3,8 +3,12 @@ brd_id: "BRD-2026-Q2-PRIVACY-PLANNER"
 title: "Privacy Planner BRD"
 description: "Business requirements for adding a first-class Privacy Planner, privacy-standards skill, and Privacy Reviewer to the hve-core planner family."
 author: "HVE Core Maintainers"
-ms.date: 2026-06-30
+ms.date: 2026-08-01
 ms.topic: reference
+keywords:
+  - privacy planner
+  - privacy
+  - business requirements
 status: "approved"
 version: "1.0.0"
 owners: ["microsoft/hve-core"]

docs/planning/prds/brd-builder-agent-prd.md

@@ -3,8 +3,12 @@ prd_id: "PRD-2026-Q2-BRD-BUILDER"
 title: "BRD Builder Agent Product Requirements"
 description: "Product Requirements Document for the BRD Builder agent, defining product goals, functional requirements, and acceptance criteria for the guided Business Requirements Document authoring workflow in the project-planning collection."
 author: "HVE Core Maintainers"
-ms.date: "2026-06-29"
+ms.date: "2026-08-01"
 ms.topic: "reference"
+keywords:
+  - brd builder
+  - product requirements
+  - project planning
 status: "approved"
 version: "1.0.0"
 owners: ["microsoft/hve-core"]

docs/planning/prds/docusaurus-accessibility-conformance-prd.md

@@ -3,8 +3,12 @@ title: "Docusaurus Accessibility Conformance - Product Requirements Document"
 description: "Product requirements for achieving and continuously verifying WCAG 2.2 AA accessibility conformance on the HVE-Core documentation site"
 sidebar_position: 3
 author: "HVE-Core Maintainers"
-ms.date: 2026-06-30
+ms.date: 2026-08-01
 ms.topic: reference
+keywords:
+  - accessibility
+  - wcag
+  - product requirements
 ---
 
 <!-- markdownlint-disable-file -->