rsc-universal 0.1.1

package/skills/cpp/references/move-and-templates.md

@@ -0,0 +1,130 @@
+# Move semantics, value categories, and modern generics
+
+## Value categories in one pass
+
+Every expression has a category that decides whether it can be *moved from*:
+
+- **lvalue** — has a name and a stable identity (`x`, `obj.field`, `*p`). Persists past the
+  expression. Binds to `T&` and `const T&`.
+- **prvalue** — a pure temporary with no name (`42`, `make()`, `a + b`). Binds to `T&&` and `const T&`.
+- **xvalue** — an "expiring" lvalue you've cast with `std::move(x)`; its resources may be stolen.
+
+`std::move` is just `static_cast<T&&>` — it *moves nothing*, it only relabels an lvalue as
+movable so an overload that steals (the move ctor/assign) is selected. After a move the source is in
+a **valid but unspecified** state: assigning to it or destroying it is fine; reading it is a bug.
+
+## Rule of Zero vs Rule of Five
+
+Prefer **Rule of Zero**: hold resources in members that already manage themselves (`std::string`,
+`std::vector`, `std::unique_ptr`) and declare *none* of the five special members. The compiler
+generates correct copy/move/destroy for free.
+
+Write the five **only** when you manage a raw resource by hand — and treat that as a smell first
+(could a `unique_ptr` with a custom deleter do it?). The Rule of Five: if you declare any one of
+destructor / copy-ctor / copy-assign / move-ctor / move-assign, declare (or `= default`/`= delete`)
+all five, because declaring one suppresses others.
+
+```cpp
+// Rule of Five for a hand-managed buffer. Note: every move op is noexcept.
+class Buffer {
+public:
+    explicit Buffer(std::size_t n) : data_(new int[n]), size_(n) {}
+    ~Buffer() { delete[] data_; }
+
+    Buffer(const Buffer& o) : data_(new int[o.size_]), size_(o.size_) {
+        std::copy(o.data_, o.data_ + size_, data_);
+    }
+    Buffer& operator=(const Buffer& o) {              // copy-and-swap: strong guarantee, self-safe
+        Buffer tmp(o);
+        swap(tmp);
+        return *this;
+    }
+    Buffer(Buffer&& o) noexcept                       // steal, leave o empty-but-valid
+        : data_(std::exchange(o.data_, nullptr)), size_(std::exchange(o.size_, 0)) {}
+    Buffer& operator=(Buffer&& o) noexcept { Buffer tmp(std::move(o)); swap(tmp); return *this; }
+
+    void swap(Buffer& o) noexcept { std::swap(data_, o.data_); std::swap(size_, o.size_); }
+private:
+    int* data_{};
+    std::size_t size_{};
+};
+```
+
+The equivalent Rule-of-Zero version is shorter and harder to get wrong:
+
+```cpp
+class Buffer {
+public:
+    explicit Buffer(std::size_t n) : data_(n) {}
+private:
+    std::vector<int> data_;   // vector is the five special members, done correctly
+};
+```
+
+## noexcept on moves — why it's load-bearing
+
+`std::vector` reallocation uses `move_if_noexcept`: it only *moves* its elements into the new buffer
+when the element's move constructor is `noexcept`; otherwise it falls back to *copying* to preserve
+the strong exception guarantee. A non-`noexcept` move ctor therefore silently turns every vector
+growth into a deep copy. Mark move operations `noexcept` whenever they can't throw (stealing
+pointers never throws).
+
+## RVO and copy elision — don't fight it
+
+```cpp
+// Good: the local is constructed directly in the caller's slot. No copy, no move.
+Widget make() { Widget w; configure(w); return w; }
+
+// Bad: std::move blocks NRVO and forces an actual move that elision would have removed.
+Widget make() { Widget w; return std::move(w); }   // pessimization — drop the std::move
+```
+
+Return local objects by value, plainly. Only `std::move` a *member* or *parameter* out of a function
+(those aren't elision candidates).
+
+## Perfect forwarding
+
+In a function template, `T&&` is a **forwarding reference** (it binds to lvalues *and* rvalues and
+preserves which it was). Pass it on with `std::forward<T>` so an rvalue argument stays movable and an
+lvalue stays an lvalue:
+
+```cpp
+template <class T, class... Args>
+std::unique_ptr<T> make(Args&&... args) {
+    return std::unique_ptr<T>(new T(std::forward<Args>(args)...));  // category preserved
+}
+```
+
+Use `std::forward` *only* with a deduced `T&&`. Inside a normal function, a parameter declared `T&&`
+where `T` is concrete is an rvalue reference, not forwarding — `std::move` it, don't `std::forward`.
+
+## CTAD and C++20 concepts
+
+Class Template Argument Deduction lets you omit template args when the constructor implies them:
+
+```cpp
+std::lock_guard lg(mtx);          // deduces std::lock_guard<std::mutex>
+std::vector v{1, 2, 3};           // deduces std::vector<int>
+std::pair p{1, "x"};              // std::pair<int, const char*>
+```
+
+C++20 **concepts** constrain templates so errors fire at the call site with a readable message
+instead of deep inside instantiation, and they document intent:
+
+```cpp
+#include <concepts>
+
+template <std::integral T>                          // only integers
+T gcd(T a, T b) { return b == 0 ? a : gcd(b, a % b); }
+
+template <class T>
+concept Drawable = requires(const T& t) {           // a custom concept
+    { t.draw() } -> std::same_as<void>;
+};
+
+void render(const Drawable auto& shape) { shape.draw(); }   // constrained abbreviated template
+```
+
+Prefer a concept over `enable_if`/SFINAE for new code: same constraint power, vastly better
+diagnostics, and it reads like a type. Combine concepts with `&&`/`||`, and use `requires` clauses
+for ad-hoc constraints the named concepts don't cover.

package/skills/cpp/references/undefined-behavior.md

@@ -0,0 +1,86 @@
+# Undefined behavior — catalog, sanitizers, fixes
+
+UB is not "an error at runtime." The standard says the program has *no defined meaning*, which
+licenses the optimizer to assume the situation never happens and rewrite code on that basis. That
+is why UB produces distant, nonsensical crashes and "works in Debug, breaks in Release." You do not
+debug UB by reasoning about what the CPU *did*; you remove it by construction and prove its absence
+with sanitizers.
+
+Static analysis (clang-tidy, cppcheck) and dynamic sanitizers catch **disjoint** bug classes — run
+both. Sanitizers only see the paths your tests exercise, so coverage matters.
+
+## The catalog
+
+| Class | What it is | Caught by | Fix |
+| --- | --- | --- | --- |
+| Lifetime / dangling | reference or pointer to a destroyed object (returned local, dangling iterator after `push_back`, view outliving its owner) | ASan (heap/stack-use-after-scope) | return by value; own with `unique_ptr`; never store a `string_view`/`span` past its backing's lifetime |
+| Use-after-move | reading an object after `std::move` (valid but unspecified state) | clang-tidy (`bugprone-use-after-move`) — **not** ASan | reassign before reading, or don't read it |
+| Out-of-bounds | index/iterator past the end of a container or array | ASan | `.at()` or a bounds-checked view; range-for / ranges; never trust an external index |
+| Signed integer overflow | `INT_MAX + 1`, etc. (UB; unsigned wraps, signed does not) | UBSan | use a wider type, check before, or `<numeric>`/`ckd_add` (C++26) overflow-checked ops |
+| Strict aliasing | reading an object through an unrelated pointer type | UBSan (partial); compiler `-Wstrict-aliasing` | `std::bit_cast` (C++20) or `memcpy`, never a reinterpret_cast pun |
+| Uninitialized read | reading a variable before assigning it | UBSan (MemorySanitizer for full coverage) | always initialize (`int n{};`); enable `-Wuninitialized` |
+| Data race | two threads access the same memory, one writes, no synchronization | TSan | a mutex/`scoped_lock`, `atomic<T>`, or don't share mutable state |
+| Null / misaligned deref | dereferencing `nullptr` or a misaligned pointer | UBSan | check before deref; references can't be null — prefer them |
+| Invalid downcast / enum | `static_cast` to the wrong dynamic type; out-of-range enum value | UBSan (`vptr`, `enum`) | `dynamic_cast` when polymorphic; validate enum inputs |
+
+## Sanitizer flag combinations & caveats
+
+- **ASan + UBSan together:** `-fsanitize=address,undefined -fno-omit-frame-pointer -g`. This is the
+  everyday build for tests and the local gate. Add `-fsanitize=integer` (Clang) to extend UBSan to
+  unsigned wraparound you care about.
+- **TSan alone:** `-fsanitize=thread -g`. It is **incompatible** with ASan — never combine them. Run
+  it as a separate build/CI job over your concurrent tests.
+- **MemorySanitizer** (Clang) for uninitialized reads needs *all* code (including libc++)
+  instrumented; usually overkill — `-Wuninitialized` + always-initialize covers most cases.
+- Sanitizers slow execution ~2–10x and need `-g` and frame pointers for readable stacks. They are a
+  test/CI tool, not a production build.
+- Tune at runtime via env: `ASAN_OPTIONS=detect_leaks=1:abort_on_error=1`,
+  `UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1`.
+
+## Worked fixes
+
+```cpp
+// Dangling reference (ASan: stack-use-after-return).
+const std::string& bad() { std::string s = make(); return s; }   // s dies at the brace
+std::string good() { return make(); }                            // by value; RVO elides the copy
+
+// Iterator invalidation (ASan: heap-use-after-free).
+for (auto it = v.begin(); it != v.end(); ++it)
+    if (*it == x) v.push_back(*it);            // Bad: push_back may realloc, it now dangles
+auto n = std::ranges::count(v, x);             // Good: compute first, then mutate
+
+// Signed overflow (UBSan: signed-integer-overflow).
+int total = a + b;                             // Bad if a+b > INT_MAX
+auto total = std::int64_t{a} + b;              // Good: widen before the add
+
+// Strict aliasing (type pun).
+float f = *reinterpret_cast<float*>(&i);       // Bad: UB
+auto f = std::bit_cast<float>(i);              // Good: C++20, defined
+```
+
+## Reading an ASan report
+
+A typical use-after-free report has three stacks — read them bottom-up by *event*:
+
+```
+==12345==ERROR: AddressSanitizer: heap-use-after-free on address 0x602...
+READ of size 4 at 0x602... thread T0
+    #0 0x... in Cache::get(int) src/cache.cpp:42      <- where the bad access happened
+    ...
+0x602... is located 0 bytes inside of 4-byte region [0x602..,0x602..)
+freed by thread T0 here:                              <- who freed it (the delete/dtor)
+    #0 0x... operator delete(void*)
+    #1 0x... in Cache::evict(int) src/cache.cpp:31
+previously allocated by thread T0 here:               <- who allocated it
+    #0 0x... operator new(unsigned long)
+    #1 0x... in Cache::put(int,int) src/cache.cpp:18
+```
+
+Procedure: (1) the top READ/WRITE frame is the *symptom* line; (2) "freed by" is the line that ended
+the object's life too early; (3) "previously allocated" is its birth. The bug is almost always that
+the "freed by" path runs while a pointer/reference/iterator captured between allocation and the
+symptom is still in use. The fix is an ownership fix — usually replacing the raw owning pointer with
+a `unique_ptr`/`shared_ptr` so the lifetime can't be cut short, or extending the owner's scope.
+
+For data races, TSan prints the two conflicting accesses (read/write) with both stacks and the thread
+that created each; the fix is a single mutex/`scoped_lock` or an `atomic<T>` guarding that memory.

package/skills/cpp/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a CMake C++ project (superset of CI).
+#
+# Usage:
+#   cd <your-project-root>   # the directory containing CMakeLists.txt
+#   ./verify.sh
+#
+# Runs: clang-format (dry-run), a CMake configure+build with warnings-as-errors and
+# ASan+UBSan, the test target via ctest, and optional clang-tidy + cppcheck.
+# Tools that are not installed are skipped with a yellow warning (not a failure).
+# Real problems (format drift, build failure, sanitizer abort, test failure) exit non-zero.
+# Read-only: never mutates your source. Only writes under build/verify/.
+#
+# Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays,
+# no unguarded array expansions under `set -u`).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+BUILD_DIR="build/verify"
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# Must run from a CMake project root.
+if [ ! -f CMakeLists.txt ]; then
+  printf '%serror:%s no CMakeLists.txt in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Collect tracked C/C++ sources (git if available, else find). Read-only.
+collect_sources() {
+  if have git && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    git ls-files '*.cpp' '*.cc' '*.cxx' '*.hpp' '*.hh' '*.hxx' '*.h' '*.ixx' 2>/dev/null
+  else
+    find . -path ./"$BUILD_DIR" -prune -o -type f \
+      \( -name '*.cpp' -o -name '*.cc' -o -name '*.cxx' \
+         -o -name '*.hpp' -o -name '*.hh' -o -name '*.hxx' \
+         -o -name '*.h' -o -name '*.ixx' \) -print 2>/dev/null
+  fi
+}
+
+# 1. clang-format - dry-run, never rewrites. Empty source set is a clean pass.
+info "clang-format"
+if have clang-format; then
+  srcs="$(collect_sources)"
+  if [ -z "$srcs" ]; then
+    ok "no C/C++ sources to format"
+  else
+    fmt_failed=0
+    # -Werror + --dry-run makes clang-format exit non-zero on any drift, printing nothing else.
+    printf '%s\n' "$srcs" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      clang-format --dry-run -Werror "$f" >/dev/null 2>&1 || printf '%s\n' "$f"
+    done > "${TMPDIR:-/tmp}/cpp_verify_fmt.$$" || true
+    if [ -s "${TMPDIR:-/tmp}/cpp_verify_fmt.$$" ]; then
+      fmt_failed=1
+      fail "files need formatting (run: clang-format -i <file>):"
+      cat "${TMPDIR:-/tmp}/cpp_verify_fmt.$$"
+    fi
+    rm -f "${TMPDIR:-/tmp}/cpp_verify_fmt.$$"
+    [ "$fmt_failed" -eq 0 ] && ok "clang-format clean"
+  fi
+else
+  warn "clang-format not found (https://clang.llvm.org/docs/ClangFormat.html)"
+fi
+
+# 2-4. CMake configure + build under warnings-as-errors + ASan+UBSan, then ctest.
+info "cmake configure (ASan+UBSan, warnings-as-errors)"
+if have cmake; then
+  SAN_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g -Werror"
+  if cmake -S . -B "$BUILD_DIR" \
+       -DCMAKE_BUILD_TYPE=Debug \
+       -DCMAKE_CXX_FLAGS="$SAN_FLAGS" \
+       -DCMAKE_EXPORT_COMPILE_COMMANDS=ON >/dev/null 2>&1; then
+    ok "configured ($BUILD_DIR)"
+
+    info "cmake build"
+    if cmake --build "$BUILD_DIR" >/dev/null 2>&1; then
+      ok "build clean (warnings-as-errors)"
+
+      info "ctest"
+      if have ctest; then
+        # ctest exits non-zero with "No tests were found" when there are none; treat that as a skip.
+        ctest_out="$(ctest --test-dir "$BUILD_DIR" --output-on-failure 2>&1 || true)"
+        if printf '%s' "$ctest_out" | grep -qi 'no tests were found'; then
+          warn "no tests registered with ctest"
+        elif printf '%s' "$ctest_out" | grep -qiE 'tests failed|failed out of|errors? while'; then
+          fail "ctest reported failures"
+          printf '%s\n' "$ctest_out"
+        else
+          ok "tests pass (ASan+UBSan)"
+        fi
+      else
+        warn "ctest not found (ships with CMake)"
+      fi
+    else
+      fail "build failed (warnings-as-errors / sanitizer compile error)"
+    fi
+  else
+    fail "cmake configure failed"
+  fi
+else
+  warn "cmake not found - cannot build/test (https://cmake.org/download/)"
+fi
+
+# 5. clang-tidy - optional; reads compile_commands.json from the build dir.
+info "clang-tidy"
+if have clang-tidy && [ -f "$BUILD_DIR/compile_commands.json" ]; then
+  srcs="$(collect_sources | grep -E '\.(cpp|cc|cxx)$' || true)"
+  if [ -z "$srcs" ]; then
+    warn "no translation units for clang-tidy"
+  else
+    tidy_failed=0
+    printf '%s\n' "$srcs" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      clang-tidy -p "$BUILD_DIR" "$f" >/dev/null 2>&1 || printf '%s\n' "$f"
+    done > "${TMPDIR:-/tmp}/cpp_verify_tidy.$$" || true
+    if [ -s "${TMPDIR:-/tmp}/cpp_verify_tidy.$$" ]; then
+      tidy_failed=1
+      fail "clang-tidy reported issues in:"
+      cat "${TMPDIR:-/tmp}/cpp_verify_tidy.$$"
+    fi
+    rm -f "${TMPDIR:-/tmp}/cpp_verify_tidy.$$"
+    [ "$tidy_failed" -eq 0 ] && ok "clang-tidy clean"
+  fi
+else
+  warn "clang-tidy not found or no compile_commands.json (optional)"
+fi
+
+# 6. cppcheck - optional static analysis.
+info "cppcheck"
+if have cppcheck; then
+  if [ -f "$BUILD_DIR/compile_commands.json" ]; then
+    if cppcheck --enable=warning,performance --error-exitcode=1 \
+         --project="$BUILD_DIR/compile_commands.json" >/dev/null 2>&1; then
+      ok "cppcheck clean"
+    else
+      fail "cppcheck reported issues"
+    fi
+  else
+    warn "cppcheck: no compile_commands.json to analyze"
+  fi
+else
+  warn "cppcheck not found (optional)"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/csharp-dotnet/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: csharp-dotnet
+description: "Use when writing, reviewing, testing, or shipping C# / .NET code, ASP.NET Core APIs, or EF Core data access — editing .cs/.csproj/.sln files, designing minimal APIs vs controllers, fixing async correctness, or structuring a dotnet solution. Triggers: 'build a .NET API', 'is this idiomatic C#', 'should this DTO be a record', 'my endpoint hangs/deadlocks under load' (sync-over-async), 'EF query hits the DB once per row' (N+1), 'set up xUnit + WebApplicationFactory', 'crea una API en .NET', 'revisa este código C# antes de hacer deploy'. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs)."
+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 to use
+
+- Authoring/reviewing/refactoring any `.cs`, `.csproj`, or `.sln`.
+- ASP.NET Core: minimal APIs vs controllers, route groups, endpoint filters,
+  validation, ProblemDetails, OpenAPI.
+- EF Core: `DbContext` design, LINQ queries, migrations, tracking, N+1.
+- async/await correctness: `CancellationToken` plumbing, `async void`, deadlocks,
+  `IAsyncEnumerable`, `ValueTask`.
+- `dotnet` CLI workflow, solution layout, NuGet, central package management.
+- Idiom review: records, pattern matching, nullable reference types (NRT).
+
+## 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`. Only `secure-coding`, `postgresdb`, `deployment`, and `harness` exist on
+disk as siblings, so only those are linked as `../<id>/SKILL.md`.
+
+## Decision rules — apply on every C# edit
+
+1. **NRT on.** `<Nullable>enable</Nullable>` in the csproj. Why: the compiler turns
+   whole classes of `NullReferenceException` into build-time warnings. Never disable it
+   to silence a warning — fix the nullability.
+2. **Async all the way, flow the token.** I/O methods are `async Task`, every call is
+   `await`ed, and a `CancellationToken` threads from the endpoint down to
+   `SaveChangesAsync`/queries/HTTP calls. Why: a dropped token means requests keep
+   running after the client gives up.
+3. **Records for DTOs and immutable data.** `public record ProductDto(int Id, string Name);`.
+   Why: value equality + `with` expressions + concise; never reuse an EF entity as the
+   wire DTO (see anti-patterns).
+4. **Parameterize every query.** EF LINQ and `FromSql` interpolation parameterize for
+   you; never string-concatenate SQL. Why: SQL injection.
+5. **Deterministic disposal.** `using`/`await using` (or `using` declarations) for
+   anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections/handles.
+6. **One `DbContext` per request (scoped).** Why: `DbContext` is not thread-safe;
+   sharing across requests corrupts change tracking.
+7. **Minimal APIs for new services** unless you need MVC features (views, model
+   binders, action filters at scale). Why: less ceremony, first-class in .NET 10.
+
+## 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.
+
+## 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);
+```
+
+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.
+
+## 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 into every async call.
+- **`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.
+
+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), `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.
+- **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.