Merge main into live

.github/agents/docseditor.agent.md

@@ -3,20 +3,32 @@ name: DocsEditor
 description: Edit and transform a document using the Microsoft Style Guide
 ---
 
-# Article Editing Instructions for LLMs
+# Article Writing and Editing Instructions for LLMs
 
-You are performing an edit pass on a Microsoft documentation article. Your MANDATORY goal is to aggressively transform the content to follow the Microsoft Style Guide while preserving technical accuracy and meaning.
+**Mode: EDITING** — Transform the existing article to follow the Microsoft Style Guide. Preserve all technical accuracy and meaning.
+**Mode: WRITING** — Create new content that follows the Microsoft Style Guide from the start. Ensure technical accuracy, clarity, and consistency.
+
+Determine which mode applies, then execute all mandatory transformations defined in this document.
 
 ❌ Don't provide explanations or commentary on your process unless asked; ✅ only summarize changes at the end.
 
 ## EDITING APPROACH - FOLLOW THIS METHODOLOGY
 
 1. **Read the entire document first**
-2. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
-3. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
-4. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
-5. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
-6. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+2. **Verify document structure** - Check that the article has a logical heading hierarchy, an introduction, and appropriate sections (such as prerequisites, steps, and next steps). Flag any missing structural elements.
+3. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
+4. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
+5. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
+6. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
+7. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+
+## WRITING APPROACH - FOLLOW THIS METHODOLOGY
+
+1. **Understand the requirements** - Clarify the topic, audience, and purpose
+2. **Ask for structure** - Before writing, ask the user for a template or an existing article to follow for structure
+3. **Write with style guidelines in mind** - Apply voice, tense, and formatting rules from the start
+4. **Ensure completeness** - Include all necessary sections and technical details
+5. **Validate accuracy** - Verify technical correctness and consistency
 
 ## PATTERN EXAMPLES FOR RECOGNITION
 
@@ -219,19 +231,19 @@ When editing, focus on these areas in order of priority:
 - ALWAYS use no spaces around dashes: "Use pipelines—logical groups—to consolidate"
 - ALWAYS add blank lines around markdown elements (don't add extra if they exist)
 
-## FINAL VALIDATION - MANDATORY CHECKS
-
-After editing, you MUST verify:
-- [ ] ALL passive voice converted to active voice
-- [ ] ALL "you can/should" converted to imperative mood
-- [ ] ALL future tense converted to present tense for descriptions
-- [ ] ALL contractions added where appropriate
-- [ ] ALL verbose phrases simplified
-- [ ] ALL weak constructions eliminated
-- [ ] ALL ambiguous "this" pronoun uses replaced with explicit nouns
-- [ ] Content maintains technical accuracy
-- [ ] Tone is conversational and helpful
-- [ ] Sentences are concise and scannable
-- [ ] Formatting follows conventions
-- [ ] No consecutive headings without content
-- [ ] Code blocks are unchanged (except comments if needed)
+## API REFERENCES
+
+Use cross-references instead of plain text or raw URLs when referring to .NET APIs:
+
+- Format: `<xref:api-doc-ID>`
+- Find API doc IDs in XML files at https://github.com/dotnet/dotnet-api-docs
+  - For types: use the `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit the first 2 characters)
+  - For members: use the `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit the first 2 characters)
+- If unsure of the doc ID, use the API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and use the `url` value from the results as a manual link.
+
+### Encoding
+
+Use the following rules to encode special characters in API doc IDs:
+
+1. Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`.
+2. **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively.

.github/copilot-instructions.md

@@ -36,7 +36,9 @@ To find API doc IDs:
 
 If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and then use the `url` value from the results as a manual link.
 
-**Encoding**:
+### Encoding
+
+Use the following rules to encode special characters in API doc IDs:
 
 1. Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`.
 2. **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively.
@@ -51,6 +53,11 @@ For snippets >6 lines:
 1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders.
 1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article.
 1. IMPORTANT: For created code, always try to encapsulate it in an standalone executable (e.g. `dotnet fsi myFile.fsx` or `dotnet run myFile.cs`, add the necessary boilerplate/imports/usings where needed, and execute it.). Run it, and for every code snippet, include a PR commentary checking each code sample and proving what it has produced - this can be diagnostics, standard output, or a result value. That standalone file is just for the purpose of verification within copilot's execution environment, the published docs snippet should remain a subset as you would normally write to maximize clarity.
+1. IMPORTANT: Code snippets are referenced in the in markdown following this format: `:::code language="{code-language}" source="{relative-file-path}" id="{snippet-identifier}":::`. For example:
+   ```markdown
+   :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick":::
+   :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick":::
+   ```
 
 ## File Naming
 

.github/prompts/Editing.FullPass.prompt.md

@@ -1,9 +1,26 @@
 ---
-model: Claude Sonnet 4 (copilot)
+model: Claude Sonnet 4.6 (copilot)
 agent: DocsEditor
 description: "Performs comprehensive editing pass following Microsoft Style Guide"
 ---
 
 # Article Editing Instructions
 
 Examine and edit the entire article, including front matter, for clarity, conciseness, grammar, spelling, and adherence to Microsoft Style Guide standards.
+
+## EDITING - FINAL VALIDATION - MANDATORY CHECKS
+
+After editing, you MUST verify:
+- [ ] ALL passive voice converted to active voice
+- [ ] ALL "you can/should" converted to imperative mood
+- [ ] ALL future tense converted to present tense for descriptions
+- [ ] ALL contractions added where appropriate
+- [ ] ALL verbose phrases simplified
+- [ ] ALL weak constructions eliminated
+- [ ] ALL ambiguous "this" pronoun uses replaced with explicit nouns
+- [ ] Content maintains technical accuracy
+- [ ] Tone is conversational and helpful
+- [ ] Sentences are concise and scannable
+- [ ] Formatting follows conventions
+- [ ] No consecutive headings without content
+- [ ] Code blocks are unchanged (except comments if needed)

.github/prompts/Merge.Article.prompt.md

@@ -0,0 +1,16 @@
+---
+name: Merge an article
+agent: agent
+description: "Copy the content from one article into another."
+---
+
+Migrate the content in one article to another.
+
+Pay attention to the following pieces of information when merging the articles:
+
+- Copy all sections and their content from the source article to the destination article.
+- If there are sections in the source article that already exist in the destination article, merge the content of those sections appropriately without duplicating information.
+- Update any internal links within the merged content to ensure they point to the correct sections in the destination article.
+- Ensure that any code snippets, images, or media in the source article are also transferred to the destination article.
+
+When the migration is done, ask the user if they want to also redirect and delete the source article. If they do, invoke the `redirect-article` skill.

.github/prompts/Snippets.Migrate.prompt.md

@@ -48,7 +48,7 @@ We no longer use the `~/samples/snippets/` location for code snippets. All code
 **Requirements for current code standards:**
 - ✅ MUST be complete and compilable
 - ✅ MUST include a project file
-- ✅ MUST target the latest .NET version
+- ✅ MUST target the latest .NET or .NET Framework version as appropriate based on article context
 - ✅ MUST provide BOTH C# and Visual Basic versions
 - ✅ MUST use appropriate syntax for the target framework
 - ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format
@@ -75,6 +75,9 @@ We no longer use the `~/samples/snippets/` location for code snippets. All code
 - **Reuse**: If the article already has snippets in the new location, reuse the existing folder structure and try to merge the code into the existing snippets if possible. Use new classes and code files as needed. Code **ONLY** needs to compile, it doesn't have to run from the program main.
 - **Create**: If no existing folder structure exists for the article, create a new one following the pattern above.
 - **New projects**: **NEVER** create project files manually. Always use the `dotnet` CLI to ensure correct formatting and structure of new code. Projects should be console apps unless otherwise required (such as a Windows Forms-related snippet)
+  - Specify a meaningful project name with the `-n` parameter.
+    - Example 1: An article about clipboard handling, use `dotnet new console -n ClipboardExample`
+    - Example 2: An article about events would be `dotnet new console -n EventsOverview`
 
 ### 3. Migrate and update code
 - **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location

.github/prompts/Snippets.Push.prompt.md

@@ -88,7 +88,6 @@ description: Push inline code block snippets out of articles into standalone fil
 - DO NOT use language tabs in the article — place references side-by-side, like so:
   ```markdown
   :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick":::
-
   :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick":::
   ```
 - Verify all paths and identifiers are correct.

.github/prompts/Snippets.Upgrade.prompt.md

@@ -58,7 +58,10 @@ All snippets must follow this folder structure relative to the referencing artic
   - Modern `using` statements
 
 ### 4. Project File Requirements
-- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type. Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible.
+- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type. Don't specify an output folder with `-o`.
+- Specify a meaningful project name with the `-n` parameter.
+  - Example 1: An article about clipboard handling, use `dotnet new console -n ClipboardExample`
+  - Example 2: For an article about events, use `dotnet new console -n EventsOverview`
 - Ensure a complete, compilable project structure with an appropriate `.csproj` or `.vbproj` file
 - Code only needs to compile — it doesn't have to run from `Main`
 - Verify compilation with `dotnet build`
@@ -97,7 +100,6 @@ All snippets must follow this folder structure relative to the referencing artic
 
 ## Common mistakes to avoid
 
-- ❌ Using the old `[net|framework]` subfolder in paths
 - ❌ Creating project files manually instead of using `dotnet new`
 - ❌ Missing C# or VB versions for standard articles
 - ❌ Using simplistic or non-descriptive snippet identifiers

.github/skills/redirect-article/SKILL.md

@@ -33,7 +33,9 @@ Delete a markdown article from the repository and create a redirect entry that p
 
 ### 2. Update the internal links
 
-1. Search for `**/*.md` and `**/*.yml` files that reference the redirected file
+1. Build a list of files that reference the deleted article
+   - Search for `**/*.md` files that reference the redirected file
+   - Search for `**/*.yml` files that reference the redirected file
 2. Update the links to point to the new article
 
 ## Redirection File Selection