Merge pull request #28305 from microsoftgraph/main

Merge to publish.

Author: Danipocket

.gdn/.gdnbaselines

@@ -16,16 +16,41 @@
     "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
       "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
       "alternativeSignatures": [
-        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e",
+        "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b"
       ],
-      "target": "update-permissions-reference.ps1",
+      "target": "scripts/update-permissions-reference.ps1",
       "line": 170,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2024-08-26 12:06:54Z"
+    },
+    "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b": {
+      "signature": "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b",
+      "alternativeSignatures": [],
+      "target": "scripts/update-permissions-reference.ps1",
+      "line": 177,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
+    },
+    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
+      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+      "alternativeSignatures": [],
+      "target": "update-permissions-reference-fic.ps1",
+      "line": 179,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
     }
   }
 }

.gdn/.gdnsuppress

@@ -16,16 +16,41 @@
     "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
       "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
       "alternativeSignatures": [
-        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e",
+        "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b"
       ],
-      "target": "update-permissions-reference.ps1",
+      "target": "scripts/update-permissions-reference.ps1",
       "line": 170,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2024-08-26 12:06:54Z"
+    },
+    "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b": {
+      "signature": "11e53a6e53ef601debd4d1a4dc1ca3d451cd0c96df1892e7f5685b8c6d01769b",
+      "alternativeSignatures": [],
+      "target": "scripts/update-permissions-reference.ps1",
+      "line": 177,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
+    },
+    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
+      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+      "alternativeSignatures": [],
+      "target": "update-permissions-reference-fic.ps1",
+      "line": 179,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2026-02-24 12:06:54Z"
     }
   }
 }

.github/prompts/author-api-docs.prompt.md

@@ -77,6 +77,7 @@ Before beginning any documentation process, instruct the author to add all requi
 - Files should be deleted from temp-docstubs after documentation is complete
 - Always reference the temp-docstubs folder when asking for or reading input files
 - Never ask the author to provide absolute file paths outside the workspace
+- **Automated validation:** A validation script prevents temporary files from being accidentally committed (see [Common Process: Validation](#common-process-validation))
 
 ### Common Process: Updating the Changelog
 
@@ -211,10 +212,7 @@ Use the JSON template and examples from **templates/changelog-patterns.md**.
 
 **Step 7: Validate the entry**
 
-Follow the complete validation checklist in **templates/changelog-patterns.md** and run:
-```powershell
-.\validate-changelog-json.ps1
-```
+Follow the complete validation checklist in **templates/changelog-patterns.md** and see [Common Process: Validation](#common-process-validation) for running the validation script.
 
 ### Common Process: Updating What's New
 
@@ -303,6 +301,31 @@ Content-type: application/json
 
 **When promoting from beta to v1.0:** Remove SDK snippets and tab markers for files copied from beta; keep only HTTP examples (see [Scenario 2](#scenario-2-promote-apis-from-beta-to-v10)).
 
+### Common Process: Validation
+
+After making documentation changes, run these validation scripts to ensure compliance:
+
+**Validate changelog JSON files:**
+```powershell
+.\scripts\validate-changelog-json.ps1
+```
+- Validates all changelog files in the `changelog/` folder
+- Checks schema compliance, required properties, and formatting
+- Must pass before committing changelog updates
+
+**Validate temp-docstubs cleanup:**
+```powershell
+.\scripts\validate-temp-docstubs.ps1
+```
+- Verifies that only `temp-docstubs-instructions.md` remains in temp-docstubs folder
+- Prevents accidental commit of temporary input files
+- Run after completing Doc Stubs Cleanup
+
+**When validation fails:**
+- Review error messages to identify issues
+- Correct the problems in the affected files
+- Re-run validation until all checks pass
+
 ---
 
 ### Reference Standards: Namespace Qualification
@@ -719,6 +742,7 @@ Remove "(preview)" from TOC entries as applicable:
 - [ ] All TOC entries updated
 - [ ] Changelog and What's new updated
 - [ ] No markdown lint errors remain
+- [ ] Validation completed (see [Common Process: Validation](#common-process-validation))
 - [ ] Provided summary of all files created/modified to author
 
 ---
@@ -960,6 +984,7 @@ When combining deprecation with new APIs/promotions:
 **Final:**
 - [ ] All Summary items addressed
 - [ ] No markdown lint errors
+- [ ] Validation completed (see [Common Process: Validation](#common-process-validation))
 - [ ] Summary provided to author
 
 ---
@@ -1809,6 +1834,7 @@ Before completing any authoring task, verify:
 - [ ] All TOC changes made if applicable
 - [ ] All properties referencing updated enumerations have been updated
 - [ ] All permissions files copied
+- [ ] Validation completed (see [Common Process: Validation](#common-process-validation))
 - [ ] Provided summary of all files created/modified to author
 
 ---
@@ -1928,6 +1954,7 @@ Before completing Scenario 4 tasks, verify:
 - [ ] Examples use pseudo-values, not data types
 - [ ] No markdown lint errors
 - [ ] Changelog, What's new, and TOC mapping updated only if appropriate
+- [ ] Validation completed (see [Common Process: Validation](#common-process-validation))
 - [ ] Summary of changes provided to author
 
 ---
@@ -1947,6 +1974,10 @@ After completing the documentation work and providing the final summary to the a
    - If the author confirms, delete all files from `temp-docstubs` folder except `temp-docstubs-instructions.md`
    - Confirm deletion: "Cleanup complete. All temporary files have been removed from the temp-docstubs folder."
 
+4. **Validate cleanup:**
+   - See [Common Process: Validation](#common-process-validation) for validation instructions
+   - If validation passes, confirm: "Validation passed: temp-docstubs folder is ready for commit."
+
 **Note:** The `temp-docstubs-instructions.md` file should never be deleted as it provides important guidance for future authoring sessions.
 
 If you cannot resolve all issues or confirm information against API.md, notify the author to manually address remaining problems.

.github/prompts/review-api-docs.prompt.md

@@ -49,6 +49,62 @@ While not required, providing these files significantly improves review quality
 
 ---
 
+## Common Process: Validation
+
+As part of the review process, validate that automated validation scripts pass. These scripts ensure compliance with required standards and prevent common errors.
+
+### Validate changelog JSON files
+
+After reviewing changelog changes, run the changelog validation script:
+
+```powershell
+.\scripts\validate-changelog-json.ps1
+```
+
+**Purpose:**
+- Validates all changelog files in the `changelog/` folder against the schema
+- Checks schema compliance, required properties, and formatting
+- Ensures proper JSON structure and required metadata
+
+**What it validates:**
+- Complete record structure (ChangeList array + Id, Cloud, Version, CreatedDateTime, WorkloadArea, SubArea)
+- GUID consistency across ChangeList items and record-level Id
+- Cloud value is "prd" (or "Prod" - case variations allowed)
+- Version value is "v1.0" or "beta"
+- CreatedDateTime in ISO 8601/RFC 3339 format with fractional seconds and Z suffix
+- WorkloadArea and SubArea match CDK taxonomy
+
+**Must pass before:** Approving PR with changelog updates
+
+### Validate temp-docstubs cleanup (if applicable)
+
+If reviewing changes that involved the temp-docstubs folder, verify cleanup:
+
+```powershell
+.\scripts\validate-temp-docstubs.ps1
+```
+
+**Purpose:**
+- Verifies that only `temp-docstubs-instructions.md` remains in temp-docstubs folder
+- Prevents accidental commit of temporary input files (autogenerated doc stubs, API.md files, changelog files)
+
+**Must pass before:** Approving PR that touched temp-docstubs folder
+
+### When validation fails
+
+**If validation scripts report errors:**
+1. Review error messages to identify specific issues
+2. Flag the issues in your review report under "Critical Issues (Must Fix)"
+3. Provide guidance on correcting the problems
+4. Request author to re-run validation after fixes
+5. Do not approve until all validation checks pass
+
+**Common validation failures:**
+- Changelog: Missing required properties, incorrect date format, malformed JSON
+- temp-docstubs: Temporary files not removed before commit
+
+---
+
 ## Review Guidelines
 
 The review process applies guidelines from three authoritative sources. You should check all sets of guidelines without duplication:
@@ -145,22 +201,24 @@ For files in `api-reference/v1.0/resources/` and `api-reference/beta/resources/`
 
 ### Changelog Files Review
 
-For files in `changelog/`, verify structure matches [templates/changelog-patterns.md](templates/changelog-patterns.md).
+For files in `changelog/`, verify structure matches [templates/changelog-patterns.md](templates/changelog-patterns.md) and run validation (see [Common Process: Validation](#common-process-validation)).
 
 **Required Elements:**
 - [ ] Complete changelog record structure (ChangeList array + Id, Cloud, Version, CreatedDateTime, WorkloadArea, SubArea)
 - [ ] Same GUID in all ChangeList items and record-level Id
-- [ ] Cloud value is "prd"
+- [ ] Cloud value is "prd" (or "Prod")
 - [ ] Version value is "v1.0" or "beta"
 - [ ] CreatedDateTime in ISO 8601/RFC 3339 format with fractional seconds and Z suffix (e.g., "2025-11-17T17:38:10.4694969Z")
 - [ ] Description links use full URLs with en-us locale
 - [ ] WorkloadArea and SubArea match CDK taxonomy (https://aka.ms/msgraphcdk)
+- [ ] Validation script passes (see [Common Process: Validation](#common-process-validation))
 
 **Common Issues:**
 - [ ] Multiple unrelated API elements in single ChangeList item
 - [ ] Missing or vague descriptions
 - [ ] Malformed links or missing en-us locale
 - [ ] Incomplete record structure (missing metadata)
+- [ ] Validation script failures
 
 ### Version-Specific Validation
 
@@ -252,7 +310,16 @@ Group files by type:
 
 For each file, apply the appropriate review checklist from above.
 
-### Step 4: Report Findings
+### Step 4: Run Validation Scripts
+
+Run automated validation scripts to ensure compliance (see [Common Process: Validation](#common-process-validation)):
+
+1. **If changelog files were modified:** Run `.\scripts\validate-changelog-json.ps1`
+2. **If temp-docstubs folder is present in the branch:** Run `.\scripts\validate-temp-docstubs.ps1`
+
+Include validation results in your review report. Flag any validation failures as critical issues.
+
+### Step 5: Report Findings
 
 Provide a structured review report:
 
@@ -275,7 +342,7 @@ For each file with issues, list:
 - Suggested fix (when applicable)
 - Line numbers or section references
 
-### Step 5: Optional - Suggest Fixes
+### Step 6: Optional - Suggest Fixes
 
 If requested, provide specific edits to fix identified issues.
 
@@ -304,6 +371,10 @@ If requested, provide specific edits to fix identified issues.
 **Files with Issues:** 3
 **Files Approved:** 5
 
+**Validation Results:**
+- ✓ Changelog validation passed (.\scripts\validate-changelog-json.ps1)
+- ✓ temp-docstubs validation passed (.\scripts\validate-temp-docstubs.ps1)
+
 ---
 
 ## Critical Issues (Must Fix)
@@ -345,6 +416,8 @@ If requested, provide specific edits to fix identified issues.
   - Current: "Added property"
   - Suggestion: "Added the **newProperty** property to enable..."
 
+### API overview updates
+- If an API Overview topic covers the same APIs, consider updating it to reflect new capabilities and changes for better discoverability and context for users.
 ---
 
 ## Files Approved
@@ -362,11 +435,13 @@ If requested, provide specific edits to fix identified issues.
 
 1. **Start with file classification** - Understanding file types helps apply the right rules
 2. **Check metadata first** - Validate namespace, doc_type, and version before content review
-3. **Use find/search** - Look for TODO placeholders across all files
-4. **Validate links** - Ensure all referenced resources and types exist and are correctly linked
-5. **Check consistency** - Resource names, namespaces, and terminology should be consistent across all files
-6. **Compare with context** - If Summary of API changes (documentation-plan.md file) or API.md provided, validate against them first
-7. **Flag autogeneration issues** - If doc stubs appear to have over-generated content, mention this
+3. **Run validation scripts early** - Check changelog and temp-docstubs validation before detailed review
+4. **Use find/search** - Look for TODO placeholders across all files
+5. **Validate links** - Ensure all referenced resources and types exist and are correctly linked
+6. **Check consistency** - Resource names, namespaces, and terminology should be consistent across all files
+7. **Compare with context** - If Summary of API changes (documentation-plan.md file) or API.md provided, validate against them first
+8. **Flag autogeneration issues** - If doc stubs appear to have over-generated content, mention this
+9. **Include validation results** - Always report validation script results in your review summary
 
 ---