@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/dotnet-aot-compat/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: dotnet-aot-compat
+description: 'Makes .NET projects compatible with Native AOT and trimming by resolving IL trim and AOT analyzer warnings. Use when making a project AOT-compatible, fixing trimming warnings, resolving IL2026, IL2067, IL2070, IL2072, or IL3050, adding DynamicallyAccessedMembers annotations, or enabling IsAotCompatible. Not for publishing native AOT binaries, optimizing binary size, replacing reflection-heavy libraries, or .NET Framework projects.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-upgrade/skills/dotnet-aot-compat/SKILL.md; see NOTICE) -->
+
+# dotnet-aot-compat
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. Arc host trimming/NativeAOT setup belongs to **cratis-arc-hosting**.
+
+Make .NET projects compatible with Native AOT and trimming by systematically resolving all IL trim/AOT analyzer warnings.
+
+## When to Use This Skill
+
+- **"Make this project AOT-compatible"**
+- **"Fix trimming warnings"** or **"fix IL warnings"**
+- **"Resolve IL2070 / IL2067 / IL2072 / IL2026 / IL3050 warnings"**
+- **"Add DynamicallyAccessedMembers annotations"**
+- **"Enable IsAotCompatible in my .csproj"**
+- **"My project has trim analyzer warnings after upgrading to net8.0"**
+- **"Annotate reflection code for the trimmer"**
+
+## When Not to Use This Skill
+
+Do not use this skill when the project exclusively targets .NET Framework (net4x), which does not support the trim/AOT analyzers.
+
+## Prerequisites
+
+An existing .NET project targeting net8.0 or later (or multi-targeting with at least one net8.0+ TFM) and the corresponding .NET SDK installed.
+
+## Background: What AOT Compatibility Means
+
+Native AOT and the IL trimmer perform static analysis to determine what code is reachable. Reflection can break this analysis because the trimmer can't see what types/members are accessed at runtime. The `IsAotCompatible` property enables analyzers that flag these issues as build warnings (ILXXXX codes).
+
+## Critical Rules
+
+### ❌ Never suppress warnings incorrectly
+
+- **NEVER** use `#pragma warning disable` for IL warnings. It hides warnings from the Roslyn analyzer at build time, but the IL linker and AOT compiler still see the issue. The code will fail at trim/publish time.
+- **NEVER** use `[UnconditionalSuppressMessage]`. It tells both the analyzer AND the linker to ignore the warning, meaning the trimmer cannot verify safety. Raising an error at build time is always preferable to hiding the issue and having it silently break at runtime.
+
+### 💡 Preferred approaches
+
+- **Prefer** `[DynamicallyAccessedMembers]` annotations to flow type information through the call chain.
+- **Prefer** refactoring to eliminate patterns that break annotation flow (e.g., boxing `Type` through `object[]`).
+- **Use** `[RequiresUnreferencedCode]` / `[RequiresDynamicCode]` / `[RequiresAssemblyFiles]` to mark methods as fundamentally incompatible with trimming, propagating the requirement to callers. This surfaces the issue clearly rather than hiding it — callers must explicitly acknowledge the incompatibility.
+
+### Annotation flow is key
+
+The trimmer tracks `[DynamicallyAccessedMembers]` annotations through assignments, parameter passing, and return values. If this flow is broken (e.g., by boxing a `Type` into `object`, storing in an untyped collection, or casting through interfaces), the trimmer loses track and warns. The fix is to preserve the flow, not suppress the warning.
+
+## Step-by-Step Procedure
+
+> **Do not explore the codebase up-front.** The build warnings tell you exactly which files and lines need changes. Follow a tight loop: **build → pick a warning → open that file at that line → apply the fix recipe → rebuild**. Reading or analyzing source files beyond what a specific warning points you to is wasted effort and leads to timeouts. Let the compiler guide you.
+>
+> ❌ Do NOT run `find`, `ls`, or `grep` to understand the project structure before building. Do NOT read README, docs, or architecture files. Your first action should be Step 1 (enable AOT analysis), then build.
+
+### Step 1: Enable AOT analysis in the .csproj
+
+Add `IsAotCompatible`. If the project doesn't exclusively target net8.0+, add a TFM condition (AOT analysis requires net8.0+):
+
+```xml
+<PropertyGroup>
+  <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible>
+</PropertyGroup>
+```
+
+This automatically sets `EnableTrimAnalyzer=true` and `EnableAotAnalyzer=true` for compatible TFMs. For multi-targeting projects (e.g., `netstandard2.0;net8.0`), the condition ensures no `NETSDK1210` warnings on older TFMs.
+
+### Step 2: Build and collect warnings
+
+```bash
+dotnet build <project.csproj> -f <net8.0-or-later-tfm> --no-incremental 2>&1 | grep 'IL[0-9]\{4\}'
+```
+
+Sort and deduplicate. Common warning codes:
+- **IL2070**: Reflection call on a `Type` parameter missing `[DynamicallyAccessedMembers]`
+- **IL2067**: Passing an unannotated `Type` to a method expecting `[DynamicallyAccessedMembers]`
+- **IL2072**: Return value or extracted value missing annotation (often from unboxing)
+- **IL2057**: `Type.GetType(string)` with a non-constant argument
+- **IL2026**: Calling a method marked `[RequiresUnreferencedCode]`
+- **IL2050**: P/invoke method with COM marshalling parameters
+- **IL2075**: Return value flows into reflection without annotation
+- **IL2091**: Generic argument missing `[DynamicallyAccessedMembers]` required by constraint
+- **IL3000**: `Assembly.Location` returns empty string in single-file/AOT apps
+- **IL3050**: Calling a method marked `[RequiresDynamicCode]`
+
+### Step 3: Triage warnings by code (do NOT read every file)
+
+Group the warnings from Step 2 by warning code and count them. **Do not open individual files yet.** Identify the top 1-2 patterns by count — these drive your fix strategy:
+
+| Pattern | Typical fix |
+|---------|-------------|
+| Many IL2026 + IL3050 from `JsonSerializer` | **Go to Strategy C immediately** — create a `JsonSerializerContext`, then batch-update all call sites |
+| IL2070/IL2087 on `Type` parameters | Add `[DynamicallyAccessedMembers]` to the innermost method, then cascade outward |
+| IL2067 passing unannotated `Type` | Annotate the parameter at the source |
+
+**In most real projects, IL2026/IL3050 from JsonSerializer dominate.** Start with Strategy C unless the warning breakdown clearly shows otherwise. After the batch JSON fix, handle remaining warnings with Strategies A–B. Only use Strategy D as a last resort.
+
+### Step 4: Fix warnings iteratively (innermost first)
+
+Work from the **innermost** reflection call outward. Each fix may cascade new warnings to callers.
+
+**Stay warning-driven.** For each warning, open only the file and line the compiler reported, identify the pattern, apply the matching fix recipe below, and move on. Do not scan the codebase for similar patterns or try to understand the full architecture — fix what the compiler tells you, rebuild, and let new warnings guide the next change. Fix a small batch of warnings (5-10), then rebuild immediately to check progress.
+
+**Use sub-agents when available.** If you can launch sub-agents (e.g., via a `task` tool), dispatch **multiple sub-agents in parallel** to edit different files simultaneously. Keep the main loop focused on building, parsing warnings, and dispatching — delegate actual file edits to sub-agents. For batch JSON updates, give each sub-agent 5-10 files to update in one prompt. **After 2 build-fix cycles, dispatch all remaining file edits to sub-agents in parallel — do not continue fixing files sequentially.** Example:
+
+> Update these files to use source-generated JSON: `src/Models/Resource.Serialization.cs`, `src/Models/Identity.Serialization.cs`, `src/Models/Plan.Serialization.cs`. In each file, replace `JsonSerializer.Serialize(writer, value)` with `JsonSerializer.Serialize(writer, value, MyProjectJsonContext.Default.TypeName)` and `JsonSerializer.Deserialize<T>(ref reader)` with `JsonSerializer.Deserialize(ref reader, MyProjectJsonContext.Default.TypeName)`. Only edit the JsonSerializer call sites.
+
+#### Strategy A: Add `[DynamicallyAccessedMembers]` (preferred)
+
+When a method uses reflection on a `Type` parameter, annotate the parameter to tell the trimmer what members are needed:
+
+```csharp
+using System.Diagnostics.CodeAnalysis;
+
+// Before (warns IL2070):
+void Process(Type t) {
+    var method = t.GetMethod("Foo");  // trimmer can't verify
+}
+
+// After (clean):
+void Process([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type t) {
+    var method = t.GetMethod("Foo");  // trimmer preserves public methods
+}
+```
+
+When you annotate a parameter, **all callers** must now pass properly annotated types. This cascades outward — follow each caller and annotate or refactor as needed. **The caller's annotation must include at least the same member types as the callee's.** If the callee requires `PublicConstructors | NonPublicConstructors`, the caller must specify the same or a superset — using only `NonPublicConstructors` will produce IL2091.
+
+#### Strategy B: Refactor to preserve annotation flow
+
+When annotation flow is broken by boxing (storing `Type` in `object`, `object[]`, or untyped collections), **refactor** to pass the `Type` directly:
+
+```csharp
+// BROKEN: Type boxed into object[], annotation lost
+void Process(object[] args) {
+    Type t = (Type)args[0];  // IL2072: annotation lost through boxing
+    Evaluate(t, ...);
+}
+
+// FIXED: Pass Type as a separate, annotated parameter
+void Process(
+    object[] args,
+    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type calleeType,
+    ...) {
+    Evaluate(calleeType, ...);  // annotation flows cleanly
+}
+```
+
+Common patterns that break flow and how to fix them:
+- **`object[]` parameter bags**: Extract the `Type` into a dedicated annotated parameter
+- **Dictionary/List storage**: Use a typed field with annotation instead
+- **Interface indirection**: Add annotation to the interface method's parameter
+- **Property with boxing getter**: Annotate the property's return type
+
+#### Strategy C: Source-generated JSON serialization (batch fix)
+
+When most warnings are IL2026/IL3050 from `JsonSerializer.Serialize`/`Deserialize`, this is a single mechanical fix applied in bulk:
+
+1. **Collect affected types** — grep for all `JsonSerializer.Serialize` and `JsonSerializer.Deserialize` call sites. Extract the type being serialized (the `<T>` in `Deserialize<T>`, or the runtime type of the object in `Serialize`).
+
+2. **Create one `JsonSerializerContext`** with `[JsonSerializable]` for every type found. **Skip types from external packages** (e.g., `ResponseError` from `Azure.Core`) — they won't source-generate for types you don't own. Handle external types separately via Gotcha #1 below.
+
+```csharp
+[JsonSerializable(typeof(ManagedServiceIdentity))]
+[JsonSerializable(typeof(SystemData))]
+// ... one attribute per type YOU OWN
+// Do NOT add types from external packages (e.g., ResponseError)
+internal partial class MyProjectJsonContext : JsonSerializerContext { }
+```
+
+3. **Batch-update all call sites** — do not read each file individually. Apply the pattern mechanically:
+   - `JsonSerializer.Serialize(obj)` → `JsonSerializer.Serialize(obj, MyProjectJsonContext.Default.TypeName)`
+   - `JsonSerializer.Deserialize<T>(json)` → `JsonSerializer.Deserialize(json, MyProjectJsonContext.Default.TypeName)`
+
+   Find and update all call sites in one pass:
+   ```bash
+   # Find all files with JsonSerializer calls
+   grep -rl 'JsonSerializer\.\(Serialize\|Deserialize\)' src/ --include='*.cs'
+   ```
+   Then use sequential `edit` calls to apply the same transformation to every matching file. **Do not use `sed` for C# code** — generics like `Deserialize<T>()` have angle brackets and nested parentheses that sed will mangle.
+
+4. **Build once** to verify. Remaining warnings will be non-serialization issues — handle those with Strategies A–B or D.
+
+#### Strategy D: `[RequiresUnreferencedCode]` (last resort)
+
+When a method fundamentally requires arbitrary reflection that cannot be statically described:
+
+```csharp
+[RequiresUnreferencedCode("Loads plugins by name using Assembly.Load")]
+public void LoadPlugin(string assemblyName) {
+    var asm = Assembly.Load(assemblyName);
+    // ...
+}
+```
+
+This propagates to callers — they must also be annotated with `[RequiresUnreferencedCode]`. Use sparingly; it marks the entire call chain as trim-incompatible.
+
+### Step 5: Rebuild and repeat
+
+After each small batch of fixes (5-10 warnings), rebuild with `--no-incremental` and check for new warnings. **Do not attempt to fix all warnings before rebuilding** — frequent rebuilds catch mistakes early and reveal cascading warnings. Fixes cascade — annotating an inner method may surface warnings in its callers. Repeat until `0 Warning(s)`.
+
+### Step 6: Validate all TFMs
+
+Build all target frameworks to ensure:
+- **0 IL warnings** on net8.0+ TFMs
+- **No NETSDK1210 warnings** (the `IsAotCompatible` condition handles this)
+- **Clean builds** on older TFMs (netstandard2.0, net472, etc.)
+
+```bash
+dotnet build <project.csproj>  # builds all TFMs
+```
+
+## Stop Signals
+
+- **Do not analyze more than 2-3 representative files per warning pattern.** After identifying the fix for a pattern, apply it to all matching files without reading each one first.
+- **Start fixing after one build.** Do not do a second analysis pass — begin implementing fixes for the most common warning pattern immediately after Step 3 triage.
+- Stop after achieving **0 IL warnings** for net8.0+ TFMs. Don't optimize or refactor already-clean annotations.
+- If a warning requires **architectural refactoring** beyond annotation flow fixes (e.g., replacing an entire serialization layer), document it and stop — don't rewrite large subsystems.
+- Limit to **3 build-fix iterations** per warning. If annotation flow doesn't resolve it after 3 attempts, escalate to `[RequiresUnreferencedCode]`.
+- Don't chase warnings in **third-party dependencies** you can't modify. Note them and move on.
+- If the user asked a scoped question (e.g., "fix warnings in this file"), don't expand to the entire project.
+
+## Polyfills for Older TFMs
+
+For multi-targeting projects that include netstandard2.0 or net472, you need polyfills for `DynamicallyAccessedMembersAttribute` and related types. See [references/polyfills.md](references/polyfills.md).
+
+## Common Gotchas
+
+1. **External types without AOT-safe serialization**: When a type comes from a dependency you can't modify (e.g., `ResponseError` from `Azure.Core`) and it lacks a source-generated serializer, `Options.GetConverter<T>()` is reflection-based and will produce IL warnings. First check if the type implements `IJsonModel<T>` (common in Azure SDK) — if so, bypass `JsonSerializer` entirely:
+
+```csharp
+// Before (IL2026 — JsonSerializer uses reflection):
+JsonSerializer.Serialize(writer, errorValue);
+
+// After (AOT-safe — uses IJsonModel directly):
+((IJsonModel<ResponseError>)errorValue).Write(writer, ModelReaderWriterOptions.Json);
+
+// For deserialization:
+var error = ((IJsonModel<ResponseError>)new ResponseError()).Create(ref reader, ModelReaderWriterOptions.Json);
+```
+
+Do **not** add the external type to your `JsonSerializerContext` — it won't source-generate for types you don't own. If the type doesn't implement `IJsonModel<T>`, write a custom `JsonConverter<T>` with manual `Utf8JsonReader`/`Utf8JsonWriter` logic and register it via `[JsonSourceGenerationOptions]` on your context.
+
+2. **Serialization libraries**: Most reflection-based serializers (e.g., `Newtonsoft.Json`, `XmlSerializer`) are not AOT-compatible. Migrate to a source-generation-based serializer such as `System.Text.Json` with a `JsonSerializerContext`. If migration is not feasible, mark the serialization call site with `[RequiresUnreferencedCode]`.
+
+3. **Shared projects / projitems**: When source is shared between multiple projects via `<Import>`, annotations added to shared code affect ALL consuming projects. Verify that all consumers still build cleanly.
+
+## References
+
+[Limitations](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/?tabs=windows%2Cnet8#limitations-of-native-aot-deployment)
+[Conceptual: Understanding trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trimming-concepts)
+[How-to: trim compat](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/fixing-warnings)
+
+## Checklist
+
+- [ ] Added `<IsAotCompatible>` with TFM condition to .csproj
+- [ ] Built with AOT analyzers enabled (net8.0+ TFM)
+- [ ] Fixed all IL warnings via annotations or refactoring
+- [ ] No `#pragma warning disable` or `[UnconditionalSuppressMessage]` used for any IL warning
+- [ ] Polyfills present for older TFMs if needed
+- [ ] All target frameworks build with 0 warnings
+- [ ] Verified shared/linked source doesn't break sibling projects

package/package/corpus/skills/dotnet-aot-compat/references/polyfills.md

@@ -0,0 +1,43 @@
+# Polyfills for Older TFMs
+
+`DynamicallyAccessedMembersAttribute` shipped in .NET 5. For projects targeting netstandard2.0 or net472, you need a polyfill. The trimmer recognizes the attribute by name, so a local copy works:
+
+```csharp
+#if !NET
+namespace System.Diagnostics.CodeAnalysis
+{
+    [AttributeUsage(AttributeTargets.Field | AttributeTargets.ReturnValue |
+                    AttributeTargets.GenericParameter | AttributeTargets.Parameter |
+                    AttributeTargets.Property, Inherited = false)]
+    internal sealed class DynamicallyAccessedMembersAttribute : Attribute
+    {
+        public DynamicallyAccessedMembersAttribute(DynamicallyAccessedMemberTypes memberTypes)
+            => MemberTypes = memberTypes;
+        public DynamicallyAccessedMemberTypes MemberTypes { get; }
+    }
+
+    [Flags]
+    internal enum DynamicallyAccessedMemberTypes
+    {
+        None = 0,
+        PublicParameterlessConstructor = 0x0001,
+        PublicConstructors = 0x0002 | PublicParameterlessConstructor,
+        NonPublicConstructors = 0x0004,
+        PublicMethods = 0x0008,
+        NonPublicMethods = 0x0010,
+        PublicFields = 0x0020,
+        NonPublicFields = 0x0040,
+        PublicNestedTypes = 0x0080,
+        NonPublicNestedTypes = 0x0100,
+        PublicProperties = 0x0200,
+        NonPublicProperties = 0x0400,
+        PublicEvents = 0x0800,
+        NonPublicEvents = 0x1000,
+        Interfaces = 0x2000,
+        All = ~None // Discouraged — prefer specific flags
+    }
+}
+#endif
+```
+
+Similarly for `RequiresUnreferencedCodeAttribute` and `UnconditionalSuppressMessageAttribute` if needed on older TFMs.

package/package/corpus/skills/dotnet-trace-collect/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/dotnet-trace-collect/NOTICE

@@ -0,0 +1,65 @@
+.NET Trace Collect
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Move the complete ### Step 2: Recommend diagnostic tools section verbatim into references/tool-selection.md to fit the body limit; leave a direct pointer.
+- Add direct conditional pointers for all otherwise-indirect reference/script/asset files: references/dotnet-monitor.md, references/dotnet-trace-collect-linux.md, references/dotnet-trace-collect.md, references/perfcollect.md, references/perfview.md.
+- Place approval guards immediately before complete Markdown tables so original rows remain intact.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+references/dotnet-monitor.md:
+- Quote the dotnet-monitor trace URL containing ampersand.
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+
+references/dotnet-trace-collect.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+
+references/perfcollect.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+- Place approval guards immediately before complete Markdown tables so original rows remain intact.
+
+references/perfview.md:
+- Prefix official tool downloads/installs with marked approval/pinned-version guidance and privileged/perfcollect examples with explicit root/container-security approval, where present.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+- Add marked approval and pinned-version guidance before the official direct-download/source-build fallback.
+
+references/tool-selection.md:
+- Adjust the moved reference-relative Markdown links to preserve their targets.
+- Contain the section moved verbatim from SKILL.md, with a reference H1 title.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.
+
+Executes or downloads (instructions retained, not executed by this import):
+- references/tool-selection.md: 3. **`perfcollect`** — inside the container when native stacks are needed on pre-.NET 10 (requires `SYS_ADMIN` / `--privileged`).
+- SKILL.md: 1. **Installation**: How to install the tool if it is not already available (e.g. `dotnet tool install -g dotnet-trace`). **When recommending multiple tools, provide installation and usage instructions for each one** — do not mention a tool without showing how to install and use it.
+- SKILL.md: | `perfcollect` in container without `SYS_ADMIN` | Containers drop `SYS_ADMIN` by default. Run with `--privileged` or add `SYS_ADMIN` capability, or fall back to `dotnet-trace`. |
+- SKILL.md: | Forgetting to install tools in container image | Add `dotnet tool install` to your Dockerfile, or use `dotnet-monitor` as a sidecar to avoid modifying the app image. |
+- references/dotnet-monitor.md: dotnet tool install -g dotnet-monitor
+- references/dotnet-trace-collect.md: dotnet tool install -g dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-x64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-arm64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/linux-musl-x64 -o dotnet-trace
+- references/dotnet-trace-collect.md: curl -JL https://aka.ms/dotnet-trace/win-x64 -o dotnet-trace.exe
+- references/perfcollect.md: | Container | Needs `SYS_ADMIN` / `--privileged` |
+- references/perfcollect.md: curl -OL https://aka.ms/perfcollect
+- references/perfcollect.md: sudo ./perfcollect install
+- references/perfcollect.md: docker run --privileged ...
+- references/perfcollect.md: privileged: true
+- references/perfcollect.md: allowPrivilegeEscalation: true
+- references/perfcollect.md: ./perfcollect install
+- references/perfcollect.md: - ❌ In containers, requires `SYS_ADMIN` or `--privileged`
+- references/perfview.md: Download from [https://github.com/microsoft/perfview/releases](https://github.com/microsoft/perfview/releases). PerfView is a standalone `.exe` — no installation required.
+- references/perfview.md: > **PerfView inside containers**: `PerfView.exe` does not run in many slimmed-down Windows container images. To run PerfView inside a container (needed for the merge step in process-isolation, or for direct collection in Hyper-V), build **PerfViewCollect** from [https://github.com/microsoft/perfview](https://github.com/microsoft/perfview) as a self-contained publish, then copy the output binaries into the container.

package/package/corpus/skills/dotnet-trace-collect/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: dotnet-trace-collect
+description: 'Guides capturing diagnostic artifacts to diagnose production .NET performance problems: choosing tools, collecting performance data, and understanding trade-offs across Windows and Linux, .NET Framework and modern .NET, and container and non-container environments. Use when the user needs help choosing a diagnostic tool or collecting performance data for a .NET process. Not for crash dumps (use dump-collect), repository-level profiling workflows (use profiling), or analyzing collected traces.'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-diag/skills/dotnet-trace-collect/SKILL.md; see NOTICE) -->
+
+# .NET Trace Collect
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+This skill helps developers diagnose production performance issues by recommending the right diagnostic tools for their environment, guiding data collection, and suggesting analysis approaches. It does not analyze code for anti-patterns or perform the analysis itself.
+
+## When to Use
+
+- A developer needs to investigate a production performance issue (high CPU, memory leak, slow requests, excessive GC, networking errors, etc.)
+- Choosing the right diagnostic tool for a specific runtime, OS, or deployment topology
+- Setting up and running diagnostic tool commands for data collection
+- Understanding trade-offs between available tools (e.g. PerfView vs dotnet-trace)
+- Collecting diagnostics from containerized or Kubernetes workloads
+
+## When Not to Use
+
+- Reviewing source code for performance anti-patterns (use a code review skill instead)
+- Benchmarking during development (e.g. BenchmarkDotNet setup)
+- Analyzing collected trace or dump files (this skill recommends tools for analysis, but does not perform it)
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| Symptom | Yes | What the developer is observing (high CPU, memory growth, slow requests, hangs, excessive GC, HTTP 5xx errors, networking timeouts, connection failures, assembly loading failures, etc.) |
+| Runtime | Yes | .NET Framework or modern .NET (and version, especially whether .NET 10+) |
+| OS | Yes | Windows or Linux |
+| Deployment | Yes | Non-container, container, or Kubernetes |
+| Admin privileges | Recommended | Whether the developer has admin/root access on the target machine |
+| Repro characteristics | Recommended | Whether the issue is easy to reproduce or requires a long time to manifest |
+
+## Workflow
+
+### Step 1: Understand the environment
+
+Determine or ask the developer to clarify:
+
+1. **Symptom**: What they are observing (high CPU, memory leak, slow requests, hangs, excessive GC, HTTP 5xx errors, networking timeouts, connection failures, assembly loading failures, etc.)
+2. **Runtime**: .NET Framework or modern .NET? If modern .NET, which version? (Especially whether .NET 10 or later.)
+3. **OS**: Windows or Linux?
+4. **Deployment**: Running directly on the host, in a container, or in Kubernetes?
+5. **Admin privileges**: Do they have admin/root access on the target machine or container?
+6. **Repro characteristics**: Does the issue reproduce quickly, or does it take a long time to manifest?
+7. **Workload context**: Determine or ask the user if you are running in the context of the workload (i.e., on the same machine or connected to the same environment where the issue is occurring). If so, you can run diagnostic commands directly on their behalf. If not, provide the commands as guidance for the user to run themselves.
+
+Use this information to select the right tool in Step 2.
+
+Read references/tool-selection.md when selecting the relevant diagnostic workflow.
+
+### Step 3: Guide data collection
+
+Provide the specific commands for the recommended tool. Load the appropriate reference file from the [tool reference lookup](references/tool-selection.md#tool-reference-lookup) table for detailed command-line examples.
+
+Key guidance to include:
+
+> **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+1. **Installation**: How to install the tool if it is not already available (e.g. `dotnet tool install -g dotnet-trace`). **When recommending multiple tools, provide installation and usage instructions for each one** — do not mention a tool without showing how to install and use it.
+2. **PID discovery (required before any `-p <PID>` command)**: Verify the target process first (for example: `dotnet-trace ps`, `curl <monitor-endpoint>/processes`, or `ps` inside a container). If the app is expected to be PID 1 in a container, still verify before collecting.
+3. **Collection command**: The exact command to run, including relevant providers, output format, and duration.
+4. **Container considerations**:
+   - Collecting from **inside** the container: ensure the tool is installed in the image or use `kubectl cp` to copy it in.
+   - Collecting from **outside** the container: use `dotnet-monitor` as a sidecar with a shared diagnostic port (Unix domain socket in `/tmp`).
+   - Kubernetes: `dotnet-monitor` as a sidecar container, or `kubectl debug` for ephemeral debug containers.
+5. **Long-running repros** (Windows/PerfView): show how to use trigger arguments and circular buffer settings.
+6. **Output location**: Where the collected file will be saved and how to copy it off the target for analysis.
+7. **Artifact handoff checklist**: Include runtime version, OS/kernel, container image tag or build SHA, PID/process name, UTC collection start/end timestamps, exact command used, and final artifact path when handing traces to someone else for analysis.
+
+### Step 4: Recommend analysis approach
+
+After data is collected, recommend the appropriate tool for analysis. Do **not** perform the analysis — just point the developer to the right tool and documentation.
+
+| Collected Data | Analysis Tool | Notes |
+|----------------|---------------|-------|
+| `.nettrace` file | PerfView (Windows), Speedscope (web) | PerfView gives the richest view on Windows |
+| `.etl` / `.etl.zip` file | PerfView | ETW traces from PerfView or perfcollect |
+| `perf.data.nl` from perfcollect | PerfView (Windows) | Copy the file to a Windows machine and open with PerfView |
+
+## Validation
+
+- [ ] The recommended tool is compatible with the developer's runtime, OS, and deployment topology
+- [ ] The collection command runs without errors
+- [ ] The output file is generated in the expected location
+- [ ] The developer knows which analysis tool to use for the collected data
+
+## Common Pitfalls
+
+> **Cratis:** Requires the user's explicit approval: downloads and runs a script as root / changes container security.
+> **Cratis:** Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+
+| Pitfall | Solution |
+|---------|----------|
+| Using `dotnet-trace` on .NET Framework | `dotnet-trace` only works with modern .NET (.NET Core 3.0+). Use PerfView for .NET Framework. |
+| PerfView without admin privileges | PerfView requires admin for ETW tracing. Fall back to `dotnet-trace` if admin is not available. |
+| `perfcollect` in container without `SYS_ADMIN` | Containers drop `SYS_ADMIN` by default. Run with `--privileged` or add `SYS_ADMIN` capability, or fall back to `dotnet-trace`. |
+| Huge trace files from long repros | On Windows, use PerfView `/StopOn` triggers that fire on the symptom you want to capture (e.g., `/StopOnPerfCounter`, `/StopOnGCEvent`, `/StopOnException`) with `/CircularMB` and `/BufferSizeMB`. **Never trigger on recovery** — the circular buffer continuously overwrites old data, so the interesting behavior may be lost by the time collection stops. |
+| Diagnostic port not accessible in container | Mount `/tmp` as a shared volume between the app container and `dotnet-monitor` sidecar for the diagnostic Unix domain socket. |
+| Forgetting to install tools in container image | Add `dotnet tool install` to your Dockerfile, or use `dotnet-monitor` as a sidecar to avoid modifying the app image. |
+| Exposing `dotnet-monitor` with `--no-auth` in production | Keep auth enabled, bind to localhost, and use `kubectl port-forward` for access. Use `--no-auth` only for short-lived isolated debugging. |
+| Collecting only CPU/thread-time trace for networking issues | CPU and thread-time traces alone do not show HTTP status codes, DNS timing, or connection pool behavior. Add the networking providers (`System.Net.Http`, `System.Net.NameResolution`, `System.Net.Security`, `System.Net.Sockets`) alongside the thread-time trace. |
+| Enabling all networking providers when only one is needed | Each networking provider adds overhead. If the issue is clearly HTTP-level (5xx status codes), `System.Net.Http` alone may be sufficient. Add DNS, TLS, and socket providers when the root cause is unclear. |
+
+## Reference navigation
+
+- Read references/dotnet-monitor.md when working on dotnet monitor.
+- Read references/dotnet-trace-collect-linux.md when working on dotnet trace collect linux.
+- Read references/dotnet-trace-collect.md when working on dotnet trace collect.
+- Read references/perfcollect.md when working on perfcollect.
+- Read references/perfview.md when working on perfview.

package/package/corpus/skills/dotnet-trace-collect/references/dotnet-monitor.md

@@ -0,0 +1,97 @@
+# dotnet-monitor
+
+**Purpose**: REST API-based diagnostics collection, designed for container and Kubernetes environments.
+
+| Attribute | Value |
+|-----------|-------|
+| OS | Windows, Linux, macOS |
+| Runtime | Modern .NET (.NET Core 3.1+) |
+| .NET Framework | ❌ Not supported |
+| Admin required | No |
+| Container | ✅ Designed for containers/K8s — runs as a sidecar |
+
+## Installation
+
+```bash
+# As a global tool
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+dotnet tool install -g dotnet-monitor
+
+# As a container image (for K8s sidecar)
+# mcr.microsoft.com/dotnet/monitor
+```
+
+## Common Commands
+
+```bash
+# Production-safe default: keep auth enabled (default) and bind to loopback
+dotnet-monitor collect --urls http://127.0.0.1:52323 --metricUrls http://127.0.0.1:52325
+
+# Dev-only shortcut in isolated environments (avoid in production)
+dotnet-monitor collect --urls http://127.0.0.1:52323 --no-auth
+```
+
+## Security Guidance (Production)
+
+- Do **not** run `dotnet-monitor` with `--no-auth` on production workloads.
+- Bind to localhost (`127.0.0.1`) and access through `kubectl port-forward` (or another local-only tunnel).
+- If remote access is required, keep auth enabled and restrict network exposure to trusted operators.
+
+## REST API Endpoints
+
+```bash
+# Access via local tunnel (recommended in Kubernetes)
+kubectl port-forward pod/<pod-name> 52323:52323
+
+# List processes (auth enabled by default)
+curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/processes
+
+# Collect a trace
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&durationSeconds=30"
+
+# Collect GC trace
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&profile=gc-verbose&durationSeconds=30"
+
+# Collect trace with networking providers (HTTP status codes, DNS, TLS, sockets)
+curl -H "Authorization: Bearer <monitor-token>" -o trace.nettrace "http://localhost:52323/trace?pid=<PID>&durationSeconds=30&providers=System.Net.Http,System.Net.NameResolution,System.Net.Security,System.Net.Sockets"
+
+# Get live metrics
+curl -H "Authorization: Bearer <monitor-token>" http://localhost:52323/livemetrics?pid=<PID>
+```
+
+## Kubernetes Sidecar Setup
+
+```yaml
+# Pod spec with dotnet-monitor as sidecar
+spec:
+  containers:
+  - name: app
+    image: myapp:latest
+    volumeMounts:
+    - name: diag
+      mountPath: /tmp
+  - name: monitor
+    image: mcr.microsoft.com/dotnet/monitor:latest
+    args: ["collect", "--urls", "http://127.0.0.1:52323", "--metricUrls", "http://127.0.0.1:52325"]
+    volumeMounts:
+    - name: diag
+      mountPath: /tmp
+    ports:
+    - containerPort: 52323
+  volumes:
+  - name: diag
+    emptyDir: {}
+```
+
+The shared `/tmp` volume allows `dotnet-monitor` to access the app's diagnostic Unix domain socket.
+Keep auth enabled (default), and access the API via `kubectl port-forward` rather than exposing a public Service unless you have explicit authentication and network controls in place.
+
+## Trade-offs
+
+- ✅ Purpose-built for containers and Kubernetes
+- ✅ No tools needed inside the app container
+- ✅ REST API is easy to automate and integrate
+- ❌ Requires sidecar setup and shared volume
+- ❌ Additional resource overhead from sidecar container
+- ❌ Requires authentication setup (API key or `--no-auth` flag)
+- ⚠️ **When running in the workload context** (console access to the container), prefer console-based tools (`dotnet-trace`, `dotnet-trace collect-linux`) to avoid authentication setup. Use `dotnet-monitor` when console access is not available or when it is already deployed.