@damiangilgonzalez/harness 1.3.7

package/skills/csharp-dotnet/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: csharp-dotnet
+description: "Use when writing, reviewing, testing, or shipping C# / .NET code — ASP.NET Core APIs (minimal APIs vs controllers), EF Core data access, async correctness, solution layout in .cs/.csproj/.sln. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs), NOT framework-neutral REST naming (that is api-design)."
+tags: [csharp, dotnet, aspnetcore, efcore, async]
+recommends: [postgresdb, secure-coding, deployment]
+origin: risco
+---
+
+# Modern C# and .NET services
+
+You write and review C#, ASP.NET Core APIs, and EF Core data access. You own the
+.NET idioms, the HTTP-contract patterns *as expressed in .NET*, async correctness,
+and the .NET-specific quality/security gates. You delegate everything language-
+agnostic to the right sibling.
+
+**Target: .NET 10 (LTS, released 2025-11-11, supported 3 years) with C# 14, EF Core
+10, ASP.NET Core 10.** .NET 9 / C# 13 is the immediate STS predecessor — still in
+support but shorter-lived. Features gate on the target framework moniker (TFM): a
+`net10.0` project gets C# 14 by default; a `net9.0` project caps at C# 13. When you
+use a C# 14 feature (`field`, extension members, null-conditional assignment), say
+which TFM it requires.
+
+## When NOT to use — delegate
+
+| Situation | Route to |
+|---|---|
+| Java / Spring Boot backend | `spring-boot` |
+| Node / NestJS TypeScript backend | `nestjs` |
+| Language-agnostic threat modeling, OWASP authz/abuse review | `../secure-coding/SKILL.md` |
+| Raw Postgres schema/index/query tuning | `../postgresdb/SKILL.md` |
+| Framework-neutral REST resource taxonomy | `api-design` |
+| Dockerfile / CI pipeline / deploy target | `../deployment/SKILL.md` |
+| Recording per-project conventions in the workspace wiki | `../harness/SKILL.md` |
+
+The .NET *expression* of an API contract and async correctness live HERE. Resource
+naming theory lives in `api-design`; the JVM and Node counterparts are `spring-boot`
+and `nestjs`.
+
+## Project & solution layout + dotnet CLI
+
+```bash
+dotnet new sln -n Shop                         # solution
+dotnet new webapi -n Shop.Api                  # minimal API (default in .NET 10)
+dotnet new webapi -n Shop.Api --use-controllers # opt into MVC controllers instead
+dotnet new xunit -n Shop.Api.Tests             # test project
+dotnet sln add Shop.Api Shop.Api.Tests         # wire into the solution
+dotnet add Shop.Api package Npgsql.EntityFrameworkCore.PostgreSQL
+dotnet ef migrations add Initial -p Shop.Api   # create a migration
+dotnet ef database update -p Shop.Api          # apply migrations
+dotnet build -warnaserror                      # compile; analyzers + NRT as errors
+dotnet test                                    # run tests
+dotnet format                                  # apply style; --verify-no-changes in CI
+dotnet publish -c Release                       # produce deployable output
+```
+
+Recommended shape:
+
+```text
+Shop.sln
+Directory.Packages.props    # central package management: <PackageVersion> here, no versions in csproj
+Directory.Build.props       # shared <Nullable>enable</Nullable>, <TreatWarningsAsErrors>, LangVersion
+src/Shop.Api/               # endpoints grouped by feature module (Products/, Orders/)
+src/Shop.Domain/            # entities, value objects (no EF/ASP.NET dependency)
+tests/Shop.Api.Tests/
+```
+
+Central package management: turn it on with `<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>`
+and list versions once in `Directory.Packages.props`. Why: one source of truth, no
+version drift across projects.
+
+NRT on for every project — `<Nullable>enable</Nullable>` in `Directory.Build.props`.
+Why: the compiler turns whole classes of `NullReferenceException` into build-time
+warnings. Never disable it to silence a warning — fix the nullability.
+
+## Modern C# idioms (C# 14 / .NET 10)
+
+DTO as a record, not a class:
+
+```csharp
+// Bad: mutable class, no value equality, hand-written boilerplate
+public class ProductDto { public int Id { get; set; } public string Name { get; set; } }
+
+// Good: immutable record DTO
+public record ProductDto(int Id, string Name, decimal Price);
+```
+
+Why: value equality, `with` expressions, no boilerplate — and never reuse an EF entity
+as the wire DTO (see anti-patterns).
+
+Pattern matching over if-chains:
+
+```csharp
+// Bad
+if (shape is Circle) { var c = (Circle)shape; return Math.PI * c.R * c.R; }
+
+// Good
+return shape switch
+{
+    Circle c      => Math.PI * c.R * c.R,
+    Rectangle r   => r.W * r.H,
+    _             => throw new ArgumentOutOfRangeException(nameof(shape)),
+};
+```
+
+`field` keyword — field-backed property without a hand-written backing field
+(**requires C# 14 / net10.0**):
+
+```csharp
+// Bad: explicit backing field just to trim a string
+private string _name = "";
+public string Name { get => _name; set => _name = value.Trim(); }
+
+// Good (C# 14)
+public string Name { get; set => field = value.Trim(); }
+```
+
+Primary constructors, `required`/`init`, collection expressions:
+
+```csharp
+public class OrderService(IOrderRepository repo, ILogger<OrderService> log)  // primary ctor: DI in one line
+{
+    public required string Region { get; init; }                            // must be set at construction, then immutable
+    private static readonly int[] DefaultTiers = [1, 2, 3];                  // collection expression
+}
+```
+
+Prefer NRT annotations over defensive null checks: declare `string? note` when null is
+valid and let the compiler force callers to handle it, instead of `if (x == null)`
+guards scattered everywhere.
+
+Dispose deterministically: `using` / `await using` (or `using` declarations) for
+anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections and handles.
+
+## async/await correctness
+
+This is the highest-leverage area to get right. Core rules in body; the full catalog
+(ConfigureAwait, ValueTask, IAsyncEnumerable, Channels, parallelism, deadlock cases)
+is in **references/async.md** — read it before any non-trivial async review.
+
+- **No `async void`** except top-level event handlers. Why: exceptions escape onto the
+  thread pool and crash the process; the caller cannot `await` or catch it. Use `async Task`.
+- **Never `.Result` / `.Wait()` / `GetAwaiter().GetResult()` on the request path.** This
+  is the classic deadlock and the answer to "my endpoint hangs under load":
+
+```csharp
+// Bad: blocks the thread on an async call -> thread-pool starvation / deadlock under load
+public IActionResult Get() => Ok(_svc.LoadAsync().Result);
+
+// Good: await all the way up
+public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.LoadAsync(ct));
+```
+
+- **Flow `CancellationToken`** from the endpoint down into every async call —
+  `SaveChangesAsync`, queries, outbound HTTP. Why: a dropped token means the request
+  keeps running after the client gives up.
+- **`ValueTask` only for hot paths** that usually complete synchronously; default to
+  `Task`. Never `await` a `ValueTask` twice.
+- **`IAsyncEnumerable<T>` for streaming** results instead of materializing a huge list.
+
+## ASP.NET Core APIs
+
+Decision: **minimal API** for new services; **controllers** only when you need MVC
+machinery (model binding conventions, action filters at scale, views). Both can coexist.
+Why minimal by default: less ceremony, first-class in .NET 10.
+
+Production minimal API shape — route group + DataAnnotations validation (built in for
+minimal API parameters in .NET 10) + ProblemDetails + OpenAPI 3.1:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOpenApi();                 // OpenAPI 3.1, JSON Schema 2020-12
+builder.Services.AddProblemDetails();          // RFC 9457 error bodies
+builder.Services.AddDbContext<ShopDb>(o => o.UseNpgsql(builder.Configuration.GetConnectionString("Shop")));
+
+var app = builder.Build();
+app.MapOpenApi();                              // serves the OpenAPI document
+app.UseExceptionHandler();                     // emits ProblemDetails on unhandled errors
+
+var products = app.MapGroup("/products").WithTags("Products");
+products.MapGet("/{id:int}", async (int id, ShopDb db, CancellationToken ct) =>
+    await db.Products.AsNoTracking()
+        .Where(p => p.Id == id)
+        .Select(p => new ProductDto(p.Id, p.Name, p.Price))   // project to DTO, no entity leak
+        .FirstOrDefaultAsync(ct) is { } dto
+        ? Results.Ok(dto)
+        : Results.NotFound());
+products.MapPost("/", async (CreateProduct req, ShopDb db, CancellationToken ct) =>
+{   // DataAnnotations on CreateProduct are validated automatically in .NET 10
+    var entity = new Product { Name = req.Name, Price = req.Price };
+    db.Products.Add(entity);
+    await db.SaveChangesAsync(ct);
+    return Results.Created($"/products/{entity.Id}", new ProductDto(entity.Id, entity.Name, entity.Price));
+});
+app.Run();
+```
+
+DI lifetimes: `Singleton` (one for the app), `Scoped` (one per request — `DbContext`
+lives here; it is not thread-safe, so sharing one across requests corrupts change
+tracking), `Transient` (new each resolve). Never inject a `Scoped` service into a
+`Singleton` (captive dependency — see anti-patterns). Middleware ordering, endpoint
+filters, the options pattern, and auth defaults are in **references/aspnetcore.md**.
+
+## EF Core 10
+
+```csharp
+// Bad: tracking + N+1 — loads orders, then one query per order's customer
+var orders = await db.Orders.ToListAsync(ct);
+foreach (var o in orders) { var name = o.Customer.Name; /* lazy/round-trip per row */ }
+
+// Good: no-tracking read + single query via projection
+var rows = await db.Orders.AsNoTracking()
+    .Select(o => new OrderRow(o.Id, o.Customer.Name))   // EF translates to one JOIN
+    .ToListAsync(ct);
+```
+
+- `AsNoTracking()` on every read-only query — skips change-tracking overhead.
+- Kill N+1 with projection (`Select`) or `Include`/`ThenInclude`; use `AsSplitQuery()`
+  when an `Include` cartesian explosion hurts.
+- Migrations: `dotnet ef migrations add <Name>` then review the generated `Up`/`Down`
+  before `database update`. Never hand-edit applied migrations.
+- EF Core 10 highlights: native `json` column type, `vector` type + `VECTOR_DISTANCE()`
+  for embeddings/RAG, `LeftJoin`/`RightJoin` LINQ operators, and named query filters
+  (multiple filters per entity, selectively disabled).
+
+Raw SQL only via parameterized `FromSql`/`ExecuteSql` interpolated strings (EF
+parameterizes the holes). Query patterns, migration workflow, the EF Core 10 features,
+and raw-SQL safety in full are in **references/efcore.md**. Schema/index tuning is
+`../postgresdb/SKILL.md`.
+
+## .NET security controls
+
+Keep only the .NET-specific controls here; threat modeling and OWASP review go to
+`../secure-coding/SKILL.md`.
+
+- **Parameterized data access** — EF LINQ / parameterized `FromSql` / ADO.NET
+  `SqlParameter`. Never concatenate user input into SQL. Why: SQL injection.
+- **Secrets** — `dotnet user-secrets` in dev, Key Vault / environment in prod. Never in
+  `appsettings.json` or source.
+- **Antiforgery** for cookie-auth browser POSTs; **Data Protection** for cookies/tokens
+  (configure a persisted key ring across instances).
+- **Auth defaults** — authenticate then authorize via middleware; prefer policy-based
+  authorization; ASP.NET Core 10 is secure-by-default but still verify HTTPS redirection
+  and HSTS in production.
+
+## Testing
+
+- **xUnit** is the default. Unit-test domain logic with no framework dependency.
+- **Integration tests** via `WebApplicationFactory<Program>` — boots the real pipeline
+  in-memory and lets you `HttpClient` your endpoints.
+- **Testcontainers** to run a real Postgres in a container for EF integration tests
+  instead of the in-memory provider (which lies about relational behavior).
+- Gate everything with `scripts/verify.sh` (format + build-warnaserror + test + vuln scan).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `async void` (non-event-handler) | Exceptions crash the process; uncatchable by caller | `async Task` |
+| `.Result` / `.Wait()` on request path | Deadlock / thread-pool starvation under load | `await` all the way |
+| Scoped service injected into a Singleton | Captive dependency: stale/`DbContext` reused across requests | Inject `IServiceScopeFactory`, or make the consumer scoped |
+| Reusing an EF entity as the wire DTO | Over-posting, serialization cycles, leaked columns | Separate `record` DTO + mapping |
+| Tracking queries on read-only reads | Wasted memory/CPU on change tracking | `AsNoTracking()` |
+| Lazy navigation in a loop | N+1 round-trips | Projection or `Include` |
+| Missing `CancellationToken` | Work continues after client disconnects | Flow the token to all I/O |
+| `catch (Exception) { }` swallow | Hides failures; corrupt state continues | Handle specifically or let `UseExceptionHandler` map it |
+| `<Nullable>disable</Nullable>` to mute a warning | Re-opens the NRE class of bugs | Keep NRT on; fix the nullability |
+
+## Project grounding
+
+Record per-project conventions (target TFM, package manager, lint rules, deploy
+target) in the workspace wiki via `../harness/SKILL.md`, not inline assumptions. Before
+calling a C# change done, run `scripts/verify.sh` from the solution/project root.

package/skills/csharp-dotnet/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — csharp-dotnet
+
+These cases are read by a human or an LLM judge, not by an automated test runner. To run them, install the skill and feed each prompt to the agent: `should_trigger` cases should make the agent reach for `csharp-dotnet` (check the routing against each `why`), and `should_not_trigger` cases should route to the named sibling instead (`route_to`). For the `capability` case, give the agent the scenario, then score the generated code against every line in `must_include` — each bullet is pass/fail, and a strong result hits all of them (net10.0 TFM, NRT on, record DTO separate from the entity, async with CancellationToken, validation + ProblemDetails, OpenAPI wired, AsNoTracking with no N+1). It is a rubric, not an assertion library, so judge intent and substance over exact wording.

package/skills/csharp-dotnet/evals/cases.yaml

@@ -0,0 +1,48 @@
+skill: csharp-dotnet
+
+should_trigger:
+  - prompt: "Build an ASP.NET Core minimal API for /products with validation and OpenAPI."
+    why: Core authoring task — minimal API + DataAnnotations validation + OpenAPI are this skill's bread and butter.
+  - prompt: "Is this idiomatic C#? Should this DTO be a record with init-only props?"
+    why: Idiom review with no tool/framework named — record-vs-class and init-only are .NET idioms this skill owns.
+  - prompt: "My API endpoint hangs and deadlocks under load — it calls .Result on an async method."
+    why: Non-obvious symptom phrasing; the user does not say "sync-over-async" but that is exactly the deadlock this skill diagnoses.
+  - prompt: "This EF Core query loads orders then hits the database once per order in a loop."
+    why: N+1 described by symptom, not by name — EF Core query shape is in scope here.
+  - prompt: "Add xUnit integration tests with WebApplicationFactory for my controllers."
+    why: .NET testing contract — WebApplicationFactory is the ASP.NET Core integration-test primitive.
+  - prompt: "revisa este código C# antes de hacer deploy"
+    why: Spanish trigger for a C# code review before shipping — language-family review is this skill.
+  - prompt: "How do I structure a .NET solution with src/ and tests/ and central package management?"
+    why: dotnet CLI + solution layout + Directory.Packages.props are covered directly in the body.
+
+should_not_trigger:
+  - prompt: "Build the same REST API but in Spring Boot with JPA."
+    route_to: spring-boot
+    why: JVM/Java backend — explicitly delegated; this skill is the .NET counterpart only.
+  - prompt: "Threat-model my multi-tenant authorization boundaries against OWASP."
+    route_to: secure-coding
+    why: Framework-neutral threat modeling; this skill keeps only the concrete .NET controls.
+  - prompt: "Tune this slow Postgres query and design the right indexes."
+    route_to: postgresdb
+    why: Raw DB schema/index/query tuning — not EF mapping or LINQ translation.
+  - prompt: "Write a Dockerfile and GitHub Actions workflow to deploy my .NET app to Hetzner."
+    route_to: deployment
+    why: Containerization and CI/deploy targets live in deployment; this skill stops at dotnet publish.
+  - prompt: "Build this backend in NestJS with TypeScript decorators."
+    route_to: nestjs
+    why: Node/TypeScript backend — the wrong language family entirely.
+
+capability:
+  - scenario: >
+      Write a production-shaped ASP.NET Core 10 minimal API for a TODO resource backed by
+      EF Core on Postgres: validation, ProblemDetails, OpenAPI, async with CancellationToken,
+      and a DTO that is separate from the EF entity.
+    must_include:
+      - "Minimal API using a route group (MapGroup) — or controllers with a stated justification."
+      - "A record DTO distinct from the EF entity, with explicit mapping between them."
+      - "async handlers that flow CancellationToken into SaveChangesAsync and queries."
+      - "DataAnnotations validation (or an endpoint filter) plus a ProblemDetails error shape."
+      - "OpenAPI wired via AddOpenApi() and MapOpenApi()."
+      - "AsNoTracking() on the read path and no N+1 (projection or Include)."
+      - "Targets net10.0 with nullable reference types enabled."

package/skills/csharp-dotnet/references/aspnetcore.md

@@ -0,0 +1,99 @@
+# ASP.NET Core 10 — full catalog
+
+The body has the decision and the canonical shape; this is the depth.
+
+## Minimal APIs vs controllers
+
+| Pick minimal APIs when | Pick controllers when |
+|---|---|
+| New service, REST/JSON endpoints, route groups suffice | You need view rendering (MVC/Razor) |
+| You want the least ceremony and AOT-friendliness | You rely on the full filter pipeline, conventions, or `ApiController` model-binding niceties at scale |
+| Endpoints map cleanly to delegates | Large teams already standardized on controllers |
+
+They coexist in one app. Default to minimal for new code; state the reason if you choose controllers.
+
+## Route groups + endpoint filters
+
+```csharp
+var products = app.MapGroup("/products")
+    .WithTags("Products")
+    .RequireAuthorization()                 // applies to the whole group
+    .AddEndpointFilter<ValidationFilter>(); // cross-cutting check per request
+
+products.MapGet("/{id:int}", GetById);
+products.MapPost("/", Create);
+```
+
+An endpoint filter runs around the handler — use it for validation, logging, or shaping results without repeating code per endpoint.
+
+```csharp
+public sealed class ValidationFilter : IEndpointFilter
+{
+    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
+    {
+        // inspect ctx.Arguments, short-circuit with Results.ValidationProblem(...) if invalid
+        return await next(ctx);
+    }
+}
+```
+
+## Validation (.NET 10)
+
+In .NET 10, DataAnnotations on minimal API parameters — query, header, and body, **including records** — are validated automatically; a failure produces a ProblemDetails 400 without manual code. Annotate the DTO and you are done for simple cases; use an endpoint filter or FluentValidation for cross-field rules.
+
+```csharp
+public record CreateProduct(
+    [property: Required, MaxLength(120)] string Name,
+    [property: Range(0.0, 1_000_000.0)] decimal Price);
+```
+
+## ProblemDetails (RFC 9457)
+
+`AddProblemDetails()` + `UseExceptionHandler()` turn unhandled exceptions and status-code responses into a consistent machine-readable error body. Never return raw exception text to clients. Use `Results.Problem(...)` / `Results.ValidationProblem(...)` for explicit error shaping.
+
+## OpenAPI 3.1
+
+`Microsoft.AspNetCore.OpenAPI` generates an **OpenAPI 3.1** document (JSON Schema draft 2020-12) at build/runtime:
+
+```csharp
+builder.Services.AddOpenApi();
+app.MapOpenApi();               // serves /openapi/v1.json
+```
+
+Annotate with `.WithTags(...)`, `.WithName(...)`, `.Produces<T>(...)`, `.WithSummary(...)` for a richer document. Pair with a UI (Scalar, Swagger UI) only in non-prod by default.
+
+## Middleware ordering
+
+Order matters — each component sees the request on the way in and the response on the way out. A workable baseline:
+
+```text
+UseExceptionHandler  ->  HSTS / HttpsRedirection  ->  static assets
+  ->  routing  ->  CORS  ->  Authentication  ->  Authorization  ->  endpoints
+```
+
+Authentication must precede Authorization. Exception handling goes first so it wraps everything below it.
+
+## DI lifetimes
+
+| Lifetime | Instances | Use for |
+|---|---|---|
+| `Singleton` | one per app | stateless services, caches, `IHttpClientFactory` |
+| `Scoped` | one per request | `DbContext`, per-request state |
+| `Transient` | one per resolve | lightweight stateless helpers |
+
+**Captive dependency**: injecting a `Scoped` (or `Transient` holding scoped state) into a `Singleton` captures it for the app lifetime — a reused `DbContext` across requests corrupts change tracking. Inject `IServiceScopeFactory` and create a scope per unit of work instead, or make the consumer scoped. The DI container's scope validation catches many of these at startup in development.
+
+## Configuration / options pattern
+
+Bind config sections to typed options instead of reading magic strings:
+
+```csharp
+builder.Services.Configure<ShopOptions>(builder.Configuration.GetSection("Shop"));
+// inject IOptions<ShopOptions> (singleton snapshot) or IOptionsSnapshot<ShopOptions> (per-request reload)
+```
+
+Use `IOptionsSnapshot<T>` in scoped services when values can change at runtime; `IOptions<T>` otherwise.
+
+## Auth defaults
+
+ASP.NET Core 10 is secure-by-default. Still: configure authentication then authorization in the right middleware order, prefer policy-based authorization (`RequireAuthorization("policy")`) over scattered role checks, enforce HTTPS redirection + HSTS in production, and keep token/cookie protection on the Data Protection key ring (persisted and shared across instances). Threat modeling beyond these knobs is `secure-coding`.

package/skills/csharp-dotnet/references/async.md

@@ -0,0 +1,82 @@
+# async/await in .NET — full catalog
+
+The body has the rules; this is the depth. Read before any non-trivial async review.
+
+## Task vs ValueTask
+
+- Default to `Task`/`Task<T>`. It composes everywhere and is hard to misuse.
+- `ValueTask<T>` avoids an allocation when the method usually completes synchronously
+  (a cache hit, a buffered read). Constraints: **await it exactly once**, never block on
+  it, never store it. Convert with `.AsTask()` if you need to await twice or `WhenAll` it.
+
+```csharp
+// Good: hot path that is usually a cache hit
+public ValueTask<User> GetAsync(int id, CancellationToken ct) =>
+    _cache.TryGetValue(id, out var u) ? new ValueTask<User>(u) : new ValueTask<User>(LoadAsync(id, ct));
+```
+
+## ConfigureAwait
+
+- **Libraries**: `ConfigureAwait(false)` on every await. Why: do not capture and force a
+  resumption context onto callers; avoids deadlocks if a caller blocks.
+- **ASP.NET Core app code**: there is no `SynchronizationContext`, so `ConfigureAwait`
+  is a no-op — do not litter app code with it. The deadlock risk comes from *blocking*,
+  not from omitting `ConfigureAwait`.
+
+## CancellationToken propagation
+
+Flow one token from the entry point through every async call. Pass it last by convention.
+
+```csharp
+public async Task<Report> BuildAsync(int id, CancellationToken ct)
+{
+    var data = await _repo.LoadAsync(id, ct);          // DB
+    var enriched = await _http.GetAsync(data.Url, ct); // outbound HTTP
+    ct.ThrowIfCancellationRequested();                 // explicit check before expensive CPU work
+    return Render(enriched);
+}
+```
+
+`CancellationToken.None` is the explicit "this genuinely cannot be cancelled" signal —
+use it deliberately, never as a shortcut to avoid plumbing.
+
+## Deadlock catalog
+
+| Trigger | Mechanism | Fix |
+|---|---|---|
+| `.Result` / `.Wait()` blocking on async | Thread blocks waiting for a continuation that needs that thread (classic context deadlock) or starves the thread pool under load | `await` |
+| `Task.Run` to "make sync code async" then await | Burns a thread pool thread for I/O-bound work | Use a truly async API |
+| Sync-over-async deep in a call chain | One blocking call poisons the whole request | Make the whole chain async |
+
+The symptom users report: "my web request hangs / the app freezes under load." It is
+almost always a blocking call on an async method. Search for `.Result`, `.Wait(`,
+`.GetAwaiter().GetResult()`.
+
+## IAsyncEnumerable
+
+Stream rows instead of materializing a giant `List<T>`:
+
+```csharp
+public async IAsyncEnumerable<OrderRow> StreamAsync([EnumeratorCancellation] CancellationToken ct)
+{
+    await foreach (var o in _db.Orders.AsAsyncEnumerable().WithCancellation(ct))
+        yield return new OrderRow(o.Id, o.Total);
+}
+```
+
+`[EnumeratorCancellation]` lets `await foreach (... .WithCancellation(ct))` flow the token in.
+
+## Parallelism
+
+- **Independent awaits**: `await Task.WhenAll(a, b, c)` — runs concurrently, surfaces the
+  first exception (inspect `Task.Exception` for all).
+- **Bounded concurrency over a collection**: `Parallel.ForEachAsync` with
+  `MaxDegreeOfParallelism`. Do not fire 10k tasks at once.
+- **Producer/consumer pipelines**: `System.Threading.Channels` (`Channel<T>`).
+- **Synchronization** (C# 13+): use the `System.Threading.Lock` type instead of locking
+  on an arbitrary `object`; it has a clearer `EnterScope()` API and better diagnostics.
+
+```csharp
+private readonly System.Threading.Lock _gate = new();   // C# 13+
+public void Touch() { lock (_gate) { _count++; } }
+```

package/skills/csharp-dotnet/references/efcore.md

@@ -0,0 +1,96 @@
+# EF Core 10 — full catalog
+
+The body has the rules; this is the depth. Raw DB schema/index tuning is `postgresdb`.
+
+## DbContext lifetime
+
+- Register with `AddDbContext<T>` — **scoped** (one per request). It is not thread-safe.
+- Never share a `DbContext` across concurrent awaits or background threads. For parallel
+  work, create a context per unit via `IDbContextFactory<T>` (`AddDbContextFactory`).
+- For short-lived background jobs, resolve a fresh scope and a fresh context per job.
+
+```csharp
+builder.Services.AddDbContext<ShopDb>(o => o.UseNpgsql(cs));
+// parallel/background work:
+builder.Services.AddDbContextFactory<ShopDb>(o => o.UseNpgsql(cs));
+```
+
+## Query patterns
+
+```csharp
+// Read path: no tracking, project straight to a DTO (selects only needed columns).
+var rows = await db.Orders.AsNoTracking()
+    .Where(o => o.Status == OrderStatus.Open)
+    .Select(o => new OrderRow(o.Id, o.Customer.Name, o.Lines.Count))
+    .ToListAsync(ct);
+
+// Write path: tracked entity, mutate, SaveChangesAsync with the token.
+var order = await db.Orders.FindAsync([id], ct);
+order!.Status = OrderStatus.Closed;
+await db.SaveChangesAsync(ct);
+```
+
+- `AsNoTracking()` on every read-only query — drops change-tracking memory/CPU.
+- Use the async query operators (`ToListAsync`, `FirstOrDefaultAsync`, `AnyAsync`,
+  `SaveChangesAsync`) and flow the token into all of them.
+- Projection (`Select` to a DTO) is usually better than loading whole entities: less data
+  over the wire, no accidental over-fetch.
+
+## Tracking and N+1
+
+The N+1 trap: load a list, then touch a navigation property inside a loop — EF issues one
+extra query per row. Symptom: "my page does hundreds of tiny queries."
+
+```csharp
+// Bad: N+1
+var orders = await db.Orders.ToListAsync(ct);
+foreach (var o in orders) { var c = o.Customer.Name; } // one query per order
+
+// Good: projection (single JOIN) or Include
+var orders = await db.Orders.Include(o => o.Customer).ToListAsync(ct);
+```
+
+Use `AsSplitQuery()` when a single query with multiple collection `Include`s causes a
+cartesian-product explosion (rows multiply across joins). Trade-off: more round-trips,
+smaller result sets.
+
+## Migrations workflow
+
+```bash
+dotnet ef migrations add AddProductPrice -p Shop.Api
+# review the generated Up()/Down() — they are real code you ship
+dotnet ef database update -p Shop.Api
+dotnet ef migrations script --idempotent -o migrate.sql   # for controlled prod deploys
+```
+
+- Always review the generated migration before applying. EF guesses; you confirm.
+- Never hand-edit a migration that has already been applied to any shared environment —
+  add a new one.
+- For production, prefer an idempotent SQL script run by your deploy pipeline over
+  `database update` at app startup. Deploy mechanics are `deployment`.
+
+## EF Core 10 highlights
+
+- **Native `json` column type** — map a property to a real JSON column with first-class
+  querying, instead of serializing to a string manually.
+- **`vector` type + `VECTOR_DISTANCE()`** — store embeddings and run similarity search in
+  the database for RAG/semantic features (provider support required).
+- **`LeftJoin` / `RightJoin` LINQ operators** — express outer joins directly instead of
+  the old `GroupJoin` + `SelectMany` + `DefaultIfEmpty` dance.
+- **Named query filters** — multiple global query filters per entity, each named so you
+  can selectively disable one (e.g. ignore soft-delete but keep tenant filter) via
+  `IgnoreQueryFilters([...])`.
+
+## Raw SQL safety
+
+Use only parameterized interpolation — EF turns the holes into parameters:
+
+```csharp
+// Good: parameterized, injection-safe
+var products = await db.Products
+    .FromSql($"SELECT * FROM products WHERE name = {name}")   // {name} becomes a parameter
+    .ToListAsync(ct);
+```
+
+Never `FromSqlRaw($"... WHERE name = '{name}'")` with string interpolation/concatenation —
+that is SQL injection. Reserve raw SQL for cases LINQ cannot express; otherwise stay in LINQ.