Merge branch 'main' into planner/pavlodatsiuk/taskchat-api

Author: Pavlo Datsiuk

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

@@ -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
@@ -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
 

.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