Merge branch 'main' into diadabal-ops-ga

Author: diadabal

.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`)
@@ -700,6 +692,7 @@ 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 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
 

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

@@ -206,6 +206,106 @@ When combining deprecation with new APIs/promotions:
 
 ---
 
+## Retirement (API removal)
+
+Retirement is the final stage of the API lifecycle — the deprecated API has reached its sunset date and is removed from the service. Documentation files for retired APIs must be **deleted** from the repository, with redirects added to guide users to alternatives.
+
+**Retirement vs. deprecation:** Deprecation marks an API as "going away in the future" — it adds notices with sunset dates and alternatives. Retirement removes the API entirely — files are deleted, not just annotated.
+
+### 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 workflow
+
+#### Step 1: Delete retired files
+
+Based on the Documentation Plan, delete:
+
+1. **Resource files** for entity types and complex types explicitly marked as retired/deleted:
+   - `api-reference/{version}/resources/{namespace}-{resourcename}.md`
+
+2. **API operation files** linked to the retired resource:
+   - List files (GET collection): `{resource}-list-{entityType}.md`
+   - Get files (GET single): `{entityType}-get.md`
+   - Create files (POST): `{resource}-post-{entityType}.md`
+   - PUT files: `{resource}-put-{entityType}.md`
+   - Update files (PATCH): `{entityType}-update.md`
+   - Upsert files (PATCH): `{entityType}-upsert.md`
+   - Delete files (DELETE): `{entityType}-delete.md`
+   - Action files: `{entityType}-{actionName}.md`
+   - Function files: `{entityType}-{functionName}.md`
+
+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:
+   - 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:
+   - 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
+   - If not explicitly called out as retired, retain the file
+
+#### Step 2: Clean up references
+
+1. **Parent resource references:**
+   - Remove the retired resource from Methods tables, Relationships tables, and Properties tables of any parent or related resources that reference it
+
+2. **TOC updates:**
+   - Remove entries for deleted files from `toc.mapping.json`
+   - Remove entries from concept `toc.yml` if applicable
+
+3. **Concept topics:**
+   - Remove or update references to the retired API in overview and concept documentation
+   - If a concept topic is entirely about the retired feature, delete it
+
+#### Step 3: Add redirects
+
+Add redirects for **resource files that include Methods tables** (entity types) and **API operation files**. Complex types, enums, and permission include files do not need redirects.
+
+**Redirect file location:** The repo uses multiple redirect files in the `redirects/` folder at the root, following the pattern `.openpublishing.redirection.yyyy-mm.json`. Use the **latest** redirection file.
+
+**Redirect file format:**
+```json
+{
+    "redirections": [
+        {
+            "source_path": "api-reference/{version}/resources/{retired-resource}.md",
+            "redirect_url": "/graph/api/resources/{alternative-resource}",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "api-reference/{version}/api/{retired-operation}.md",
+            "redirect_url": "/graph/api/{alternative-operation}",
+            "redirect_document_id": false
+        }
+    ]
+}
+```
+
+**Field definitions:**
+- `source_path` — file path to the deleted file in the repo (relative to repo root)
+- `redirect_url` — relative URL to the alternative article on learn.microsoft.com (not a file path)
+- `redirect_document_id` — always `false`
+
+**Steps:**
+1. Identify the latest `.openpublishing.redirection.yyyy-mm.json` file in the `redirects/` folder
+2. Add redirect entries for each deleted resource file (entity types with Methods tables) and each deleted API operation file
+3. Set `redirect_url` to the alternative resource or operation specified in the Documentation Plan or the deprecation notice
+
+#### Step 4: Add changelog and What's New
+
+1. **Changelog:** Add entries with Change type "Deletion". See [Updating the Changelog](common.md#updating-the-changelog).
+2. **What's New:** Note the API retirement, link to the alternative API, and reference the original deprecation blog post. See [Updating What's New](common.md#updating-whats-new).
+
+---
+
 ## Version-specific notes
 
 - **Beta:** Banner after namespace, before beta disclaimer; keep beta disclaimer; use `?view=graph-rest-beta&preserve-view=true`
@@ -261,3 +361,16 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 
 **Final — Scenario 3 specific:**
 - [ ] All deprecation items from Documentation Plan addressed
+- [ ] All retirement items from Documentation Plan addressed
+
+**Retirement-specific (if applicable):**
+- [ ] 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
+- [ ] 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
+- [ ] Concept topics updated or deleted as appropriate
+- [ ] Redirects added in latest `.openpublishing.redirection.yyyy-mm.json` for deleted resource files (with Methods tables) and API operation files
+- [ ] Changelog entries added with Change type "Deletion"
+- [ ] What's New updated with retirement notice and link to alternative