Merge pull request #28508 from microsoftgraph/main

Merge to publish.

Author: Danipocket

.gdn/.gdnbaselines

@@ -40,17 +40,17 @@
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2026-02-24 12:06:54Z"
     },
-    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
-      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+    "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915": {
+      "signature": "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915",
       "alternativeSignatures": [],
-      "target": "update-permissions-reference-fic.ps1",
+      "target": "scripts/update-permissions-reference-fic.ps1",
       "line": 179,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
-      "createdDate": "2026-02-24 12:06:54Z"
+      "createdDate": "2026-03-24 12:06:54Z"
     }
   }
 }

.gdn/.gdnsuppress

@@ -40,17 +40,17 @@
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2026-02-24 12:06:54Z"
     },
-    "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96": {
-      "signature": "261f3837d9978ecb7637c62a4ced8a0eb843e19a07557738ce232dc24410ac96",
+    "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915": {
+      "signature": "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915",
       "alternativeSignatures": [],
-      "target": "update-permissions-reference-fic.ps1",
+      "target": "scripts/update-permissions-reference-fic.ps1",
       "line": 179,
       "memberOf": [
         "default"
       ],
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
-      "createdDate": "2026-02-24 12:06:54Z"
+      "createdDate": "2026-03-24 12:06:54Z"
     }
   }
 }

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

@@ -603,6 +603,19 @@ Use the following format when reporting file processing results, so output is co
 ⚠️ Blocked: [list with reasons, or "None"]
 ```
 
+**Mid-phase validation** (required at every ⏸ phase gate, before moving to the next phase):
+
+Re-read each file completed in the current phase and verify it meets expectations for its file type. Output a validation checklist:
+
+```
+✅ Phase [N] Validation
+- [file1.md]: H1 ✓ | Namespace ✓ | Properties table ✓ | JSON representation ✓
+- [file2.md]: H1 ✓ | Namespace ✓ | Permissions ✓ | HTTP request ✓ | Examples ✓
+- [file3.md]: H1 ✓ | Namespace ✓ | Properties table ✗ (missing "newProperty") — FIXING
+```
+
+Fix any failures before proceeding to the next phase. Do not defer fixes to end-of-session.
+
 ## State Tracking
 
 Maintain a running progress tracker throughout the session. After each file or batch of files, update and display:
@@ -625,8 +638,9 @@ For Documentation Plans with many files (10+):
 1. **Group by type:** resources, API methods, enumerations, permissions, supporting files
 2. **Process in batches of 5 files** — complete all steps for each file before moving to the next
 3. **After each batch**, output a phase status summary (see [Structured Output Format](#structured-output-format))
-4. **Present the execution plan upfront** and proceed unless the author objects — avoid blocking confirmations for each batch when the Documentation Plan is clear
-5. **If the plan exceeds 20 files**, create a numbered task list at the start, group into batches, and checkpoint progress after each batch
+4. **Verify each batch before proceeding:** Re-read every file in the completed batch and confirm it contains the expected sections (e.g., H1, namespace, Permissions, HTTP request, Examples for API files; H1, namespace, Properties table, JSON representation for resource files). Fix any issues before starting the next batch.
+5. **Present the execution plan upfront** and proceed unless the author objects — avoid blocking confirmations for each batch when the Documentation Plan is clear
+6. **If the plan exceeds 20 files**, after the first batch completes and is verified, **stop and ask the author to confirm quality** before continuing. This catches systematic errors early.
 
 ## Decision Trees for Ambiguous Cases
 
@@ -702,6 +716,8 @@ Report any inconsistencies in the final summary to the author.
 
 The following checks apply to every documentation scenario. Scenario-specific checklists add additional items on top of these.
 
+> **IMPORTANT:** For each checklist item, re-read the actual file content to confirm — do not check items from memory.
+
 **For all files (new and updated):**
 - [ ] All required sections are present and in correct order
 - [ ] Headings match the expected format

.github/prompts/author-api-docs/deprecate-retire.md

@@ -214,10 +214,15 @@ Retirement is the final stage of the API lifecycle — the deprecated API has re
 
 ### Inputs for retirement
 
-The Documentation Plan must explicitly identify:
-- Which resources (entity types, complex types) are being retired (marked as "Deleted" or "Removed")
-- Which API operation files are linked to the retired resources
-- **Dependency analysis for related types:** Complex types referenced as property return types and entity types referenced as relationship targets must be explicitly called out. The Documentation Plan must state whether each related type is also being retired or should be retained.
+Retirement can be triggered by:
+- **Schema change:** A Documentation Plan or changelog showing `ChangeType: "Deletion"` for entities, complex types, properties, relationships, actions, or functions
+- **Endpoint removal:** The product stops supporting an endpoint — this may not appear in the schema. The author will specify which endpoints are removed and the affected version(s).
+
+The Documentation Plan or author prompt must identify:
+- Which resources (entity types, complex types) are being retired
+- Which version(s): beta, v1.0, or both
+- The alternative API or resource (for redirects)
+- **Dependency analysis for related types:** Complex types referenced as property return types and entity types referenced as relationship targets may still be in use by other APIs. Only delete a related type if it is explicitly called out as retired — otherwise retain it.
 
 ### Retirement workflow
 
@@ -242,11 +247,14 @@ Based on the Documentation Plan, delete:
 3. **Permission include files** for the retired API operation files:
    - `api-reference/{version}/includes/permissions/{operation}-permissions.md` (naming may vary — match the include reference in each API operation file)
 
-4. **Complex type files** explicitly called out as retired/deleted in the Documentation Plan:
+4. **RBAC include files** for the retired API operation files (if they exist and not in use by other APIs):
+   - `api-reference/{version}/includes/rbac-for-apis/{rbac-file}.md` (match the include reference in each API operation file)
+
+5. **Complex type files** explicitly called out as retired/deleted in the Documentation Plan:
    - Only delete if the Documentation Plan explicitly marks the complex type as retired/deleted
    - If not explicitly called out as retired, retain the file
 
-5. **Enum files or sections** explicitly called out as retired/deleted in the Documentation Plan:
+6. **Enum files or sections** explicitly called out as retired/deleted in the Documentation Plan:
    - For standalone enum files: delete if explicitly marked as retired
    - For H3 sections in parent resources: removed when parent resource is deleted
    - For entries in global enums files (`enums.md`, `enums-{subnamespace}.md`): remove the enum section
@@ -277,12 +285,12 @@ Add redirects for **resource files that include Methods tables** (entity types)
     "redirections": [
         {
             "source_path": "api-reference/{version}/resources/{retired-resource}.md",
-            "redirect_url": "/graph/api/resources/{alternative-resource}",
+            "redirect_url": "/graph/api/resources/{alternative-resource}?view=graph-rest-{version}",
             "redirect_document_id": false
         },
         {
             "source_path": "api-reference/{version}/api/{retired-operation}.md",
-            "redirect_url": "/graph/api/{alternative-operation}",
+            "redirect_url": "/graph/api/{alternative-operation}?view=graph-rest-{version}",
             "redirect_document_id": false
         }
     ]
@@ -367,6 +375,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] All resource files explicitly marked as retired/deleted are deleted
 - [ ] All API operation files linked to retired resources are deleted
 - [ ] All permission include files for retired operations are deleted
+- [ ] All RBAC include files for retired operations are deleted (if they existed and not in use by other APIs)
 - [ ] Complex types and enums only deleted if explicitly called out as retired in the Documentation Plan
 - [ ] References to retired resources removed from parent/related resource tables (Methods, Relationships, Properties)
 - [ ] TOC entries removed for deleted files

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

@@ -208,6 +208,18 @@ When reviewing resources that are part of a polymorphic hierarchy (base types wi
 
 Full rules: [common.md — Cross-file consistency validation](./author-api-docs/common.md#cross-file-consistency-validation) (point d) and [public-preview.md — Handling polymorphic entity types](./author-api-docs/public-preview.md#handling-polymorphic-entity-types)
 
+### Retirement (file deletion) review
+
+When a PR deletes API documentation files, validate:
+- **Completeness:** All API operation files, permission includes, and RBAC includes tied to a deleted entity type resource are also deleted
+- **Retained types:** Complex types and entity types referenced by the deleted resource are NOT deleted unless explicitly called out — they may be in use by other APIs
+- **Reference cleanup:** Deleted resources are removed from Methods tables, Relationships tables, and Properties tables in parent/related resource files
+- **Redirects:** Each deleted entity type resource file and API operation file has a redirect entry in the latest `.openpublishing.redirection.yyyy-mm.json` file in `redirects/`
+- **TOC:** Entries for deleted files removed from `toc.mapping.json`
+- **Changelog and What's New:** Entries with Change type "Deletion" are present
+
+Full rules: [deprecate-retire.md — Retirement workflow](./author-api-docs/deprecate-retire.md#retirement-api-removal) and [Retirement quality checklist](./author-api-docs/deprecate-retire.md#quality-checklist)
+
 ---
 
 ## Optional Context-Enhanced Review
@@ -285,6 +297,8 @@ Group files by type:
 
 For each file, apply the appropriate review checklist from above.
 
+**For PRs with 15+ changed files:** Review in batches of 10 files. After each batch, output findings so far before continuing to the next batch. This keeps context focused and prevents quality degradation on later files.
+
 ### Step 4: Run Validation Scripts
 
 Run automated validation scripts to ensure compliance (see [Common Process: Validation](#common-process-validation)):
@@ -306,6 +320,8 @@ Use these criteria consistently when categorizing findings:
 
 ### Step 6: Report Findings
 
+> **IMPORTANT:** Before finalizing the report, re-read each reviewed file to confirm your findings. Do not report issues or approvals from memory alone.
+
 Provide a structured review report:
 
 **Summary:**
@@ -341,6 +357,7 @@ If requested, provide specific edits to fix identified issues.
 
 **Special handling:**
 - Mixed scenarios: If both deprecation and other changes exist, flag this for the reviewer
+- Retirement (file deletions): Validate redirect entries, reference cleanup, and dependency safety — see [Retirement review](#retirement-file-deletion-review)
 - Autogenerated content: If file appears autogenerated (check metadata), validate that manual edits are appropriate
 - Permission files: These are typically autogenerated; validate format but don't require extensive review unless issues are evident
 

.github/workflows/permissions-reference-gen-fic.yml

@@ -27,16 +27,16 @@ jobs:
     - name: Azure Login using Federated Identity
       uses: azure/login@v2
       with:
-        client-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_CLIENT_ID }}
-        tenant-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_TENANT_ID }}
+        client-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_CLIENT_ID }}
+        tenant-id: ${{ secrets.GRAPHPERMISSIONSREFERENCE_TENANT_ID }}
         allow-no-subscriptions: true
 
     - name: Run PowerShell script to update permissions
       shell: pwsh
       run: | 
-        $ClientId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_CLIENT_ID }}"
-        $TenantId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_AZURE_TENANT_ID }}"
-        ./docs/update-permissions-reference-fic.ps1 -ClientId $ClientId -TenantId $TenantId
+        $ClientId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_CLIENT_ID }}"
+        $TenantId = "${{ secrets.GRAPHPERMISSIONSREFERENCE_TENANT_ID }}"
+        ./docs/scripts/update-permissions-reference-fic.ps1 -ClientId $ClientId -TenantId $TenantId
         
     - name: Get token
       id: get_token
@@ -65,7 +65,7 @@ jobs:
     - name: Run PowerShell script to correct errors in permissions descriptions
       shell: pwsh
       run: | 
-        ./docs/correct-permissions-reference-errors.ps1
+        ./docs/scripts/correct-permissions-reference-errors.ps1
     
     - name: Commit errors correction and open a pull request
       working-directory: ./docs
@@ -87,4 +87,4 @@ jobs:
           git push --set-upstream origin $branchName -f
           
           gh pr create --base main --title $prTitle --body "Scheduled permissions reference update using Federated Identity Credentials" --reviewer "FaithOmbongi,msewaweru" --label "ready for content review"
-        }
+        }

.github/workflows/request-ref-toc-gen.yml

@@ -64,4 +64,4 @@ jobs:
         INPUT_OWNER: ${{ github.repository_owner }}
         INPUT_REPO: ${{ github.event.repository.name }}
         INPUT_PULL: ${{ github.event.issue.number }}
-        INPUT_BODY: ${{ needs.request-toc-gen.outputs.result }}
+        INPUT_BODY: ${{ needs.request-toc-gen.outputs.result || 'TOC generation did not produce a result. Please check the workflow logs.' }}

api-reference/beta/api/accesspackageassignmentrequest-resume.md

@@ -321,7 +321,6 @@ Content-Type: application/json
 
 ---
 
-
 ### Response
 
 The following example shows the response.

api-reference/beta/api/accesspackagesuggestions-filterbycurrentuser.md

@@ -81,7 +81,6 @@ GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/ac
 
 ---
 
-
 #### Response
 
 The following example shows the response.
@@ -160,7 +159,6 @@ GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/ac
 
 ---
 
-
 #### Response
 
 The following example shows the response.

api-reference/beta/api/agentcardmanifest-get.md

@@ -96,7 +96,6 @@ GET https://graph.microsoft.com/beta/agentRegistry/agentCardManifests/{agentCard
 
 ---
 
-
 ### Response
 
 The following example shows the response.