Merge branch 'main' into user/jsinghmokha/add-section-management-apis-beta

Author: MSFT-Andrea

.gdn/.gdnbaselines

@@ -39,18 +39,6 @@
       "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

@@ -39,18 +39,6 @@
       "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

@@ -1,7 +1,7 @@
 ---
 agent: agent
 model: Claude Sonnet 4.5 (copilot)
-tools: ['usages', 'problems', 'fetch', 'githubRepo', 'runCommands', 'edit/createFile', 'edit/editFiles', 'search']
+tools: ['usages', 'problems', 'fetch', 'githubRepo', 'runCommands', 'edit/createFile', 'edit/editFiles', 'search', 'github/*']
 description: Author and update Microsoft Graph API reference documentation using autogenerated doc stubs
 name: authorAPIdocs
 ---

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

@@ -31,7 +31,7 @@ If a conflict is significant, flag it to the author in the final summary but fol
 Gather both values in a **single upfront step** to minimize round-trips with the author:
 
 1. **Attempt auto-detection first:**
-   - `author`: Use the GitHub login of the signed-in user
+   - `author`: Use the `get_me` tool to get the GitHub Login of the signed-in user
    - `ms.subservice`: Inspect existing API/resource files being updated and use their `ms.subservice` value (exclude enum files)
 
 2. **If either value cannot be inferred**, ask the author for both at once:
@@ -45,17 +45,7 @@ Gather both values in a **single upfront step** to minimize round-trips with the
 
 ### temp-docstubs Folder
 
-Before beginning any documentation process, instruct the author to add all required files to the `temp-docstubs` folder in this workspace:
-
-**For Scenario 1 (Fresh APIs / beta changes):**
-- Autogenerated doc stubs (*.md files)
-- API.md file describing the capabilities being added/changed
-- Autogenerated changelog file (changelog_*.json)
-
-**For Scenario 2 (Promotion from beta to v1.0):**
-- Documentation Plan documenting what is being promoted
-- **Optional:** Autogenerated doc stubs (*.md files for v1.0)
-- Autogenerated changelog file (changelog_*.json)
+Before beginning any documentation process, instruct the author to add all required files to the `temp-docstubs` folder in this workspace. The specific files needed depend on the scenario — see the **Inputs** section of the relevant scenario file for details.
 
 **Important notes about temp-docstubs:**
 - This folder is temporary storage for input files needed during authoring
@@ -86,7 +76,7 @@ After authoring documentation, update the appropriate changelog file in the `cha
           // Records will go here
         ],
         "Id": "{unique-guid}",
-        "Cloud": "prd",
+        "Cloud": "Prod",
         "Version": "beta",
         "CreatedDateTime": "{YYYY-MM-DDTHH:mm:ss.fffffffZ}",
         "WorkloadArea": "{WorkloadArea}",
@@ -100,7 +90,7 @@ After authoring documentation, update the appropriate changelog file in the `cha
 - **IMPORTANT:** A changelog record is NOT just the ChangeList array. A complete changelog record consists of:
   - `ChangeList` array (containing individual change items)
   - `Id` (unique GUID for this set of changes)
-  - `Cloud` (always "prd")
+  - `Cloud` (use "Prod" for new entries; older changelogs may have "prd")
   - `Version` (e.g., "beta" or "v1.0")
   - `CreatedDateTime` (ISO 8601/RFC 3339 DateTime with fractional seconds and Z suffix)
   - `WorkloadArea` (e.g., "Security")
@@ -132,7 +122,7 @@ After authoring documentation, update the appropriate changelog file in the `cha
       }
     ],
     "Id": "1e2218aa-5dbc-4c74-a0fe-1d06e90b451c",
-    "Cloud": "prd",
+    "Cloud": "Prod",
     "Version": "beta",
     "CreatedDateTime": "2025-11-17T17:38:10.4694969Z",
     "WorkloadArea": "Security",
@@ -179,7 +169,7 @@ Collect the following details for each API change (refer to **templates/changelo
 
 **Required record-level properties:** Version, WorkloadArea, SubArea
 
-**Note:** Cloud is always "prd" - no need to ask the author.
+**Note:** Cloud is "Prod" for new entries - no need to ask the author. Older changelogs may use "prd", which is also valid.
 
 **Step 3: Generate GUID and timestamp**
 
@@ -259,7 +249,7 @@ After updating What's new, update the appropriate TOC mapping file to make new d
 
 **For new files:** Include only HTTP request examples using `msgraph-interactive` (for URLs without an ID placeholder, e.g., `https://graph.microsoft.com/v1.0/users`) or `http` language identifier. No tabs or SDK includes.
 
-**For existing files:** Follow the established pattern. If the file has no SDK snippets, add only HTTP examples. Do not introduce SDK snippets to files lacking them.
+**For existing files:** Follow the established pattern. If the file has no SDK snippets, add only HTTP examples. Do not introduce SDK snippets to files or examples lacking them.
 
 **Example HTTP-only format:**
 
@@ -399,11 +389,12 @@ Fully qualify any type (including enum types) that is defined in a subnamespace
 - Remove beta disclaimer when promoting to v1.0
 
 **National cloud include statement:**
-- API method files in beta include an autogenerated national cloud support statement immediately before the `## Permissions` header. Example include statement for all clouds support:
+- API method files in beta include an autogenerated national cloud support statement immediately before the `## Permissions` header. Example:
   ```
   [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
   ```
-- Remove this include statement when promoting to v1.0
+- **Do not add** this statement when authoring new API method files — it is added automatically by a downstream process
+- **Delete** this statement from files copied from beta when promoting to v1.0
 
 ## Documentation Standards
 
@@ -416,6 +407,7 @@ Fully qualify any type (including enum types) that is defined in a subnamespace
 **Permissions:**
 - Must start with the standard boilerplate text
 - Must include link to a permissions table
+- **(Optional) RBAC include:** If the documentation plan or author specifies required Entra admin roles, add an RBAC include statement immediately after the permissions table include. See [RBAC for APIs include file templates](../../../templates/rbac-for-apis-include.md) for file conventions, naming, and content templates.
 
 **HTTP request:**
 - Use relative URLs (e.g., `/users` not `https://graph.microsoft.com/beta/users`)
@@ -611,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:
@@ -633,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
 
@@ -700,15 +706,18 @@ After processing all files in a documentation session, verify cross-file consist
 2. **API file ↔ resource link:** Every API file's description should link back to its parent resource, and that resource file should exist
 3. **Enum references ↔ definitions:** Every enum type referenced in Properties tables should be defined in the appropriate enums file, parent resource, or separate topic
 4. **Permissions files:** Every permissions include reference in API files should have a corresponding file in the `includes/permissions/` folder
+5. **RBAC files:** If any API file has an RBAC include reference, verify the corresponding file exists in `includes/rbac-for-apis/`
 5. **JSON representation ↔ Properties table:** Properties listed in the JSON representation section should match the Properties table
-6. **Polymorphic collections:** If a Documentation Plan flagged polymorphic types, verify: (a) no operation files were created using derived type names, (b) all shared operation files use the base type name, (c) base type resource page has the Methods table (including base-type-only operations for concrete bases), (d) derived type resource pages reference the base type for operations, (e) `@odata.type` guidance is included in POST/PATCH request body sections
+6. **Polymorphic collections:** If a Documentation Plan flagged polymorphic types, verify: (a) no operation files were created using derived type names, (b) all shared operation files use the base type name, (c) base type resource page has the Methods table (including base-type-only operations for concrete bases), (d) derived type resource pages have a `## Methods` section with only a polymorphic note (no Methods table — the table lives only on the base type page), (e) `@odata.type` guidance is included in POST/PATCH request body sections
 
 Report any inconsistencies in the final summary to the author.
 
 ## Base Quality Checklist
 
 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