Merge branch 'main' into yizcheng/nonazregion

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

@@ -76,15 +76,15 @@ If the author has already described the deprecation in sufficient detail (e.g.,
 | Instead of... | Use... |
 |---------------|--------|
 | Documentation Plan | The author's prompt — extract what is being deprecated, the alternative/workaround, milestone date, and blog post link |
-| Autogenerated changelog | Ask the author if a changelog and What's New update are needed. If yes, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for deprecations and retirements. If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided):
 - What specifically is being deprecated (resource, method, property, enum, etc.)
 - The alternative API or workaround
 - The milestone/sunset date
 - Blog post URL (if available)
 - Which version(s): beta, v1.0, or both
-- WorkloadArea and SubArea for the changelog (if one is needed)
+- WorkloadArea and SubArea for the changelog (if not inferrable)
 
 ## Key principles
 
@@ -190,10 +190,22 @@ See [Deprecating enumerations](.github/prompts/author-api-docs/enumerations.md#d
 
 ## Supporting updates
 
-**Changelog:** Change type: "Deprecation". Include API set/entities, link to topics and blog post. See [Updating the Changelog](common.md#updating-the-changelog).
+Changelog and What's New updates are always required for deprecations and retirements. This applies to all deprecated or retired schema artifacts — resources, properties, relationships, enums, methods.
+
+**Changelog:** Change type: "Deprecation" or "Deletion". Include API set/entities, link to topics and blog post. See [Updating the Changelog](common.md#updating-the-changelog).
 
 **What's New:** Describe deprecation, link to deprecated API and alternative, link to blog post. See [Updating What's New](common.md#updating-whats-new).
 
+**What's New description patterns for deprecations and retirements:**
+
+- **Deprecated resource:** `Deprecated the [resourceName](/graph/api/resources/{filename}?view=graph-rest-{version}&preserve-view=true) resource type. Use [alternativeName](/graph/api/resources/{alt-filename}?view=graph-rest-{version}&preserve-view=true) instead.`
+- **Deprecated property:** `Deprecated the **propertyName** property on the [resourceName](/graph/api/resources/{filename}?view=graph-rest-{version}&preserve-view=true) resource type. Use the **alternativeProperty** property instead.`
+- **Deprecated method:** `Deprecated the [methodName](/graph/api/{filename}?view=graph-rest-{version}&preserve-view=true) method. Use [alternativeMethod](/graph/api/{alt-filename}?view=graph-rest-{version}&preserve-view=true) instead.`
+- **Deprecated enum/member:** `Deprecated the `memberName` member in the **enumName** enumeration type.`
+- **Retired resource:** `Removed the **resourceName** resource type and associated methods.`
+
+For v1.0-only links, omit the `?view=graph-rest-beta&preserve-view=true` query string.
+
 ---
 
 ## Mixed scenarios
@@ -214,10 +226,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 +259,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 +297,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
         }
     ]
@@ -348,6 +368,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 **Supporting updates:**
 - [ ] Changelog: Change type "Deprecation", links to topics/blog
 - [ ] What's New: describes deprecation, links to API/alternative/blog
+- [ ] What's New includes entries for all deprecated schema artifacts (resources, properties, enums, methods)
 
 **Mixed scenarios:**
 - [ ] Non-deprecation tasks processed first
@@ -367,6 +388,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/author-api-docs/ga.md

@@ -70,13 +70,13 @@ If the author has already described the promotion in sufficient detail (e.g., na
 | Documentation Plan | The author's prompt — extract which resources, methods, or properties are being promoted |
 | API.md | The author's pasted content (XML, CSDL, JSON) + existing documentation in the repo |
 | Doc stubs | Existing files in the repo — search for them by resource name, namespace, or file path |
-| Autogenerated changelog | Ask the author if they can provide an autogenerated changelog in `temp-docstubs`. If not, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for promotions to v1.0. If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided or inferrable):
 - Which specific resources/methods/properties are being promoted
 - Whether this is a full or partial promotion
 - Whether there are deviations from beta (renames, type changes, structural differences)
-- WorkloadArea and SubArea for the changelog (if one is needed)
+- WorkloadArea and SubArea for the changelog (if not inferrable)
 
 **Do not block** on missing formal inputs when the author's prompt provides enough context to proceed.
 
@@ -189,6 +189,8 @@ Remove "(preview)" from TOC entries as applicable:
 
 ### Step 5: Update changelog and What's new
 
+Changelog and What's New updates are always required for promotions. This applies to all promoted schema artifacts — resources, properties, relationships, enums, methods.
+
 1. **Add changelog entries:**
    - Use the autogenerated changelog doc stub (JSON file) provided by the author
    - Add entries for all APIs and resources being promoted to v1.0
@@ -198,6 +200,16 @@ Remove "(preview)" from TOC entries as applicable:
    - Add entries to the [What's new](https://learn.microsoft.com/en-us/graph/whats-new-overview) topic for the promoted APIs
    - Highlight that these APIs are now generally available (GA) in v1.0
 
+**What's New description patterns for GA promotions:**
+
+- **Promoted resource:** `Added the [resourceName](/graph/api/resources/{filename}) resource type to the v1.0 endpoint.`
+- **Promoted property:** `Added the **propertyName** property to the [resourceName](/graph/api/resources/{filename}) resource type in v1.0.`
+- **Promoted enum:** `Added the **enumName** enumeration type to the v1.0 endpoint.`
+- **Promoted method:** `Added the [methodName](/graph/api/{filename}) method to the [resourceName](/graph/api/resources/{filename}) resource type in v1.0.`
+- **Promoted enum member:** Added the `memberName` member to the **enumName** enumeration type in v1.0.
+
+Note: For v1.0 links, do NOT append `?view=graph-rest-beta&preserve-view=true` query strings.
+
 ## Partial promotions
 
 When only some properties, methods, or relationships of a resource are being promoted (the v1.0 resource already exists):
@@ -319,6 +331,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 **For changelog and What's new:**
 - [ ] Changelog entries added using autogenerated JSON stub
 - [ ] What's new topic updated with GA announcement
+- [ ] What's New includes entries for all promoted schema artifacts (resources, properties, enums, methods)
 
 **Final verification — Scenario 2 specific:**
 - [ ] All resource files promoted and updated

.github/prompts/author-api-docs/public-preview.md

@@ -67,7 +67,7 @@ If the author has already described the change in sufficient detail (e.g., paste
 | Documentation Plan | The author's prompt — extract scope, files, resources, and changes directly from their message |
 | API.md | The author's pasted content (XML, CSDL, JSON) + existing documentation in the repo |
 | Doc stubs | Existing files in the repo — search for them by resource name, namespace, or file path |
-| Autogenerated changelog | Ask the author if a changelog and What's New update are needed. If yes, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for schema changes (new resources, properties, enums, methods, deprecations). If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided or inferrable):
 - Which version: beta, v1.0, or both
@@ -497,6 +497,30 @@ For all API changes, include the following updates as applicable:
 
 See the shared processes in [`common.md`](.github/prompts/author-api-docs/common.md) for complete instructions on each of these processes.
 
+### When changelog and What's New are required
+
+Changelog and What's New updates are required whenever a doc stub changelog file is provided or the Documentation Plan includes schema changes. This includes — but is not limited to:
+
+| Change type | Changelog required | What's New required |
+|-------------|-------------------|---------------------|
+| New resource type (EntityType, ComplexType) | ✅ Yes | ✅ Yes |
+| New API method (action, function) | ✅ Yes | ✅ Yes |
+| New property on existing resource | ✅ Yes | ✅ Yes |
+| New relationship on existing resource | ✅ Yes | ✅ Yes |
+| New enumeration type | ✅ Yes | ✅ Yes |
+| New enum member on existing enum | ✅ Yes | ✅ Yes |
+| Deprecation or removal | ✅ Yes | ✅ Yes |
+
+**What's New description patterns for common changes:**
+
+- **New resource:** `Added the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New property:** `Added the **propertyName** property to the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New enum:** `Added the **enumName** enumeration type.`
+- **New method:** `Added the [methodName](/graph/api/{filename}?view=graph-rest-beta&preserve-view=true) method to the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New enum member:** `Added the `memberName` member to the **enumName** enumeration type.`
+
+For v1.0, omit the `?view=graph-rest-beta&preserve-view=true` query string from links.
+
 After gathering all inputs, analyze the Documentation Plan to understand the full scope of work.
 
 ## Quality checklist
@@ -594,6 +618,8 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] All TOC changes made if applicable
 - [ ] All properties referencing updated enumerations have been updated
 - [ ] All permissions files copied
+- [ ] Changelog entry added for all schema changes (new resources, properties, enums, methods, deprecations)
+- [ ] What's New entry added for all schema changes (matches changelog scope)
 
 **For polymorphic collections (if applicable):**
 - [ ] Polymorphism detected from Documentation Plan notes