diff --git a/.claude/agents/dotnet-developer.md b/.claude/agents/dotnet-developer.md
index 08f9656..fe21dee 100644
--- a/.claude/agents/dotnet-developer.md
+++ b/.claude/agents/dotnet-developer.md
@@ -17,11 +17,11 @@ Use the following skills based on the task at hand:
 
 | Area | Skill | Description |
 |------|-------|-------------|
-| Web & REST APIs | [dotnet-aspnet](../../skills/csharp/dotnet-aspnet/SKILL.md) | ASP.NET Core controllers, minimal APIs, middleware, auth, and API conventions |
-| SDK & Library Development | [dotnet-sdk-builder](../../skills/csharp/dotnet-sdk-builder/SKILL.md) | Generate .NET SDK libraries with DI support, typed HTTP clients, and Options pattern |
-| Testing | [dotnet-tester](../../skills/csharp/dotnet-tester/SKILL.md) | Write and execute unit tests using xUnit, FakeItEasy, and AwesomeAssertions |
-| Data Access | [ef-core](../../skills/csharp/ef-core/SKILL.md) | Entity Framework Core best practices, DbContext design, migrations, and queries |
-| Package Management | [nuget-manager](../../skills/csharp/nuget-manager/SKILL.md) | Add, remove, and update NuGet packages via dotnet CLI |
-| Documentation | [csharp-docs](../../skills/csharp/csharp-docs/SKILL.md) | C# XML documentation comments following Microsoft standards |
-| Code Review | [code-review](../../skills/general/code-review/SKILL.md) | Structured code reviews covering quality, security, and performance |
-| Refactoring | [refactoring](../../skills/general/refactoring/SKILL.md) | Improve code structure and maintainability without changing behavior |
+| Web & REST APIs | `dotnet-aspnet` | ASP.NET Core controllers, minimal APIs, middleware, auth, and API conventions |
+| SDK & Library Development | `dotnet-sdk-builder` | Generate .NET SDK libraries with DI support, typed HTTP clients, and Options pattern |
+| Testing | `dotnet-tester` | Write and execute unit tests using xUnit, FakeItEasy, and AwesomeAssertions |
+| Data Access | `dotnet-ef-core` | Entity Framework Core best practices, DbContext design, migrations, and queries |
+| Package Management | `dotnet-nuget-manager` | Add, remove, and update NuGet packages via dotnet CLI |
+| Documentation | `dotnet-xmldocs` | C# XML documentation comments following Microsoft standards |
+| Code Review | `code-review` | Structured code reviews covering quality, security, and performance |
+| Refactoring | `refactoring` | Improve code structure and maintainability without changing behavior |
diff --git a/.claude/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md b/.claude/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md
new file mode 100644
index 0000000..5963161
--- /dev/null
+++ b/.claude/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md
@@ -0,0 +1,173 @@
+# Azure DevOps Markdown Guidance
+
+This reference describes Markdown syntax supported by Azure DevOps features including Wiki pages, README files, dashboards, and pull requests.
+
+## Supported Features
+
+| Markdown type | Definition of Done | Widget | Pull Requests | README | Wiki |
+|---|---|---|---|---|---|
+| Headings | Yes | Yes | Yes | Yes | Yes |
+| Paragraphs/line breaks | Yes | Yes | Yes | Yes | Yes |
+| Blockquotes | Yes | Yes | Yes | Yes | Yes |
+| Horizontal rules | Yes | Yes | Yes | Yes | Yes |
+| Emphasis (bold, italic) | Yes | Yes | Yes | Yes | Yes |
+| Tables | No | Yes | Yes | Yes | Yes |
+| Lists (ordered, unordered) | Yes | Yes | Yes | Yes | Yes |
+| Links | Yes | Yes | Yes | Yes | Yes |
+| Images | No | Yes | Yes | Yes | Yes |
+| Code highlighting | No | Yes | Yes | Yes | Yes |
+| Math notation | No | No | Yes | Yes | Yes |
+| Checklists/task lists | No | No | Yes | Yes | Yes |
+| Mermaid diagrams | No | No | No | No | Yes |
+
+> **Note:** Markdown in Azure DevOps doesn't support JavaScript or iframes.
+
+## Headings
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
+##### Heading 5
+###### Heading 6
+```
+
+## Paragraphs and Line Breaks
+
+Use a blank line for new paragraphs. Use two spaces at line end or `<br/>` for line breaks within a paragraph.
+
+## Blockquotes
+
+```markdown
+> Single blockquote
+>> Nested blockquote
+```
+
+## Horizontal Rules
+
+Use three or more hyphens, asterisks, or underscores on a line by themselves.
+
+## Emphasis
+
+```markdown
+*Italic* or _Italic_
+**Bold** or __Bold__
+***Bold italic***
+~~Strikethrough~~
+```
+
+## Code Highlighting
+
+**Inline:** Use single backticks `` `code` ``
+
+**Block:** Use triple backticks with optional language identifier:
+
+````markdown
+```javascript
+const x = 1;
+```
+````
+
+Supported languages include: ActionScript, Apex, Bash, C, C#, C++, CSS, Dart, Go, Groovy, Haskell, HTML, Java, JavaScript, JSON, Kotlin, Lua, Markdown, Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Shell, SQL, Swift, TypeScript, XML, YAML, and more.
+
+## Tables
+
+```markdown
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+```
+
+Alignment with colons: `:---` (left), `:---:` (center), `---:` (right).
+
+## Lists
+
+**Ordered:**
+
+```markdown
+1. First item
+2. Second item
+```
+
+**Unordered:**
+
+```markdown
+- Item 1
+- Item 2
+```
+
+**Nested:** Indent with spaces.
+
+## Links
+
+```markdown
+[Link text](URL)
+[Link text](URL "Title")
+```
+
+**Anchor links:** Link to headings within the same page using `#section-name`.
+
+## Images
+
+```markdown
+![Alt text](image-url)
+![Alt text](image-url =WIDTHxHEIGHT)
+```
+
+Azure DevOps supports image resizing with `=WIDTHxHEIGHT` syntax.
+
+## Checklists / Task Lists
+
+```markdown
+- [ ] Incomplete task
+- [x] Completed task
+```
+
+## Mathematical Notation
+
+**Inline:** `$` delimiters: `$e^{i\pi} = -1$`
+
+**Block:** `$$` delimiters:
+
+```markdown
+$$
+\sum_{i=1}^{n} x_i
+$$
+```
+
+Uses KaTeX for rendering.
+
+## Mermaid Diagrams (Wiki only)
+
+````markdown
+```mermaid
+graph TD;
+    A-->B;
+    B-->C;
+```
+````
+
+Supports: flowcharts, sequence diagrams, Gantt charts, and more.
+
+## Collapsible Sections
+
+```html
+<details>
+  <summary>Click to expand</summary>
+
+  Content here (leave blank line after summary tag).
+</details>
+```
+
+## Emoji
+
+Use standard emoji shortcodes: `:smile:`, `:thumbsup:`, etc.
+
+## Special Characters
+
+Escape special Markdown characters with backslash: `\*`, `\#`, `\[`, etc.
+
+## HTML Tags
+
+Supported HTML tags in Wiki include: `<div>`, `<span>`, `<img>`, `<br>`, `<table>`, `<tr>`, `<td>`, `<th>`, `<strong>`, `<em>`, `<code>`, `<pre>`, `<blockquote>`, `<ul>`, `<ol>`, `<li>`, `<h1>`-`<h6>`, `<hr>`, `<p>`, `<a>`, `<details>`, `<summary>`, `<video>`, `<audio>`.
diff --git a/.claude/skills/convert-plaintext-to-md/references/considerations.md b/.claude/skills/convert-plaintext-to-md/references/considerations.md
index c8f77e1..5e053ed 100644
--- a/.claude/skills/convert-plaintext-to-md/references/considerations.md
+++ b/.claude/skills/convert-plaintext-to-md/references/considerations.md
@@ -35,6 +35,6 @@ When converting documentation, do **not** halt the conversion when the text docu
 
 When in doubt, consult these resources for markdown best practices:
 
-- [GitHub Basic Writing and Formatting Syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
-- [Markdown Extended Syntax](https://www.markdownguide.org/extended-syntax/)
-- [Azure DevOps Markdown Guidance](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops)
+- [GitHub Basic Writing and Formatting Syntax](./github-basic-formatting.md)
+- [Markdown Extended Syntax](./markdown-extended-syntax.md)
+- [Azure DevOps Markdown Guidance](./azure-devops-markdown-guidance.md)
diff --git a/.claude/skills/convert-plaintext-to-md/references/github-basic-formatting.md b/.claude/skills/convert-plaintext-to-md/references/github-basic-formatting.md
new file mode 100644
index 0000000..efaa03b
--- /dev/null
+++ b/.claude/skills/convert-plaintext-to-md/references/github-basic-formatting.md
@@ -0,0 +1,153 @@
+# GitHub Basic Writing and Formatting Syntax Reference
+
+## Headings
+
+Create hierarchy using 1-6 hash symbols. GitHub automatically generates a table of contents when you use multiple headings.
+
+```markdown
+# First-level heading
+## Second-level heading
+### Third-level heading
+```
+
+## Text Styling
+
+| Style | Syntax | Example |
+|-------|--------|---------|
+| Bold | `** **` or `__ __` | `**bold text**` |
+| Italic | `* *` or `_ _` | `*italicized text*` |
+| Strikethrough | `~~ ~~` | `~~mistaken text~~` |
+| Bold & italic | `** **` and `_ _` | `**_extremely_ important**` |
+| Subscript | `<sub> </sub>` | `<sub>subscript</sub>` |
+| Superscript | `<sup> </sup>` | `<sup>superscript</sup>` |
+| Underline | `<ins> </ins>` | `<ins>underlined</ins>` |
+
+## Quoting Text
+
+Use `>` to create block quotes:
+
+```markdown
+> Text that is a quote
+```
+
+## Code Formatting
+
+**Inline code:** Use single backticks for code within sentences:
+
+```markdown
+Use `git status` to list changes.
+```
+
+**Code blocks:** Use triple backticks for standalone code:
+
+````markdown
+```
+git status
+git add
+git commit
+```
+````
+
+## Color Support
+
+Display colors using supported models within backticks:
+
+- Hex: `` `#0969DA` ``
+- RGB: `` `rgb(9, 105, 218)` ``
+- HSL: `` `hsl(212, 92%, 45%)` ``
+
+## Links
+
+Wrap link text in brackets and URL in parentheses:
+
+```markdown
+[Link text](https://example.com)
+```
+
+**Section links:** Link directly to any heading using its anchor.
+
+**Relative links:** Use paths relative to current file:
+
+```markdown
+[Contribution guidelines](docs/CONTRIBUTING.md)
+```
+
+## Images
+
+Include images using exclamation mark, alt text in brackets, and URL in parentheses:
+
+```markdown
+![Alt text](image-url.png)
+```
+
+The `<picture>` HTML element is supported for theme-adaptive images.
+
+## Lists
+
+**Unordered lists:** Use `-`, `*`, or `+`
+
+**Ordered lists:** Use numbers followed by periods
+
+**Nested lists:** Indent items under parent items using spaces or tabs
+
+## Task Lists
+
+Create checkboxes with `[ ]` for incomplete and `[x]` for complete tasks:
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+```
+
+## Mentions & References
+
+- **Mention people/teams:** `@username` or `@organization/team-name`
+- **Reference issues:** `#` followed by issue number or title
+
+## Emojis
+
+Use `:EMOJICODE:` format: `:+1:`, `:shipit:`
+
+## Paragraphs & Line Breaks
+
+Create paragraphs by leaving blank lines between text. For line breaks:
+
+- Two trailing spaces at line end
+- Backslash `\` at line end
+- HTML `<br/>`
+
+## Footnotes
+
+```markdown
+Here is a footnote[^1].
+
+[^1]: Footnote content here.
+```
+
+Footnotes render at document bottom regardless of placement.
+
+## Alerts
+
+Five alert types emphasize critical information:
+
+```markdown
+> [!NOTE]
+> Essential information users should know.
+
+> [!TIP]
+> Helpful advice for better outcomes.
+
+> [!IMPORTANT]
+> Key information for success.
+
+> [!WARNING]
+> Urgent information requiring immediate attention.
+
+> [!CAUTION]
+> Warns about risks and negative outcomes.
+```
+
+## Special Features
+
+- **HTML comments:** `<!-- Hidden content -->`
+- **Escape formatting:** Backslash before markdown characters: `\*not italicized\*`
diff --git a/.claude/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md b/.claude/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md
new file mode 100644
index 0000000..bbc1ab0
--- /dev/null
+++ b/.claude/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md
@@ -0,0 +1,133 @@
+# Markdown Extended Syntax Reference
+
+The extended syntax builds upon basic Markdown by adding advanced features. Not all Markdown applications support extended syntax — check your application's documentation to confirm compatibility.
+
+## Tables
+
+Create tables using pipes (`|`) and hyphens (`---`):
+
+```markdown
+| Syntax      | Description |
+| ----------- | ----------- |
+| Header      | Title       |
+| Paragraph   | Text        |
+```
+
+### Alignment
+
+Add colons to align columns:
+
+- Left: `:---`
+- Center: `:---:`
+- Right: `---:`
+
+### Formatting in Tables
+
+Supported: links, code (backticks only), emphasis.
+Not supported: headings, blockquotes, lists, horizontal rules, images.
+
+### Escaping Pipes
+
+Use HTML entity `&#124;` to display pipe characters.
+
+## Fenced Code Blocks
+
+Use triple backticks or tildes without indentation:
+
+````markdown
+```json
+{
+  "example": "value"
+}
+```
+````
+
+Specify language after opening backticks for syntax highlighting.
+
+## Footnotes
+
+```markdown
+Text here.[^1]
+
+[^1]: This is the footnote.
+```
+
+## Heading IDs
+
+Add custom IDs to headings:
+
+```markdown
+### Heading {#custom-id}
+```
+
+Link to IDs with `[Link text](#custom-id)`.
+
+## Definition Lists
+
+```markdown
+Term
+: Definition of the term.
+```
+
+## Strikethrough
+
+Use double tildes:
+
+```markdown
+~~Strikethrough text~~
+```
+
+## Task Lists
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+```
+
+## Emoji
+
+### Direct Copy-Paste
+
+Paste emoji directly from sources like Emojipedia.
+
+### Shortcodes
+
+```markdown
+Gone camping! :tent: Be back soon.
+```
+
+## Highlight
+
+```markdown
+==Important words==
+```
+
+Or use HTML: `<mark>text</mark>`
+
+## Subscript
+
+```markdown
+H~2~O
+```
+
+Or HTML: `H<sub>2</sub>O`
+
+## Superscript
+
+```markdown
+X^2^
+```
+
+Or HTML: `X<sup>2</sup>`
+
+## Automatic URL Linking
+
+Most processors auto-link URLs. Disable by wrapping in backticks:
+
+```markdown
+`http://www.example.com`
+```
+
+---
+
+> **Note:** Support varies significantly across applications. Always test extended syntax features in your specific Markdown processor.
diff --git a/.claude/skills/create-readme/SKILL.md b/.claude/skills/create-readme/SKILL.md
index 81cc12b..acff6c8 100644
--- a/.claude/skills/create-readme/SKILL.md
+++ b/.claude/skills/create-readme/SKILL.md
@@ -7,11 +7,11 @@ description: Creates a comprehensive, professional README.md for a project. Use
 
 1. Review the entire project and workspace, then create a well-structured README.md.
 2. Take inspiration from these readme files for structure, tone, and content:
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-chat-langchainjs/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-recipes-javascript/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/run-on-output/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/smoke/refs/heads/main/README.md
+   - [serverless-chat-langchainjs](./references/serverless-chat-langchainjs-readme.md)
+   - [serverless-recipes-javascript](./references/serverless-recipes-javascript-readme.md)
+   - [run-on-output](./references/run-on-output-readme.md)
+   - [smoke](./references/smoke-readme.md)
 3. Do not overuse emojis, and keep the readme concise and to the point.
 4. Do not include sections like "LICENSE", "CONTRIBUTING", "CHANGELOG", etc. There are dedicated files for those sections.
-5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (https://github.com/orgs/community/discussions/16925) where appropriate.
+5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (see [reference](./references/github-admonition-syntax.md)) where appropriate.
 6. If you find a logo or icon for the project, use it in the readme's header.
diff --git a/.claude/skills/create-readme/references/github-admonition-syntax.md b/.claude/skills/create-readme/references/github-admonition-syntax.md
new file mode 100644
index 0000000..324df13
--- /dev/null
+++ b/.claude/skills/create-readme/references/github-admonition-syntax.md
@@ -0,0 +1,60 @@
+# GitHub Markdown Alerts (Admonition Syntax)
+
+GitHub supports a markdown extension for creating highlighted alert blocks using blockquote syntax. This feature helps emphasize critical information in documentation with distinctive colors and icons.
+
+## Syntax
+
+The basic syntax uses blockquote markers (`>`) with a bracket notation:
+
+```markdown
+> [!TYPE]
+> Your alert content here
+```
+
+## Supported Alert Types
+
+### NOTE
+
+```markdown
+> [!NOTE]
+> Highlights information users should consider, even when skimming.
+```
+
+### TIP
+
+```markdown
+> [!TIP]
+> Optional information to help users be more successful.
+```
+
+### IMPORTANT
+
+```markdown
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+```
+
+### WARNING
+
+```markdown
+> [!WARNING]
+> Critical content demanding immediate attention due to potential risks.
+```
+
+### CAUTION
+
+```markdown
+> [!CAUTION]
+> Negative potential consequences of an action.
+```
+
+## Key Features
+
+- A line break must follow the alert type marker
+- Alerts render as `div` elements with semantic styling rather than blockquote elements
+- Works in READMEs, Markdown files, wikis, issues, pull requests, and discussions
+- Each alert type uses distinct visual styling (colors and icons) for clarity
+
+## Source
+
+Originally discussed at: https://github.com/orgs/community/discussions/16925
diff --git a/.claude/skills/create-readme/references/run-on-output-readme.md b/.claude/skills/create-readme/references/run-on-output-readme.md
new file mode 100644
index 0000000..971734d
--- /dev/null
+++ b/.claude/skills/create-readme/references/run-on-output-readme.md
@@ -0,0 +1,146 @@
+<div align="center">
+  <img src="icon.png" width="96" alt="run-on-output logo">
+  
+  # run-on-output
+  *Execute tasks when CLI output patterns are detected*
+  
+  [![Build Status](https://img.shields.io/github/actions/workflow/status/sinedied/run-on-output/ci.yml?style=flat-square)](https://github.com/sinedied/run-on-output/actions)
+  [![npm version](https://img.shields.io/npm/v/run-on-output?style=flat-square)](https://www.npmjs.com/package/run-on-output)
+  [![Node.js](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)](https://nodejs.org)
+  [![XO code style](https://shields.io/badge/code_style-5ed9c7?logo=xo&labelColor=gray&style=flat-square)](https://github.com/xojs/xo)
+  [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+  ⭐ If you like this project, star it on GitHub!
+
+  [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Examples](#examples)
+
+</div>
+
+
+A lightweight Node.js CLI tool that monitors command output in real-time and triggers actions when specific patterns are found. Perfect for automation workflows, development environments, and CI/CD pipelines.
+
+## Features
+
+- 🎯 **Pattern Matching** - Monitor stdout/stderr for regex patterns or plain strings
+- ⚡ **Real-time Monitoring** - Output is forwarded in real-time while monitoring  
+- 🔧 **Flexible Actions** - Display messages or execute commands when patterns match
+- 📝 **Multiple Patterns** - Wait for multiple patterns before triggering actions
+- 🚀 **Zero Dependencies** - Built with Node.js built-in modules only
+
+## Installation
+
+```bash
+npm install -g run-on-output
+```
+
+Or use without installing:
+
+```bash
+npx run-on-output [options] <command> [args...]
+```
+
+## Usage
+
+### Basic Examples
+
+**Display a message when server starts:**
+```bash
+run-on-output -s "Server started" -m "🚀 Server is ready" npm start
+```
+
+**Execute a health check when server is listening:**
+```bash
+run-on-output -p "listening on port \\d+" -r "curl http://localhost:3000/health" node server.js
+```
+
+**Monitor development environment startup:**
+```bash
+run-on-output -s "webpack compiled,server ready" -m "✅ Development environment ready" npm run dev
+```
+
+**Multiple actions - show message and open browser:**
+```bash
+run-on-output -s "ready" -m "Server is up" -r "open http://localhost:3000" npm start
+```
+
+**Run npm script when server is ready:**
+```bash
+run-on-output -s "Server running" -n "test" node server.js
+```
+
+> [!TIP]
+> You can use the short alias `roo` instead of `run-on-output` for faster typing:
+> ```bash
+> roo -s "Server started" -m "🚀 Server is ready" npm start
+> ```
+
+### Command Line Options
+
+```
+run-on-output [OPTIONS] <command> [args...]
+
+OPTIONS:
+  -p, --patterns <patterns>    Comma-separated list of regex patterns to watch for
+  -s, --strings <strings>      Comma-separated list of plain strings to watch for
+  -r, --run <command>          Command to execute after all patterns are found
+  -n, --npm <script>           npm script to run after all patterns are found
+  -m, --message <text>         Message to display after all patterns are found
+  -h, --help                   Show this help message
+
+REQUIREMENTS:
+  - Either --patterns or --strings must be specified (but not both)
+  - At least one of --run, --npm, or --message must be specified
+```
+
+### Pattern Types
+
+**Plain Strings (`-s, --strings`)**
+- Matches exact text (case-insensitive)
+- Easier to use for simple text matching
+- Example: `-s "Server started,Database connected"`
+
+**Regex Patterns (`-p, --patterns`)**
+- Use regular expressions for complex matching
+- Supports all JavaScript regex features
+- Example: `-p "listening on port \\d+,ready in \\d+ms"`
+
+## Examples
+
+**Development Workflow**
+```bash
+# Wait for both webpack and server, then open browser
+run-on-output -s "webpack compiled,Local:" -r "open http://localhost:3000" npm run dev
+
+# Monitor test runner and show completion message
+run-on-output -s "Tests completed" -m "✅ All tests passed" npm test
+```
+
+**CI/CD Pipeline**
+```bash
+# Wait for deployment completion and run smoke tests
+run-on-output -p "deployment.*complete" -r "./scripts/smoke-test.sh" deploy.sh
+
+# Monitor build process and trigger notifications
+run-on-output -s "Build successful" -r "slack-notify '#dev' 'Build completed'" npm run build
+```
+
+**Docker & Containers**
+```bash
+# Wait for container health check and run integration tests
+run-on-output -s "healthy" -r "npm run test:integration" docker-compose up
+
+# Monitor database initialization
+run-on-output -p "database.*ready" -m "📁 Database initialized" ./start-db.sh
+```
+
+**API Development**
+```bash
+# Wait for API server and run endpoint tests
+run-on-output -p "server.*listening.*port" -r "npm run test:api" node api.js
+
+# Monitor microservices startup and run deployment script
+run-on-output -s "auth-service ready,user-service ready" -n "deploy" ./start-services.sh
+
+# Combine message, command and npm script
+run-on-output -s "Database connected" -m "🎉 Ready for testing" -n "test:integration" npm start
+```
diff --git a/.claude/skills/create-readme/references/serverless-chat-langchainjs-readme.md b/.claude/skills/create-readme/references/serverless-chat-langchainjs-readme.md
new file mode 100644
index 0000000..b36fbba
--- /dev/null
+++ b/.claude/skills/create-readme/references/serverless-chat-langchainjs-readme.md
@@ -0,0 +1,280 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<img src="./packages/webapp/public/favicon.png" alt="" align="center" height="64" />
+
+# Serverless AI Chat with RAG using LangChain.js
+
+[![Open project in GitHub Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/Azure-Samples/serverless-chat-langchainjs?hide_repo_select=true&ref=main&quickstart=true)
+[![Join Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Community-blue?style=flat-square&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+[![Official Learn documentation](https://img.shields.io/badge/Documentation-00a3ee?style=flat-square)](https://learn.microsoft.com/azure/developer/javascript/ai/get-started-app-chat-template-langchainjs)
+[![Watch to learn about RAG and this sample on YouTube](https://img.shields.io/badge/YouTube-d95652.svg?style=flat-square&logo=youtube)](https://www.youtube.com/watch?v=xkFOmx5yxIA&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=4)
+[![dev.to blog post walkthrough](https://img.shields.io/badge/Blog%20post-black?style=flat-square&logo=dev.to)](https://dev.to/azure/build-a-serverless-chatgpt-with-rag-using-langchainjs-3487)
+<br>
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Azure-Samples/serverless-chat-langchainjs/build-test.yaml?style=flat-square&label=Build)](https://github.com/Azure-Samples/serverless-chat-langchainjs/actions)
+![Node version](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
+[![Ollama + Llama3.1](https://img.shields.io/badge/Ollama-Llama3.1-ff7000?style=flat-square)](https://ollama.com/library/llama3.1)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+:star: If you like this sample, star it on GitHub — it helps a lot!
+
+[Overview](#overview) • [Get started](#getting-started) • [Run the sample](#run-the-sample) • [Resources](#resources) • [FAQ](#faq) • [Troubleshooting](#troubleshooting)
+
+![Animation showing the chat app in action](./docs/images/demo.gif)
+
+</div>
+
+This sample shows how to build a serverless AI chat experience with Retrieval-Augmented Generation using [LangChain.js](https://js.langchain.com/) and Azure. The application is hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview) and [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript), with [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/vector-) as the vector database. You can use it as a starting point for building more complex AI applications.
+
+> [!TIP]
+> You can test this application locally without any cost using [Ollama](https://ollama.com/). Follow the instructions in the [Local Development](#local-development) section to get started.
+
+## Overview
+
+Building AI applications can be complex and time-consuming, but using LangChain.js and Azure serverless technologies allows to greatly simplify the process. This application is a chatbot that uses a set of enterprise documents to generate responses to user queries.
+
+We provide sample data to make this sample ready to try, but feel free to replace it with your own. We use a fictitious company called _Contoso Real Estate_, and the experience allows its customers to ask support questions about the usage of its products. The sample data includes a set of documents that describes its terms of service, privacy policy and a support guide.
+
+<div align="center">
+  <img src="./docs/images/architecture.drawio.png" alt="Application architecture" width="640px" />
+</div>
+
+This application is made from multiple components:
+
+- A web app made with a single chat web component built with [Lit](https://lit.dev) and hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview). The code is located in the `packages/webapp` folder.
+
+- A serverless API built with [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript) and using [LangChain.js](https://js.langchain.com/) to ingest the documents and generate responses to the user chat queries. The code is located in the `packages/api` folder.
+
+- A database to store chat sessions and the text extracted from the documents and the vectors generated by LangChain.js, using [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/).
+
+- A file storage to store the source documents, using [Azure Blob Storage](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction).
+
+We use the [HTTP protocol for AI chat apps](https://aka.ms/chatprotocol) to communicate between the web app and the API.
+
+## Features
+
+- **Serverless Architecture**: Utilizes Azure Functions and Azure Static Web Apps for a fully serverless deployment.
+- **Retrieval-Augmented Generation (RAG)**: Combines the power of Azure Cosmos DB and LangChain.js to provide relevant and accurate responses.
+- **Chat Sessions History**: Maintains a personal chat history for each user, allowing them to revisit previous conversations.
+- **Scalable and Cost-Effective**: Leverages Azure's serverless offerings to provide a scalable and cost-effective solution.
+- **Local Development**: Supports local development using Ollama for testing without any cloud costs.
+
+## Getting started
+
+There are multiple ways to get started with this project.
+
+The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
+
+> [!IMPORTANT]
+> If you want to run this sample entirely locally using Ollama, you have to follow the instructions in the [local environment](#use-your-local-environment) section.
+
+### Use your local environment
+
+You need to install following tools to work on your local machine:
+
+- [Node.js LTS](https://nodejs.org/download/)
+- [Azure Developer CLI](https://aka.ms/azure-dev/install)
+- [Git](https://git-scm.com/downloads)
+- [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_
+  - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
+  - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
+- [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_
+
+Then you can get the project code:
+
+1. [**Fork**](https://github.com/Azure-Samples/serverless-chat-langchainjs/fork) the project to create your own copy of this repository.
+2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
+
+<div align="center">
+  <img src="./docs/images/clone-url.png" alt="Screenshot showing how to copy the repository URL" width="400px" />
+</div>
+3. Open a terminal and run this command to clone the repo: <code> git clone &lt;your-repo-url&gt; </code>
+
+### Use GitHub Codespaces
+
+You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
+
+[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/serverless-chat-langchainjs?hide_repo_select=true&ref&quickstart=true)
+
+### Use a VSCode dev container
+
+A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+You will also need to have [Docker](https://www.docker.com/products/docker-desktop) installed on your machine to run the container.
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/serverless-chat-langchainjs)
+
+## Run the sample
+
+There are multiple ways to run this sample: locally using Ollama or Azure OpenAI models, or by deploying it to Azure.
+
+### Deploy the sample to Azure
+
+#### Azure prerequisites
+
+- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents).
+- **Azure subscription with access enabled for the Azure OpenAI service**. You can request access with [this form](https://aka.ms/oaiapply).
+- **Azure account permissions**:
+  - Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](docs/deploy_existing.md#resource-group).
+  - Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
+
+#### Cost estimation
+
+See the [cost estimation](./docs/cost.md) details for running this sample on Azure.
+
+#### Deploy the sample
+
+1. Open a terminal and navigate to the root of the project.
+2. Authenticate with Azure by running `azd auth login`.
+3. Run `azd up` to deploy the application to Azure. This will provision Azure resources, deploy this sample, and build the search index based on the files found in the `./data` folder.
+   - You will be prompted to select a base location for the resources. If you're unsure of which location to choose, select `eastus2`.
+   - By default, the OpenAI resource will be deployed to `eastus2`. You can set a different location with `azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location>`. Currently only a short list of locations is accepted. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and may become outdated as availability changes.
+
+The deployment process will take a few minutes. Once it's done, you'll see the URL of the web app in the terminal.
+
+<div align="center">
+  <img src="./docs/images/azd-up.png" alt="Screenshot of the azd up command result" width="600px" />
+</div>
+
+You can now open the web app in your browser and start chatting with the bot.
+
+##### Enhance security
+
+When deploying the sample in an enterprise context, you may want to enforce tighter security restrictions to protect your data and resources. See the [enhance security](./docs/enhance-security.md) guide for more information.
+
+#### Enable CI/CD
+
+If you want to enable Continuous Deployment for your forked repository, you need to configure the Azure pipeline first:
+
+1. Open a terminal at the root of your forked project.
+2. Authenticate with Azure by running `azd auth login`.
+3. Run `azd pipeline config` to configure the required secrets and variables for connecting to Azure from GitHub Actions.
+   - This command will set up the necessary Azure service principal and configure GitHub repository secrets.
+   - Follow the prompts to complete the configuration.
+
+Once configured, the GitHub Actions workflow will automatically deploy your application to Azure whenever you push changes to the main branch.
+
+#### Clean up
+
+To clean up all the Azure resources created by this sample:
+
+1. Run `azd down --purge`
+2. When asked if you are sure you want to continue, enter `y`
+
+The resource group and all the resources will be deleted.
+
+### Run the sample locally with Ollama
+
+If you have a machine with enough resources, you can run this sample entirely locally without using any cloud resources. To do that, you first have to install [Ollama](https://ollama.com) and then run the following commands to download the models on your machine:
+
+```bash
+ollama pull llama3.1:latest
+ollama pull nomic-embed-text:latest
+```
+
+> [!NOTE]
+> The `llama3.1` model with download a few gigabytes of data, so it can take some time depending on your internet connection.
+
+After that you have to install the NPM dependencies:
+
+```bash
+npm install
+```
+
+Then you can start the application by running the following command which will start the web app and the API locally:
+
+```bash
+npm start
+```
+
+Then, open a new terminal running concurrently and run the following command to upload the PDF documents from the `/data` folder to the API:
+
+```bash
+npm run upload:docs
+```
+
+This only has to be done once, unless you want to add more documents.
+
+You can now open the URL `http://localhost:8000` in your browser to start chatting with the bot.
+
+> [!NOTE]
+> While local models usually works well enough to answer the questions, sometimes they may not be able to follow perfectly the advanced formatting instructions for the citations and follow-up questions. This is expected, and a limitation of using smaller local models.
+
+### Run the sample locally with Azure OpenAI models
+
+First you need to provision the Azure resources needed to run the sample. Follow the instructions in the [Deploy the sample to Azure](#deploy-the-sample-to-azure) section to deploy the sample to Azure, then you'll be able to run the sample locally using the deployed Azure resources.
+
+Once your deployment is complete, you should see a `.env` file in the `packages/api` folder. This file contains the environment variables needed to run the application using Azure resources.
+
+To run the sample, you can then use the same commands as for the Ollama setup. This will start the web app and the API locally:
+
+```bash
+npm start
+```
+
+Open the URL `http://localhost:8000` in your browser to start chatting with the bot.
+
+Note that the documents are uploaded automatically when deploying the sample to Azure with `azd up`.
+
+> [!TIP]
+> You can switch back to using Ollama models by simply deleting the `packages/api/.env` file and starting the application again. To regenerate the `.env` file, you can run `azd env get-values > packages/api/.env`.
+
+## Resources
+
+Here are some resources to learn more about the technologies used in this sample:
+
+- [LangChain.js documentation](https://js.langchain.com)
+- [Generative AI with JavaScript](https://github.com/microsoft/generative-ai-with-javascript)
+- [Generative AI For Beginners](https://github.com/microsoft/generative-ai-for-beginners)
+- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/overview)
+- [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/)
+- [Ask YouTube: LangChain.js + Azure Quickstart sample](https://github.com/Azure-Samples/langchainjs-quickstart-demo)
+- [Chat + Enterprise data with Azure OpenAI and Azure AI Search](https://github.com/Azure-Samples/azure-search-openai-javascript)
+- [Revolutionize your Enterprise Data with Chat: Next-gen Apps w/ Azure OpenAI and AI Search](https://aka.ms/entgptsearchblog)
+
+You can also find [more Azure AI samples here](https://github.com/Azure-Samples/azureai-samples).
+
+## FAQ
+
+You can find answers to frequently asked questions in the [FAQ](./docs/faq.md).
+
+## Troubleshooting
+
+If you have any issue when running or deploying this sample, please check the [troubleshooting guide](./docs/troubleshooting.md). If you can't find a solution to your problem, please [open an issue](https://github.com/Azure-Samples/serverless-chat-langchainjs/issues) in this repository.
+
+## Guidance
+
+For more detailed guidance on how to use this sample, please refer to the [tutorial](./docs/tutorial/01-introduction.md).
+
+## Getting Help
+
+If you get stuck or have any questions about building AI apps, join:
+
+[![Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+
+If you have product feedback or errors while building visit:
+
+[![Azure AI Foundry Developer Forum](https://img.shields.io/badge/GitHub-Azure_AI_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum)
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.
diff --git a/.claude/skills/create-readme/references/serverless-recipes-javascript-readme.md b/.claude/skills/create-readme/references/serverless-recipes-javascript-readme.md
new file mode 100644
index 0000000..d361fd6
--- /dev/null
+++ b/.claude/skills/create-readme/references/serverless-recipes-javascript-readme.md
@@ -0,0 +1,162 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<img src="./docs/images/icon.png" alt="" align="center" height="96" />
+
+# Serverless Recipes for JavaScript/TypeScript
+
+[![Open project in GitHub Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/Azure-Samples/serverless-recipes-javascript?hide_repo_select=true&ref=main&quickstart=true)
+[![Join Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Community-blue?style=flat-square&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Azure-Samples/serverless-recipes-javascript/build-test.yaml?style=flat-square&label=Build)](https://github.com/Azure-Samples/serverless-recipes-javascript/actions)
+![Node version](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+⭐ If you like this project, star it on GitHub — it helps a lot!
+
+[Get started](#getting-started) • [Run the samples](#run-the-samples) • [Samples list](#samples-list) • [Resources](#resources) • [Troubleshooting](#troubleshooting)
+
+</div>
+
+This repository is a collection of code examples demonstrating how to build serverless applications using TypeScript and Azure. Each recipe is a standalone sample that demonstrates how to build a specific feature or use a specific technology. You can use these samples as a starting point for your own projects or to learn more about serverless development with Azure.
+
+> [!NOTE]
+> **What's Serverless?**<br>
+> Serverless computing allows you to build and run applications without managing infrastructure. You can focus on your code and let the cloud provider handle the rest. Azure provides a wide range of serverless services, including [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript), [Azure Static Web Apps]([Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview), [Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db/nosql/), and more.
+
+## Why serverless?
+
+Let's say you're a developer for the Contoso Solutions company, and you've been tasked to build new applications with a fast turnaround time, startup style. You need to build these apps quickly with a low initial budget, and you don't want to worry about managing servers, scaling, or infrastructure. **You want to focus on writing code and delivering value to your users.**
+
+*This is exactly where serverless is a great fit!*
+
+While walking through this collection of ready-to-use code examples, you'll learn how to solve common problems and build applications using many of the serverless technologies available on Azure. The best part? You only need to pay attention to the code and the business logic, all samples are ready to deploy and run in your Azure account.
+
+## Prerequisites
+- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents).
+- **GitHub account**. If you don't have one, you can [create a free GitHub account](https://github.com/signup). You can optionally use [GitHub Copilot Free](https://github.com/features/copilot) to help you write code and ship your application even faster.
+
+## Getting started
+
+There are multiple ways to get started with this project.
+
+The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
+
+<details open>
+<summary><h3>Use GitHub Codespaces</h3></summary>
+
+You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
+
+[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=flat-square&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/serverless-recipes-javascript?hide_repo_select=true&ref&quickstart=true)
+
+</details>
+
+<details>
+<summary><h3>Use a VSCode dev container</h3></summary>
+
+A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+You will also need to have [Docker](https://www.docker.com/get-started/) installed on your machine to run the container.
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=flat-square&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/serverless-recipes-javascript)
+
+</details>
+
+<details>
+<summary><h3>Use your local environment</h3></summary>
+
+You need to install following tools to work on your local machine:
+
+- [Node.js LTS](https://nodejs.org/en/download)
+- [Azure Developer CLI](https://aka.ms/azure-dev/install)
+- [Git](https://git-scm.com/downloads)
+- [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_
+  - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
+  - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
+- [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_
+
+Then you can get the project code:
+
+1. [**Fork**](https://github.com/Azure-Samples/serverless-recipes-javascript/fork) the project to create your own copy of this repository.
+2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
+
+   ![Screenshot showing how to copy the repository URL](./docs/images/clone-url.png)
+3. Open a terminal and run this command to clone the repo: `git clone <your-repo-url>`
+
+</details>
+
+## Run the samples
+
+After setting up your environment, you can deploy and run any of the samples. Each sample is a standalone project that you can run independently. Follows these steps to run a sample:
+
+```bash
+# Open the sample directory
+cd samples/<sample-name>
+
+# Install dependencies
+npm install
+
+# Deploy the sample to Azure
+azd auth login
+azd up
+```
+
+Once the initial deployment is completed, you can also run the sample locally with `npm start`.
+You can check the `README.md` file in each sample directory for more specific instructions.
+
+## Samples list
+
+<!-- #begin-samples -->
+
+| | Sample | Deployment Time | Video | Blog |
+| --- |:--- | --- | --- | --- |
+| <img src="./samples/openai-extension-embeddings/docs/images/icon.png" width="32px"/> | [Azure Functions OpenAI extension - embeddings](./samples/openai-extension-embeddings) | 5min | - | - |
+| <img src="./samples/openai-extension-textcompletion/docs/images/icon.png" width="32px"/> | [Azure Functions OpenAI extension - text completion](./samples/openai-extension-textcompletion) | 5min | - | - |
+
+<!-- #end-samples -->
+
+## Resources
+
+Here are some additional resources to learn more about the technologies used:
+
+- [Serverless Node.js with Azure Functions](https://learn.microsoft.com/azure/developer/javascript/how-to/develop-serverless-apps?tabs=v4-ts) (Microsoft Learn)
+- [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/) (Microsoft Learn)
+- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/overview) (Microsoft Learn)
+- [Generative AI with JavaScript](https://github.com/microsoft/generative-ai-with-javascript) (GitHub)
+- [Serverless AI Chat with RAG using LangChain.js](https://github.com/Azure-Samples/serverless-chat-langchainjs) (GitHub)
+
+## Troubleshooting
+
+If you have any issue when running or deploying the samples, please check the [troubleshooting guide](./docs/troubleshooting.md). If you can't find a solution to your problem, please [open an issue](https://github.com/Azure-Samples/serverless-recipes-javascript/issues) in this repository.
+
+## Getting Help
+
+If you get stuck or have any questions about building AI apps, join:
+
+[![Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+
+If you have product feedback or errors while building visit:
+
+[![Azure AI Foundry Developer Forum](https://img.shields.io/badge/GitHub-Azure_AI_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum)
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.
diff --git a/.claude/skills/create-readme/references/smoke-readme.md b/.claude/skills/create-readme/references/smoke-readme.md
new file mode 100644
index 0000000..fd2fc80
--- /dev/null
+++ b/.claude/skills/create-readme/references/smoke-readme.md
@@ -0,0 +1,366 @@
+# :dash: smoke
+
+[![NPM version](https://img.shields.io/npm/v/smoke.svg)](https://www.npmjs.com/package/smoke)
+[![Build Status](https://github.com/sinedied/smoke/workflows/build/badge.svg)](https://github.com/sinedied/smoke/actions)
+![Node version](https://img.shields.io/node/v/smoke.svg)
+[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> Simple yet powerful file-based mock server with recording abilities
+
+![demo](https://user-images.githubusercontent.com/593151/49312821-9f2cc680-f4e5-11e8-900a-117120c38422.gif)
+
+Just drop a bunch of (JSON) files in a folder and you're ready to go!
+
+### Basic mock example
+1. Start the server: `smoke`
+2. Create a file named `get_api#hello.json`:
+    ```json
+    {
+      "message": "hello world!"
+    }
+    ```
+3. Test the mock: `curl http://localhost:3000/api/hello`
+
+### Features
+
+**Smoke** is a file-based, convention over configuration mock server that can fill your API mocking needs without any
+complex setup. Yet, it supports many advanced features and dynamic mocks for almost any situation:
+
+- Generate mocks quickly by recording responses from an existing server
+- Use folders and file names to describe API routes and REST methods
+- Use templates to generate responses based on input queries and route parameters
+- Add / edit / remove mocks without restarting the server
+- Generate mocks with JavaScript for more complex responses
+- Define different mock sets to simulate various scenarii (errors...), with fallback
+- Customize headers and status code if needed, automatically detect content-type if not specified
+- Add custom middlewares to modify requests/responses
+- Mock only specific requests and proxy the rest to an existing server
+- Supports CORS (cross-origin resource-sharing)
+
+## Installation
+
+```bash
+npm install -g smoke
+```
+
+## Usage
+
+See [some example mocks](test/mocks) to quickly get a grasp of the syntax and possibilities.
+
+CLI usage is quite straightforward you can just run `smoke` unless you want to add some options:
+```
+Usage: smoke [<mocks_folder>] [options]
+
+Base options:
+  -p, --port <num>                  Server port           [default: 3000]
+  -h, --host <host>                 Server host           [default: "localhost"]
+  -s, --set <name>                  Mocks set to use      [default: none]
+  -n, --not-found <glob>            Mocks for 404 errors  [default: "404.*"]
+  -i, --ignore <glob>               Files to ignore       [default: none]
+  -k, --hooks <file>                Middleware hooks      [default: none]
+  -x, --proxy <host>                Fallback proxy if no mock found
+  -o, --allow-cors [all|<hosts>]    Enable CORS requests  [default: none]
+  --https                           Enable secure request serving with HTTPS [default: false]
+  -l, --logs                        Enable server logs
+  -v, --version                     Show version
+  --help                            Show help
+
+Mock recording:
+  -r, --record <host>               Proxy & record requests if no mock found
+  -c, --collection <file>           Save to single file mock collection
+  -d, --depth <N>                   Folder depth for mocks  [default: 1]
+  -a, --save-headers                Save response headers
+  -q, --save-query                  Save query parameters
+```
+
+### File naming
+
+**General format:** `methods_api#route#@routeParam$queryParam=value.__set.extension`
+
+The path and file name of the mock is used to determinate:
+
+#### Supported HTTP methods
+Optionally prefix your file by the HTTP method supported followed by an underscore (for example `get_`).
+You can specify multiple methods at once using a `+` to separate them (for example `post+put_`);
+If no method is specified, the mock will be used for any HTTP method.
+
+#### Server route and named route parameters
+Use any combination of folders or hash-separated components to specify the server route.
+
+For example `api/example/get_hello.json` is equivalent to `get_api#example#hello.json` and will respond to
+`GET api/example/hello` requests.
+
+Additionaly, any route component can be defined as a route parameter by prefixing the name with `@`, for example
+`api#resource#@id.json` will match `GET api/resource/1` and expose `1` as the value for the `id` parameter that can be
+used in dynamic mocks (templates or JavaScript).
+
+#### Query parameters
+You can further discriminate mocks by adding query parameters to match after defining the route, using a `$` (instead
+of the regular `?`) like you would specify them in a request.
+
+For example `get_api#hello$who=john.json` will match the request `api/get_hello?who=john.json`.
+
+Multiple query parameters to match can be added with `&`, for example `get_api#hello$who=john&greet=hi.json`.
+Any specified query parameter in the file name must be matched (in any order) by the request, but the opposite is not
+needed.
+
+Note that special characters must be URL-encoded, for example use `get_api#hello$who=john%20doe.json` to set the
+parameter `who` with the value `john doe`.
+
+> Tip: If you need to URL-encode a string, just run `node -p "encodeURIComponent('some string')"` in a terminal.
+
+#### Content type
+The file extension will determine the content type of the response if it's not already specified in a
+[custom header](#custom-status-and-headers).
+
+Files with no extension will use the default MIME type `application/octet-stream`.
+
+You can have multiple mocks with the same API route and different file extensions, the server will then use the best
+mock depending of the [`Accept` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) of the
+request.
+
+#### Mock set
+You can optionally specify a mock set before the file extension by using a `__set-name` suffix after the file name.
+
+For example `get_api#hello__error.json` will only be used if you start the server with the `error` set enabled:
+`smoke --set error`.
+
+If you do not specify a mock set on your file name, it will be considered as the default mock for the specified route
+and will be used as a fallback if no mock with this set matched.
+
+#### Templates
+If you add an underscore `_` after the file extension, the mock will be processed as a template before being sent to
+the client. Templates works only on text-based formats.
+
+For example `get_hello.html_` or `get_hello.json_` will be treated as templates. 
+
+Every template can use an implicit context object that have these properties defined:
+- `method`: the HTTP method of the request (ex: `'GET'`, `'POST'`)
+- `query`: map with query parameters that were part of the request URL. For example, matched URL
+  `http://server/hello?who=world` will result in the query value: `{ who: 'world' }`.
+- `params`: map containing matched route parameters. For example the mock `resource#@id.json_` with the matched URL
+  `http://server/resource/123` will result in the params value: `{ id: '123' }`.
+- `headers`: map containing request headers
+- `body`: the request body. JSON bodies are automatically parsed.
+- `files`: if the request includes `multipart/form-data`, this will be the array of uploaded files (see
+  [multer documentation](https://github.com/expressjs/multer) for more details)
+
+##### Template syntax
+
+- `{{ }}` interpolates data in place
+
+  For example, create **get_hello.txt_** with this:
+  ```
+  Hello {{query.name}}!
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=John"` returns `Hello John!`
+
+- `{{{ }}}` escapes HTML special chars from interpolated string
+
+  For example, create **get_hello.html_** with this:
+  ```html
+  <h1>Hello {{{query.name}}}!</h1>
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=%3CJack%26Jones%3E"` returns:
+  ```html
+  <h1>Hello &lt;Jack&amp;Jones&gt;!</h1>
+  ```
+
+- `<{ }>` evaluates JavaScript to generate data
+
+  For example, create **get_hello.html_** with this:
+  ```html
+  Hello to:
+  <ul>
+    <{ query.name.forEach(name => { }><li>{{name}}</li><{ }); }>
+  </ul>
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=Jack&name=Jones"` returns:
+  ```html
+  Hello to:
+  <ul>
+    <li>Jack</li><li>Jones</li>
+  </ul>
+  ```
+
+### Custom status and headers
+
+By default all mocks responses are sent with a status code `200` (OK), or `204` (No content) if a mock file is empty.
+
+You can customize the response status and (optionally) headers with JSON and [JavaScript](#javascript-mocks) files,
+using this syntax:
+```js
+{
+  "statusCode": 400,
+  "body": {
+    "error": "Bad request"
+  },
+  // headers can be omitted, only use if you want to customize them
+  "headers": {
+    "Content-Type": "text/plain"
+  } 
+}
+```
+
+You can also use non-string content type if you encode the content as a base64 string in the `body` property and add
+the property `"buffer": true` to the mock:
+```js
+{
+  "statusCode": 200,
+  "body": "U21va2Ugcm9ja3Mh",
+  "buffer": true,
+  "headers": {
+    "Content-Type": "application/octet-stream"
+  } 
+}
+```
+
+### Mock formats
+
+Any file format is supported for mocks, and the file extension will be used to determine the response content type.
+Files with no extension will use the default MIME type `application/octet-stream`.
+
+Text formats (for example `.json`, `.html`, `.txt`...) can be processed as [templates](#templates) by adding an
+underscore to the file extension.
+
+Note that JSON files and templates must use `UTF-8` encoding.
+
+#### JavaScript mocks
+
+In addition, you can define dynamic mocks using JavaScript by using the `.js` extension, that will be loaded as a regular
+Node.js module.
+
+In that case, your JS module is expected to export a function that take an input data object with the
+[same properties](#templates) as for templates and must returns the response body or an
+[object](#custom-status-and-headers) containing the status code, headers and body.
+
+Example:
+```js
+export default (data) => `{ "data": "Your user agent is: ${data.headers['user-agent']}" }`;
+```
+
+Note that by default, JS mocks use `application/json` for the response content type. If you want to use another type,
+you must set the `Content-Type` header yourself, for example:
+```js
+export default data => ({
+  statusCode: 200,
+  headers: {
+    'Content-Type': 'text/plain'
+  },
+  body: `Your user agent is: ${data.headers['user-agent']}`
+});
+```
+
+### Fallback proxy
+
+If you want to override responses of an existing server, you can use the `--proxy <host>` option. This will proxy
+every request for which a mock does not exist to the specified host.
+
+This can also be useful for mocking yet-to-be-implemented APIs and keep using real implemented APIs.
+
+### Mock recording
+
+To quickly create a mock set of an existing server (to allow working offline for example), you can use the
+`--record <host>` option. This will proxy every request for which a mock does not exist to the specified host, and
+record the resulting response as a mock file.
+
+You can change the maximum folder depth for mock files created this way using the `--depth` option.
+
+The recorded mock set can also be changed using the `--set` option.
+
+Instead of recoring separate mock files, you can also record to a
+[single file mock collection](#single-file-mock-collection) using the `--collection <file>` option. 
+
+Note that by default response headers and request query parameters are not saved. To change this behavior, you can
+use the `--save-headers` and `--save-query` options.
+
+### Middleware hooks
+
+For more advanced usages, you can hook on any standard
+[Express middleware](https://expressjs.com/en/guide/writing-middleware.html) to modify the request and/or the response
+returned by the server.
+
+To hook on your own middlewares, use the `--hooks` to specify a JavaScript module with exports setup like this:
+```js
+export const before = []; // middlewares to be executed before the request is processed
+export const after = [];  // middlewares to be executed after the request has been processed
+```
+
+Middlewares executed before the request is processed can be used to bypass regular mock response, for example to
+randomly simulate a server failure with an early error 500 response.
+
+On the other hand, middlewares executed after the request have been processed can be used to augment or modify the
+response, for example by adding header or changing the response status. You can also access and modify the response
+body by using the special `res.body` property.
+
+Remember that once you have used `.send()`, `.sendStatus` or `.json()` in a middleware the response cannot be altered
+anymore, that's why you should use the `res.body` property instead if you plan to alter the response later on.
+
+See some [example hooks](test/hooks.js).
+
+## Enabling CORS
+
+Smoke offers support to requests originating from a different origin. However, by default, this would be disabled.
+
+To enable CORS, pass the hosts that you want to allow to `-o` or `--allow-cors` arguments.
+
+**Accepted Values**
+- `all` - Allow requests from `*`
+- `<hosts>` - You could also pass a comma-separated list of hosts that you want to allow requests from something like `'http://localhost:3000,http://example.com'`
+
+### Single file mock collection
+
+You can regroup multiple mocks in a special single file with the extension `.mocks.js`, using this format:
+```js
+export default {
+  '<file_name>': '<file_content>' // can be a string, an object (custom response) or a function (JavaScript mock)
+};
+```
+See this [example mock collection](test/mocks/collection.mocks.js) to get an idea of all possibilities.
+
+The format of file name is the same as for individual mock files, and will be used to match the request using the same
+rules. As for the mock content, the format is also the same as what you would put in single file mock. If a request
+matches both a mock file and a mock within a collection with the same specificity, the mock file will always be used
+over the collection.
+
+As the format is the same, you can convert a bunch of files to a single file mock collection and conversely.
+To convert separate mock files to a collection:
+```sh
+smoke-conv <glob> <output_file>  // Will create <output_file>.mocks.js from all mocks found
+```
+
+To convert a mock collection to separate files:
+```sh
+smoke-conv <file> <output_folder>  // Will extract separate mocks into <output_folder>
+```
+
+Note that only text-based file content will be inserted directly, other file content will be converted to a base64
+string.
+
+:warning: There is a limitation regarding JavaScript mocks: only the exported function will be converted for a given
+mock, meaning that if you have non-exported functions, variables or imports they will be lost during the conversion.
+
+## Migration from v1/v2/v3 to v4
+
+If you are migrating from a previous version of Smoke, you need to be aware that the default module format has changed: earlier version used CommonJS modules, while v4 uses ES modules by default.
+
+But don't worry! You don't have to regenerate or updates all your mock files, Smoke will still support the CommonJS format for backward compatibility, though you need to rename all your `*.js` mocks, collections and hooks files to use the `.cjs` extension instead of `.js`.
+
+If you prefer to migrate your existing mock files to the new ES module format, you can do so by updating the export syntax to use `export default` instead of `module.exports` in mock files and collections, and `export` the `before` and `after` hooks constant separately in hooks fles.
+
+> [!NOTE]
+> If you try to record new mocks into an existing collection in CommonJS format, the result will be saved into a new collection in ES modules format.
+
+## Other mock servers
+
+If you cannot find what you need here, you might want to check out one of these other Node.js mock servers:
+
+- [JSON Server](https://github.com/typicode/json-server)
+- [mockserver](https://github.com/namshi/mockserver)
+- [node-mock-server](https://github.com/smollweide/node-mock-server)
+- [node-easymock](https://github.com/CyberAgent/node-easymock)
+- [mockserver-node](https://github.com/jamesdbloom/mockserver-node)
diff --git a/.claude/skills/dotnet-aspnet/SKILL.md b/.claude/skills/dotnet-aspnet/SKILL.md
index 1a6a094..b3ba212 100644
--- a/.claude/skills/dotnet-aspnet/SKILL.md
+++ b/.claude/skills/dotnet-aspnet/SKILL.md
@@ -1,372 +1,46 @@
 ---
 name: dotnet-aspnet
-description: ASP.NET Core best practices for building Web and REST APIs. Use when creating controllers, minimal APIs, configuring middleware, routing, model binding, validation, dependency injection, authentication, authorization, error handling with ProblemDetails, OpenAPI/Swagger, health checks, CORS, rate limiting, or structuring an ASP.NET Core project.
+description: Applies ASP.NET Core best practices for building Web and REST APIs. Use when creating controllers, minimal APIs, configuring middleware, routing, model binding, validation, authentication, authorization, error handling with ProblemDetails, OpenAPI/Swagger, health checks, CORS, rate limiting, or structuring an ASP.NET Core project. For DI, Options pattern, and configuration that apply to any .NET host, use dotnet-fundamentals.
 ---
 
 # ASP.NET Core Web API Best Practices
 
-## Project Structure
+## When to Use
 
-- Organize code by feature/domain, not by layer (avoid generic `Controllers/`, `Services/`, `Models/` folders)
-- Use `Program.cs` as the composition root — register services, configure middleware pipeline
-- Keep `Program.cs` lean by extracting registration into extension methods (e.g., `AddApplicationServices()`, `AddAuthenticationServices()`)
-- Use feature folders:
-  ```
-  Features/
-    Orders/
-      OrdersController.cs
-      CreateOrderRequest.cs
-      OrderResponse.cs
-      OrderService.cs
-    Products/
-      ...
-  ```
+- Creating new controllers, minimal API endpoints, or feature folders in an ASP.NET Core project
+- Configuring the middleware pipeline, routing, or model binding
+- Adding authentication, authorization policies, or `[Authorize]`-based access control
+- Implementing error handling with `ProblemDetails` (RFC 9457) or `IExceptionHandler`
+- Wiring up OpenAPI/Swagger, health checks, CORS, rate limiting, output caching, or response compression
+- Reviewing or restructuring an existing ASP.NET Core project to align with best practices
 
-## Controllers vs Minimal APIs
+This skill covers the **HTTP / web layer only**. For dependency injection, Options pattern, and configuration that apply to any .NET host, see [`dotnet-fundamentals`](../dotnet-fundamentals/SKILL.md).
 
-### Controllers
+## Core Principles
 
-Use controllers for larger APIs with shared conventions, filters, and complex routing:
+- Use feature folders, not layer folders. Keep `Program.cs` lean — extract registrations into extension methods.
+- Always use `[ApiController]` on MVC controllers; prefer `TypedResults` in minimal APIs.
+- Accept `CancellationToken` on every async endpoint.
+- Map domain exceptions to ProblemDetails — never leak internal exception messages.
+- Middleware order matters: exception handler → status code pages → HSTS/HTTPS → CORS → auth → rate limiter → endpoints.
 
-```csharp
-[ApiController]
-[Route("api/[controller]")]
-public class OrdersController(IOrderService orderService) : ControllerBase
-{
-    [HttpGet("{id:guid}")]
-    [ProducesResponseType<OrderResponse>(StatusCodes.Status200OK)]
-    [ProducesResponseType(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
-    {
-        var order = await orderService.GetByIdAsync(id, ct);
-        return order is null ? NotFound() : Ok(order);
-    }
-}
-```
+## Reference Index
 
-- Always use `[ApiController]` attribute — enables automatic model validation, binding source inference, and ProblemDetails responses
-- Use primary constructor injection for dependencies
-- Return `IActionResult` or `ActionResult<T>` for endpoints with multiple response types
-- Accept `CancellationToken` on all async endpoints
+Detailed patterns and code samples live in `references/`:
 
-### Minimal APIs
-
-Use minimal APIs for simple endpoints, microservices, or when startup performance matters:
-
-```csharp
-var group = app.MapGroup("/api/orders")
-    .WithTags("Orders")
-    .RequireAuthorization();
-
-group.MapGet("/{id:guid}", async (Guid id, IOrderService service, CancellationToken ct) =>
-{
-    var order = await service.GetByIdAsync(id, ct);
-    return order is null ? Results.NotFound() : Results.Ok(order);
-})
-.WithName("GetOrderById")
-.Produces<OrderResponse>()
-.ProducesProblem(StatusCodes.Status404NotFound);
-```
-
-- Use `MapGroup()` to share route prefixes, filters, and metadata
-- Use `TypedResults` instead of `Results` for compile-time response type verification
-- Add `.WithName()` for OpenAPI operation IDs and link generation
-- Use endpoint filters for cross-cutting concerns
-
-## Routing & Endpoints
-
-- Use attribute routing on controllers (`[Route]`, `[HttpGet]`, etc.)
-- Apply route constraints: `{id:guid}`, `{page:int:min(1)}`, `{slug:regex(^[a-z-]+$)}`
-- Use API versioning via URL segment (`/api/v1/orders`) or header-based versioning with `Asp.Versioning.Http`
-- Keep route templates consistent — plural nouns for resources (`/api/orders`, not `/api/order`)
-- Use `LinkGenerator` for generating URLs to named endpoints
-
-## Model Binding & Validation
-
-- Use binding source attributes explicitly: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromHeader]`
-- With `[ApiController]`, complex types default to `[FromBody]`, simple types to `[FromRoute]`/`[FromQuery]`
-- Validate with Data Annotations or FluentValidation:
-
-```csharp
-public record CreateOrderRequest(
-    [Required] string CustomerId,
-    [Required, MinLength(1)] List<OrderItemRequest> Items);
-```
-
-- For FluentValidation: register validators via `AddValidatorsFromAssemblyContaining<T>()` and use a validation filter or `IEndpointFilter`
-- Return `ValidationProblemDetails` (automatic with `[ApiController]`) for validation failures
-
-## Dependency Injection
-
-- Register services in `Program.cs` or via extension methods
-- Use appropriate lifetimes:
-  - **Transient**: Stateless, lightweight services
-  - **Scoped**: Per-request services (DbContext, unit of work)
-  - **Singleton**: Thread-safe, shared state (caches, configuration)
-- Use keyed services (.NET 8+) when multiple implementations of the same interface are needed:
-  ```csharp
-  builder.Services.AddKeyedScoped<IPaymentGateway, StripeGateway>("stripe");
-  builder.Services.AddKeyedScoped<IPaymentGateway, PayPalGateway>("paypal");
-  ```
-- Prefer interface-based registration for testability
-- Avoid service locator pattern — do not inject `IServiceProvider` into business logic
-
-## Middleware Pipeline
-
-Order matters — register middleware in the correct sequence:
-
-```csharp
-app.UseExceptionHandler();
-app.UseStatusCodePages();
-app.UseHsts();
-app.UseHttpsRedirection();
-app.UseCors();
-app.UseAuthentication();
-app.UseAuthorization();
-app.UseRateLimiter();
-app.UseOutputCache();
-app.MapControllers();
-```
-
-### Custom Middleware
-
-```csharp
-public class RequestTimingMiddleware(RequestDelegate next)
-{
-    public async Task InvokeAsync(HttpContext context)
-    {
-        var sw = Stopwatch.StartNew();
-        context.Response.OnStarting(() =>
-        {
-            context.Response.Headers["X-Response-Time-Ms"] = sw.ElapsedMilliseconds.ToString();
-            return Task.CompletedTask;
-        });
-        await next(context);
-    }
-}
-```
-
-- Use primary constructors for middleware
-- Inject scoped services via `InvokeAsync` parameters, not the constructor
-- Keep middleware focused — one concern per middleware
-
-## Configuration
-
-- Use the Options pattern for strongly-typed configuration:
-
-```csharp
-public class SmtpOptions
-{
-    public const string SectionName = "Smtp";
-    public required string Host { get; init; }
-    public int Port { get; init; } = 587;
-    public required string Username { get; init; }
-}
-
-builder.Services.AddOptions<SmtpOptions>()
-    .BindConfiguration(SmtpOptions.SectionName)
-    .ValidateDataAnnotations()
-    .ValidateOnStart();
-```
-
-- Use `ValidateOnStart()` to catch configuration errors at startup, not at first use
-- Use `appsettings.json` for defaults, `appsettings.{Environment}.json` for overrides
-- Use User Secrets (`dotnet user-secrets`) for local development — never commit secrets
-- Use environment variables or a vault for production secrets
-- Inject `IOptions<T>` for static config, `IOptionsMonitor<T>` for reloadable config
-
-## Authentication & Authorization
-
-### JWT Bearer Authentication
-
-```csharp
-builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
-    .AddJwtBearer(options =>
-    {
-        options.Authority = builder.Configuration["Auth:Authority"];
-        options.Audience = builder.Configuration["Auth:Audience"];
-    });
-```
-
-### Authorization Policies
-
-```csharp
-builder.Services.AddAuthorizationBuilder()
-    .AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"))
-    .AddPolicy("CanEditOrder", policy =>
-        policy.Requirements.Add(new OrderOwnerRequirement()));
-```
-
-- Use policy-based authorization over role checks in attributes
-- Apply `[Authorize]` at controller level, `[AllowAnonymous]` for exceptions
-- Implement `IAuthorizationHandler` for resource-based authorization
-- For minimal APIs use `.RequireAuthorization("PolicyName")`
-
-## Error Handling
-
-### ProblemDetails (RFC 9457)
-
-```csharp
-builder.Services.AddProblemDetails(options =>
-{
-    options.CustomizeProblemDetails = ctx =>
-    {
-        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
-    };
-});
-```
-
-### Global Exception Handling (.NET 8+)
-
-```csharp
-public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
-{
-    public async ValueTask<bool> TryHandleAsync(
-        HttpContext context, Exception exception, CancellationToken ct)
-    {
-        logger.LogError(exception, "Unhandled exception");
-
-        var problem = new ProblemDetails
-        {
-            Status = StatusCodes.Status500InternalServerError,
-            Title = "An error occurred",
-            Type = "https://httpstatuses.com/500"
-        };
-
-        context.Response.StatusCode = problem.Status.Value;
-        await context.Response.WriteAsJsonAsync(problem, ct);
-        return true;
-    }
-}
-
-builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
-```
-
-- Use `IExceptionHandler` (.NET 8+) instead of custom exception middleware
-- Map domain exceptions to appropriate HTTP status codes
-- Never expose internal exception details in production responses
-- Use `app.UseStatusCodePages()` for consistent responses on empty status codes (404, 405, etc.)
-
-## API Conventions & Response Types
-
-- Annotate endpoints with `[ProducesResponseType]` for OpenAPI documentation
-- Use `[Consumes]` and `[Produces]` for content type negotiation
-- Return consistent response envelopes or use ProblemDetails for errors
-- Use `TypedResults` in minimal APIs for compile-time response verification:
-
-```csharp
-group.MapPost("/", async (CreateOrderRequest req, IOrderService service, CancellationToken ct) =>
-{
-    var id = await service.CreateAsync(req, ct);
-    return TypedResults.Created($"/api/orders/{id}", new { id });
-});
-```
-
-## OpenAPI / Swagger
-
-- Use the built-in OpenAPI support (.NET 9+) or Swashbuckle/NSwag for earlier versions:
-
-```csharp
-builder.Services.AddOpenApi();
-// ...
-app.MapOpenApi();
-```
-
-- Enable XML comments in `.csproj` for automatic documentation:
-  ```xml
-  <PropertyGroup>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <NoWarn>$(NoWarn);1591</NoWarn>
-  </PropertyGroup>
-  ```
-- Use `[Tags]`, `[EndpointSummary]`, `[EndpointDescription]` for metadata
-- Use `WithName()` and `WithTags()` on minimal API endpoints
-- Use the `csharp-docs` skill for writing XML documentation comments
-
-## Health Checks
-
-```csharp
-builder.Services.AddHealthChecks()
-    .AddCheck("self", () => HealthCheckResult.Healthy())
-    .AddNpgSql(connectionString, name: "database")
-    .AddRedis(redisConnectionString, name: "cache");
-
-app.MapHealthChecks("/health", new HealthCheckOptions
-{
-    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
-});
-
-app.MapHealthChecks("/health/ready", new HealthCheckOptions
-{
-    Predicate = check => check.Tags.Contains("ready")
-});
-```
-
-- Separate liveness (`/health`) and readiness (`/health/ready`) endpoints
-- Tag health checks for selective filtering
-- Use NuGet packages `AspNetCore.HealthChecks.*` for common dependencies
-- Use the `nuget-manager` skill for adding health check packages
-
-## Cross-Cutting Concerns
-
-### CORS
-
-```csharp
-builder.Services.AddCors(options =>
-{
-    options.AddPolicy("AllowFrontend", policy =>
-        policy.WithOrigins("https://app.example.com")
-              .AllowAnyHeader()
-              .AllowAnyMethod()
-              .AllowCredentials());
-});
-
-app.UseCors("AllowFrontend");
-```
-
-### Rate Limiting (.NET 7+)
-
-```csharp
-builder.Services.AddRateLimiter(options =>
-{
-    options.AddFixedWindowLimiter("api", limiter =>
-    {
-        limiter.PermitLimit = 100;
-        limiter.Window = TimeSpan.FromMinutes(1);
-    });
-    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
-});
-
-app.UseRateLimiter();
-```
-
-- Apply per-endpoint with `[EnableRateLimiting("api")]` or `.RequireRateLimiting("api")`
-
-### Output Caching (.NET 7+)
-
-```csharp
-builder.Services.AddOutputCache(options =>
-{
-    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
-    options.AddPolicy("NoCache", builder => builder.NoCache());
-});
-```
-
-### Response Compression
-
-```csharp
-builder.Services.AddResponseCompression(options =>
-{
-    options.EnableForHttps = true;
-    options.Providers.Add<BrotliCompressionProvider>();
-    options.Providers.Add<GzipCompressionProvider>();
-});
-```
+- **[project-and-endpoints.md](references/project-and-endpoints.md)** — Project structure, Controllers vs Minimal APIs, routing, API conventions, response types (`TypedResults`, `[ProducesResponseType]`)
+- **[model-binding-validation.md](references/model-binding-validation.md)** — Binding sources (`[FromBody]`, `[FromRoute]`, etc.), Data Annotations, FluentValidation, `ValidationProblemDetails`
+- **[middleware.md](references/middleware.md)** — Pipeline order, custom middleware with primary constructors
+- **[auth.md](references/auth.md)** — JWT Bearer, authorization policies, `IAuthorizationHandler`, `RequireAuthorization`
+- **[error-handling.md](references/error-handling.md)** — ProblemDetails, `IExceptionHandler` (.NET 8+), `UseStatusCodePages`
+- **[openapi-and-cross-cutting.md](references/openapi-and-cross-cutting.md)** — OpenAPI/Swagger, XML doc generation, health checks (liveness/readiness), CORS, rate limiting, output caching, response compression
 
 ## Related Skills
 
-- **[ef-core](../ef-core/SKILL.md)** — Data access with Entity Framework Core
-- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Unit and integration testing
-- **[csharp-docs](../csharp-docs/SKILL.md)** — XML documentation comments
-- **[nuget-manager](../nuget-manager/SKILL.md)** — NuGet package management
-- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — SDK/client library generation
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Foundation: DI, Options pattern, configuration, modern C# idioms used by every endpoint and service in this skill
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — Data access with Entity Framework Core
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Unit and integration testing for endpoints
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — XML documentation comments (feed OpenAPI)
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Invoked for adding health-check, resilience, and middleware packages
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Generates typed HTTP clients for consuming these APIs
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Reviews ASP.NET Core code for security, performance, and architecture issues
diff --git a/.claude/skills/dotnet-aspnet/references/auth.md b/.claude/skills/dotnet-aspnet/references/auth.md
new file mode 100644
index 0000000..52f2641
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/auth.md
@@ -0,0 +1,26 @@
+# Authentication & Authorization
+
+## JWT Bearer Authentication
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.Authority = builder.Configuration["Auth:Authority"];
+        options.Audience = builder.Configuration["Auth:Audience"];
+    });
+```
+
+## Authorization Policies
+
+```csharp
+builder.Services.AddAuthorizationBuilder()
+    .AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"))
+    .AddPolicy("CanEditOrder", policy =>
+        policy.Requirements.Add(new OrderOwnerRequirement()));
+```
+
+- Use policy-based authorization over role checks in attributes
+- Apply `[Authorize]` at controller level, `[AllowAnonymous]` for exceptions
+- Implement `IAuthorizationHandler` for resource-based authorization
+- For minimal APIs use `.RequireAuthorization("PolicyName")`
diff --git a/.claude/skills/dotnet-aspnet/references/error-handling.md b/.claude/skills/dotnet-aspnet/references/error-handling.md
new file mode 100644
index 0000000..09282b5
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/error-handling.md
@@ -0,0 +1,44 @@
+# Error Handling
+
+## ProblemDetails (RFC 9457)
+
+```csharp
+builder.Services.AddProblemDetails(options =>
+{
+    options.CustomizeProblemDetails = ctx =>
+    {
+        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
+    };
+});
+```
+
+## Global Exception Handling (.NET 8+)
+
+```csharp
+public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(
+        HttpContext context, Exception exception, CancellationToken ct)
+    {
+        logger.LogError(exception, "Unhandled exception");
+
+        var problem = new ProblemDetails
+        {
+            Status = StatusCodes.Status500InternalServerError,
+            Title = "An error occurred",
+            Type = "https://httpstatuses.com/500"
+        };
+
+        context.Response.StatusCode = problem.Status.Value;
+        await context.Response.WriteAsJsonAsync(problem, ct);
+        return true;
+    }
+}
+
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
+```
+
+- Use `IExceptionHandler` (.NET 8+) instead of custom exception middleware
+- Map domain exceptions to appropriate HTTP status codes
+- Never expose internal exception details in production responses
+- Use `app.UseStatusCodePages()` for consistent responses on empty status codes (404, 405, etc.)
diff --git a/.claude/skills/dotnet-aspnet/references/middleware.md b/.claude/skills/dotnet-aspnet/references/middleware.md
new file mode 100644
index 0000000..9940ff3
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/middleware.md
@@ -0,0 +1,38 @@
+# Middleware Pipeline
+
+Order matters — register middleware in the correct sequence:
+
+```csharp
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+app.UseHsts();
+app.UseHttpsRedirection();
+app.UseCors();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseRateLimiter();
+app.UseOutputCache();
+app.MapControllers();
+```
+
+## Custom Middleware
+
+```csharp
+public class RequestTimingMiddleware(RequestDelegate next)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var sw = Stopwatch.StartNew();
+        context.Response.OnStarting(() =>
+        {
+            context.Response.Headers["X-Response-Time-Ms"] = sw.ElapsedMilliseconds.ToString();
+            return Task.CompletedTask;
+        });
+        await next(context);
+    }
+}
+```
+
+- Use primary constructors for middleware
+- Inject scoped services via `InvokeAsync` parameters, not the constructor
+- Keep middleware focused — one concern per middleware
diff --git a/.claude/skills/dotnet-aspnet/references/model-binding-validation.md b/.claude/skills/dotnet-aspnet/references/model-binding-validation.md
new file mode 100644
index 0000000..1023f6d
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/model-binding-validation.md
@@ -0,0 +1,71 @@
+# Model Binding & Validation
+
+ASP.NET Core-specific concerns around mapping HTTP requests onto typed arguments and validating them.
+
+## Binding Sources
+
+- Use binding source attributes explicitly: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromHeader]`, `[FromForm]`, `[FromServices]`.
+- With `[ApiController]`, the framework infers binding sources: complex types default to `[FromBody]`, simple types to `[FromRoute]` / `[FromQuery]`.
+- For minimal APIs, binding is determined by parameter type and route template; use the attributes when inference is ambiguous.
+
+```csharp
+[HttpPost]
+public IActionResult Create(
+    [FromBody] CreateOrderRequest body,
+    [FromHeader(Name = "X-Tenant-Id")] string tenantId,
+    CancellationToken ct)
+{
+    // ...
+}
+```
+
+## Data Annotation Validation
+
+```csharp
+public record CreateOrderRequest(
+    [Required] string CustomerId,
+    [Required, MinLength(1)] List<OrderItemRequest> Items);
+```
+
+- With `[ApiController]`, validation failures automatically produce a `400 Bad Request` with a `ValidationProblemDetails` body.
+- Combine with `[StringLength]`, `[Range]`, `[RegularExpression]`, `[EmailAddress]` for richer constraints.
+
+## FluentValidation
+
+For validation logic that exceeds attribute capabilities (cross-field rules, async lookups), use FluentValidation:
+
+```csharp
+public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
+{
+    public CreateOrderRequestValidator()
+    {
+        RuleFor(x => x.CustomerId).NotEmpty().Length(5, 50);
+        RuleFor(x => x.Items).NotEmpty();
+        RuleForEach(x => x.Items).SetValidator(new OrderItemRequestValidator());
+    }
+}
+
+builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderRequestValidator>();
+```
+
+Wire validators into the pipeline via an `IEndpointFilter` (minimal APIs) or a custom MVC filter that runs `IValidator<T>` and returns `ValidationProblemDetails` on failure.
+
+## ProblemDetails for Validation Errors
+
+`[ApiController]` returns `ValidationProblemDetails` (RFC 9457 extension) automatically. For minimal APIs, return it explicitly:
+
+```csharp
+app.MapPost("/orders", async (CreateOrderRequest req, IValidator<CreateOrderRequest> validator, CancellationToken ct) =>
+{
+    var result = await validator.ValidateAsync(req, ct);
+    if (!result.IsValid)
+        return Results.ValidationProblem(result.ToDictionary());
+
+    // proceed
+    return Results.Created(...);
+});
+```
+
+---
+
+**For DI lifetimes, the Options pattern, and configuration (`appsettings.json`, User Secrets, environment variables): see the [`dotnet-fundamentals`](../../dotnet-fundamentals/SKILL.md) skill.**
diff --git a/.claude/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md b/.claude/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md
new file mode 100644
index 0000000..374a6ef
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md
@@ -0,0 +1,100 @@
+# OpenAPI, Health Checks & Cross-Cutting Concerns
+
+## OpenAPI / Swagger
+
+- Use the built-in OpenAPI support (.NET 9+) or Swashbuckle/NSwag for earlier versions:
+
+```csharp
+builder.Services.AddOpenApi();
+// ...
+app.MapOpenApi();
+```
+
+- Enable XML comments in `.csproj` for automatic documentation:
+  ```xml
+  <PropertyGroup>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+  ```
+- Use `[Tags]`, `[EndpointSummary]`, `[EndpointDescription]` for metadata
+- Use `WithName()` and `WithTags()` on minimal API endpoints
+- Use the `dotnet-xmldocs` skill for writing XML documentation comments
+
+## Health Checks
+
+```csharp
+builder.Services.AddHealthChecks()
+    .AddCheck("self", () => HealthCheckResult.Healthy())
+    .AddNpgSql(connectionString, name: "database")
+    .AddRedis(redisConnectionString, name: "cache");
+
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapHealthChecks("/health/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+```
+
+- Separate liveness (`/health`) and readiness (`/health/ready`) endpoints
+- Tag health checks for selective filtering
+- Use NuGet packages `AspNetCore.HealthChecks.*` for common dependencies
+- Use the `dotnet-nuget-manager` skill for adding health check packages
+
+## CORS
+
+```csharp
+builder.Services.AddCors(options =>
+{
+    options.AddPolicy("AllowFrontend", policy =>
+        policy.WithOrigins("https://app.example.com")
+              .AllowAnyHeader()
+              .AllowAnyMethod()
+              .AllowCredentials());
+});
+
+app.UseCors("AllowFrontend");
+```
+
+## Rate Limiting (.NET 7+)
+
+```csharp
+builder.Services.AddRateLimiter(options =>
+{
+    options.AddFixedWindowLimiter("api", limiter =>
+    {
+        limiter.PermitLimit = 100;
+        limiter.Window = TimeSpan.FromMinutes(1);
+    });
+    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
+});
+
+app.UseRateLimiter();
+```
+
+- Apply per-endpoint with `[EnableRateLimiting("api")]` or `.RequireRateLimiting("api")`
+
+## Output Caching (.NET 7+)
+
+```csharp
+builder.Services.AddOutputCache(options =>
+{
+    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
+    options.AddPolicy("NoCache", builder => builder.NoCache());
+});
+```
+
+## Response Compression
+
+```csharp
+builder.Services.AddResponseCompression(options =>
+{
+    options.EnableForHttps = true;
+    options.Providers.Add<BrotliCompressionProvider>();
+    options.Providers.Add<GzipCompressionProvider>();
+});
+```
diff --git a/.claude/skills/dotnet-aspnet/references/project-and-endpoints.md b/.claude/skills/dotnet-aspnet/references/project-and-endpoints.md
new file mode 100644
index 0000000..61649e9
--- /dev/null
+++ b/.claude/skills/dotnet-aspnet/references/project-and-endpoints.md
@@ -0,0 +1,92 @@
+# Project Structure & Endpoints
+
+## Project Structure
+
+- Organize code by feature/domain, not by layer (avoid generic `Controllers/`, `Services/`, `Models/` folders)
+- Use `Program.cs` as the composition root — register services, configure middleware pipeline
+- Keep `Program.cs` lean by extracting registration into extension methods (e.g., `AddApplicationServices()`, `AddAuthenticationServices()`)
+- Use feature folders:
+  ```
+  Features/
+    Orders/
+      OrdersController.cs
+      CreateOrderRequest.cs
+      OrderResponse.cs
+      OrderService.cs
+    Products/
+      ...
+  ```
+
+## Controllers vs Minimal APIs
+
+### Controllers
+
+Use controllers for larger APIs with shared conventions, filters, and complex routing:
+
+```csharp
+[ApiController]
+[Route("api/[controller]")]
+public class OrdersController(IOrderService orderService) : ControllerBase
+{
+    [HttpGet("{id:guid}")]
+    [ProducesResponseType<OrderResponse>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
+    {
+        var order = await orderService.GetByIdAsync(id, ct);
+        return order is null ? NotFound() : Ok(order);
+    }
+}
+```
+
+- Always use `[ApiController]` attribute — enables automatic model validation, binding source inference, and ProblemDetails responses
+- Use primary constructor injection for dependencies
+- Return `IActionResult` or `ActionResult<T>` for endpoints with multiple response types
+- Accept `CancellationToken` on all async endpoints
+
+### Minimal APIs
+
+Use minimal APIs for simple endpoints, microservices, or when startup performance matters:
+
+```csharp
+var group = app.MapGroup("/api/orders")
+    .WithTags("Orders")
+    .RequireAuthorization();
+
+group.MapGet("/{id:guid}", async (Guid id, IOrderService service, CancellationToken ct) =>
+{
+    var order = await service.GetByIdAsync(id, ct);
+    return order is null ? Results.NotFound() : Results.Ok(order);
+})
+.WithName("GetOrderById")
+.Produces<OrderResponse>()
+.ProducesProblem(StatusCodes.Status404NotFound);
+```
+
+- Use `MapGroup()` to share route prefixes, filters, and metadata
+- Use `TypedResults` instead of `Results` for compile-time response type verification
+- Add `.WithName()` for OpenAPI operation IDs and link generation
+- Use endpoint filters for cross-cutting concerns
+
+## Routing & Endpoints
+
+- Use attribute routing on controllers (`[Route]`, `[HttpGet]`, etc.)
+- Apply route constraints: `{id:guid}`, `{page:int:min(1)}`, `{slug:regex(^[a-z-]+$)}`
+- Use API versioning via URL segment (`/api/v1/orders`) or header-based versioning with `Asp.Versioning.Http`
+- Keep route templates consistent — plural nouns for resources (`/api/orders`, not `/api/order`)
+- Use `LinkGenerator` for generating URLs to named endpoints
+
+## API Conventions & Response Types
+
+- Annotate endpoints with `[ProducesResponseType]` for OpenAPI documentation
+- Use `[Consumes]` and `[Produces]` for content type negotiation
+- Return consistent response envelopes or use ProblemDetails for errors
+- Use `TypedResults` in minimal APIs for compile-time response verification:
+
+```csharp
+group.MapPost("/", async (CreateOrderRequest req, IOrderService service, CancellationToken ct) =>
+{
+    var id = await service.CreateAsync(req, ct);
+    return TypedResults.Created($"/api/orders/{id}", new { id });
+});
+```
diff --git a/.claude/skills/dotnet-dev/SKILL.md b/.claude/skills/dotnet-dev/SKILL.md
new file mode 100644
index 0000000..db23ff4
--- /dev/null
+++ b/.claude/skills/dotnet-dev/SKILL.md
@@ -0,0 +1,312 @@
+---
+name: dotnet-dev
+description: >
+  Use when asked to implement, extend, or change a feature, user story,
+  requirement, or bug fix in a .NET / C# project — any task that produces or
+  modifies C# production code, tests, or documentation. Use when a .NET change
+  request arrives, before writing any code.
+---
+
+# dotnet-dev — Comprehensive C# Requirement Implementation
+
+A strict, gated workflow for implementing requirements end-to-end in .NET / C#.
+Every phase ends in a confirmation gate; every applicable `dotnet-*` skill is a
+mandatory binding. The workflow exists to survive exactly the conditions —
+deadlines, "trivial" framing, "skip the ceremony" — under which it is most
+tempting to abandon.
+
+## Core Principle
+
+**Violating the letter of this workflow is violating its spirit.** The phases,
+gates, point-by-point clarification, and skill bindings are not ceremony to be
+proportioned to task size. They are the work. A one-line endpoint runs the same
+workflow as a subsystem — at speed, never collapsed.
+
+## CRITICAL RULES (read before every phase)
+
+1. **NO COMMITS.** Never run `git commit`, `git add -A`/`.`, branch, tag, or
+   push. The user commits manually. If asked to commit, skip it and say so.
+
+2. **URGENCY AND TRIVIALITY WAIVE NOTHING.** "It's trivial", "I'm in a hurry",
+   "demo in 30 minutes", "skip the clarification dance", "no need for the full
+   process", "just bang it out", "one pass is fine" are NOT permission to skip a
+   phase, a gate, a clarification point, or a skill binding. Acknowledge the
+   deadline, then run the workflow **at speed** — do not shrink it. The only
+   lawful way to reduce a binding's work is an objective `n/a` (see below);
+   user preference, pressure, and perceived size are never valid `n/a` reasons.
+   An explicit, informed user waiver is a different thing from pressure — see
+   *Waiver vs. `n/a` vs. silent skip*.
+
+3. **EVERY PHASE ENDS IN A CONFIRMATION GATE.** At the end of each phase you
+   MUST present a summary and STOP. Do not start the next phase until the user
+   explicitly confirms. **Batching is a violation** — you may not present
+   multiple phases at once, "pre-run" the next phase, or ask for one combined
+   confirmation at the end. One phase → one summary → one wait.
+
+4. **`dotnet-*` SKILLS ARE MANDATORY BINDINGS.** When a binding applies, you
+   MUST invoke that skill via the `Skill` tool, in this conversation, for this
+   task, **before** producing the corresponding artifact. Listing it,
+   paraphrasing it, "knowing it already", or having invoked it for a previous
+   task does NOT count. Invocation must shape the artifact, not certify it
+   afterward.
+
+## Phase Flow
+
+```
+Phase 1: Requirement Review              → GATE
+Phase 2: Clarification (8 points)        → GATE
+Phase 3: Task Breakdown                  → GATE
+Phase 4: Implementation + App Smoke-Check ◄──┐  → GATE
+Phase 5: Code Review (dotnet-reviewer)       │
+   └─ rework needed? ───────────────────────►┘
+   └─ all good → GATE
+Phase 6: Final Summary
+```
+
+## Skill Map — Mandatory Bindings
+
+| Binding | Skill | Applies in | When |
+|---|---|---|---|
+| Core C# / DI / Options / config / modern C# idioms | `dotnet-fundamentals` | Phase 4 | always, for production code |
+| ASP.NET Core (controllers, minimal APIs, middleware, auth, ProblemDetails, OpenAPI) | `dotnet-aspnet` | Phase 4 | when ASP.NET Core is touched |
+| EF Core (DbContext, entities, LINQ, migrations) | `dotnet-ef-core` | Phase 4 | when EF Core is touched |
+| SDK / typed HTTP client generation | `dotnet-sdk-builder` | Phase 4 | when building a typed SDK / client |
+| External / platform / NuGet API surface lookup | `dotnet-inspect` | Phase 1, 4 | when an external/platform API is involved |
+| Tests | `dotnet-tester` | Phase 4 | always, when code is written or changed |
+| XML documentation | `dotnet-xmldocs` | Phase 4 | for any public API addition/change |
+| NuGet packages | `dotnet-nuget-manager` | Phase 4 | any package add/remove/version change |
+| Code review | `dotnet-reviewer` | Phase 5 | always |
+| Router (tie-breaker) | `dotnet` | any | when the right sub-skill is not obvious |
+
+**Correct names matter:** `dotnet-ef-core` and `dotnet-nuget-manager` (not
+`ef-core` / `nuget-manager`). A binding is fulfilled only when its skill has
+fired via the `Skill` tool for this task. A binding applies whether you do the
+work yourself or dispatch a sub-agent — self-execution never waives it, and a
+sub-agent's invocation never waives the main agent's own follow-up edits.
+
+**Tooling:** for code navigation/exploration follow the project + global rules
+(Serena first, then tokensave; built-in/`Explore` agents only in the documented
+carve-outs). Do NOT use `Explore` agents for code research when tokensave is
+available.
+
+---
+
+## Phase 1 — Requirement Review
+
+1. Read the requirement. Extract explicit AND implicit acceptance criteria.
+2. **Find gaps, contradictions, and open questions** — list them explicitly. A
+   review that surfaces no gaps on an ambiguous requirement is a failure; if the
+   requirement truly is unambiguous, say so explicitly rather than skipping.
+3. Analyze scope: affected `*.csproj`, components, files; existing tests/docs.
+4. Read `CLAUDE.md`, `AGENTS.md`, `.editorconfig`, `Directory.Build.props`,
+   `Directory.Packages.props` and follow the conventions found.
+5. Invoke `dotnet-inspect` if any external/platform API surface must be verified.
+6. **Determine the preliminary Skill Map** for this task and show it as a table.
+
+**GATE 1 — STOP.** Present: requirement restated, acceptance criteria,
+gaps/contradictions/open questions, affected scope, and the preliminary Skill
+Map table. Wait for confirmation.
+
+## Phase 2 — Clarification (8 points, one round-trip per point)
+
+Clarify the following **one point at a time** — present point _N_, propose a
+concrete default/assumption, ask the open question, and **wait for the user's
+answer before moving to point _N+1_.** You may NOT batch points into one
+message, NOR skip a point silently. A point that objectively does not apply is
+presented with `n/a — <code-referenced reason>` and still acknowledged.
+
+| # | Item | Must clarify |
+|---|---|---|
+| 1 | Project & folder structure | Target `*.csproj`, namespace, folder layout, new projects yes/no |
+| 2 | Architecture & layering | Layers (controller/service/repo or vertical slice), DI lifetimes, public vs internal surface |
+| 3 | Naming conventions | Type/method/file/namespace names, suffixes (`Service`, `Handler`, `Options`, `Async`), test naming |
+| 4 | Public API / contracts | DTO shape, request/response, ProblemDetails, versioning, OpenAPI annotations |
+| 5 | Errors & edge cases | Exception strategy, Result vs throws, validation style, logging granularity |
+| 6 | Test strategy | Unit and/or integration, mock boundaries, naming, fakes vs real dependencies, coverage expectation |
+| 7 | Persistence / EF Core | Entity shape, migrations yes/no, owned types, indexes, query style (LINQ vs spec) |
+| 8 | Dependencies / NuGet | Allowed/forbidden packages, Central Package Management versions |
+
+**GATE 2 — STOP.** Present: every clarified decision (all 8 points) and the
+**finalized** Skill Map (updated from the answers — e.g. points 7/8 confirm
+`dotnet-ef-core` / `dotnet-nuget-manager`). Wait for confirmation.
+
+## Phase 3 — Task Breakdown
+
+1. Break the requirement into discrete implementation tasks.
+2. Each task covers **production code + tests + documentation**.
+3. **Each task publishes a Skill-prerequisite checklist** (from the Skill Map):
+
+   ```
+   Task #N: <subject>
+     Skill prerequisites:
+       [ ] dotnet-fundamentals
+       [ ] dotnet-aspnet
+       [ ] dotnet-tester
+       [ ] dotnet-xmldocs
+   ```
+
+4. Define dependencies and which tasks may run in parallel via sub-agents.
+
+**GATE 3 — STOP.** Present the task list with per-task checklists, dependency
+order, and parallelization. Wait for confirmation.
+
+## Phase 4 — Implementation + App Smoke-Check
+
+For each task (or parallel group):
+
+1. **Step 0 — invoke every required `dotnet-*` skill for this task** before any
+   `Write`/`Edit`/code-producing `Bash`. One `Skill(...)` call per binding, no
+   collapsing. Re-invoke per task; previous-task invocations do not carry over.
+   Then follow each skill's workflow when producing its artifact.
+2. Implement production code (`dotnet-fundamentals` + stack skill), tests
+   (`dotnet-tester`), XML docs (`dotnet-xmldocs`), package changes
+   (`dotnet-nuget-manager`).
+3. Run `dotnet build` and the test suite. Fix failures.
+4. **App Smoke-Check** — if a runnable application exists, start it and verify
+   it actually runs:
+   - **Applies when** the solution has an executable project (`OutputType=Exe`,
+     ASP.NET Core Web/API, Worker Service). **`n/a` only when** the solution is
+     library-only (no executable project) — state that as the reason.
+   - Start the app **in the background** (a server does not exit on its own),
+     check startup logs / health endpoint / a representative request, then shut
+     it down cleanly. Never block on a foreground long-running process.
+
+**GATE 4 — STOP.** Present implemented tasks, build/test result, and the
+App-Smoke-Check outcome (or its `n/a` reason). Wait for confirmation.
+
+## Phase 5 — Code Review
+
+1. Launch a code-review **sub-agent** that uses `dotnet-reviewer`. Invoke
+   `dotnet-reviewer` via the `Skill` tool in the main conversation **and** pass
+   it to the sub-agent prompt. Inline self-review does NOT satisfy this phase —
+   `dotnet-reviewer` produces a severity-tagged Markdown report under
+   `docs/reviews/`.
+2. Evaluate findings:
+   - **Rework needed** → create new tasks (each with its own Skill checklist)
+     and return to **Phase 4**. After fixing, re-run Phase 5 (rework loop).
+   - **All good** → proceed.
+
+**GATE 5 — STOP.** Present the review findings, the report path, and your
+rework/no-rework decision. Wait for confirmation.
+
+## Phase 6 — Final Summary
+
+1. Files created/modified; what was implemented and why.
+2. Tests added/updated; documentation changes; package changes.
+3. Decisions/trade-offs; anything the user should verify before committing.
+4. **Skill-Invocation Log** (mandatory audit trail — see below).
+5. Reminder: *the user commits; this workflow creates no commits.*
+
+---
+
+## `n/a` Criteria — Strict
+
+A binding or clarification point may be `n/a` **only** when an objective
+technical fact makes the work empty for this task. Valid reasons cite the
+codebase, never the user:
+
+- ✅ `n/a — task touches no public API members (internal sealed class)` — `dotnet-xmldocs`
+- ✅ `n/a — no NuGet package added/removed/version-changed` — `dotnet-nuget-manager`
+- ✅ `n/a — solution is library-only, no executable project` — App Smoke-Check
+- ✅ `n/a — scanned changed files; no DbContext/IQueryable/migration` — `dotnet-ef-core`
+- ❌ NOT valid: `n/a — user said no tests`
+- ❌ NOT valid: `n/a — too small / trivial / one-liner / just a lambda`
+- ❌ NOT valid: `n/a — single ToListAsync, doesn't need the skill`
+- ❌ NOT valid: `n/a — no test project exists` (creating it is part of the task)
+- ❌ NOT valid: `n/a — demo, no time`
+
+If you cannot phrase the reason as "no `<artifact>` exists in this task because
+`<code-referenced fact>`", it is NOT `n/a` — invoke the skill and do the work.
+
+**No avoidance-driven `n/a`.** You may not reshape the implementation to escape
+a binding — e.g. hand-rolling code to dodge `dotnet-nuget-manager`, inlining a
+public member to dodge `dotnet-xmldocs`, or collapsing a service into private
+code to dodge `dotnet-tester`. The binding follows the natural shape of the
+work, not a shape chosen to minimise bindings.
+
+## Waiver vs. `n/a` vs. silent skip
+
+Three distinct cases — keep them apart. Conflating them is how the workflow
+silently collapses.
+
+- **Implicit pressure** — "it's trivial", "I'm in a hurry", "demo in 30
+  minutes", "skip the ceremony", "this is how we work here", "nobody runs all
+  this". **Waives NOTHING.** Acknowledge it and run the full workflow at speed.
+  These are exactly the conditions the workflow exists to survive (CRITICAL
+  RULE 2). Treat them as no-ops on scope.
+
+- **Explicit, informed user waiver** — the user, *after being told what the step
+  protects and what gap skipping it creates*, directly says "skip phase X / the
+  gates / the clarification / the tests / the review." This **may be honored**
+  (your global rule: explicit user instructions take precedence), but only on
+  these terms:
+  1. **State the cost first.** Name what the skipped step would have caught
+     before you skip it. No silent compliance.
+  2. **Record it as a waiver, never as `n/a`.** A waiver means "the user chose
+     to skip this"; `n/a` means "the work is objectively empty." Stamping `n/a`
+     on a waived step makes the audit trail lie about *why* it was skipped.
+     Log it as: `waived — explicit user instruction (<who>, <when>); not a
+     technical n/a; gap: <what is now uncovered>`.
+  3. **Some steps still run regardless.** Invoking the relevant `dotnet-*`
+     skills before writing code costs the user nothing and keeps the code
+     matching repo conventions — keep them even under a waiver.
+
+- **Objective `n/a`** — the work is empty for a code-referenced reason (see
+  `n/a` Criteria). This is the only state that requires no user sign-off.
+
+**The line:** vague urgency is not a waiver. A waiver is the user explicitly
+electing to skip a *named* step after hearing its cost. When in doubt, ask the
+user to confirm the waiver explicitly — do not infer one from pressure.
+
+## Artifact-Substance Bar
+
+Invoking a skill is necessary but not sufficient — the artifact must reflect it:
+
+- A test that asserts nothing about the change (`Assert.True(true)`, a smoke
+  test with no behavioral assertion) does not satisfy `dotnet-tester`.
+- Empty `<summary />` or name-echoing docs do not satisfy `dotnet-xmldocs`.
+- Hand-editing `<PackageReference>` after "invoking" `dotnet-nuget-manager` does
+  not satisfy it — use the `dotnet` CLI as the skill prescribes.
+- A "review" with no `docs/reviews/` report does not satisfy `dotnet-reviewer`.
+
+If an artifact misses the bar, the binding is `[!]`, not `[x]`.
+
+## Skill-Invocation Log (Phase 6)
+
+Reproduce each task's checklist, every entry resolved with evidence:
+
+- `[x] <skill> — invoked at <evidence>` — a verifiable ordered turn (e.g.
+  "before Write of `UsersController.cs`"). "Considered"/"applied" is not
+  evidence. Invocation AFTER the artifact is `[!]`, not `[x]`.
+- `[n/a] <skill> — did not apply (<code-referenced reason>)`.
+- `[!] <skill> — NOT invoked` — a violation. `[!]` is **not a shipping path**:
+  name it, mark the task INCOMPLETE, STOP, and offer to re-enter Phase 4 to run
+  the missing skill's workflow on the artifact. Phase 6 does not complete while
+  any `[!]` is present.
+
+## Red Flags — STOP and run the workflow
+
+| Rationalization | Reality |
+|---|---|
+| "It's trivial / one endpoint — phases & gates are overkill" | Size does not scale the workflow. Run all phases at speed. Gate after each. |
+| "Demo in 30 min / I'm in a hurry — one pass, no gates" | Urgency waives nothing (CRITICAL RULE 2). Acknowledge the deadline, keep the gates. |
+| "Lead waived the clarification dance" | The 8 points are mandatory, one round-trip each. User waiver is not a valid skip. |
+| "Ambiguities aren't blocking — I'll state assumptions instead of asking" | Stating assumptions ≠ clarifying. Present each point and wait for the answer. |
+| "I'll batch all phases / ask one combined confirmation" | Batching is a gate violation. One phase → one summary → one wait. |
+| "This is a single ToListAsync — `dotnet-ef-core` isn't needed" | Touching EF Core triggers the binding regardless of LINQ simplicity. Invoke it. |
+| "Not a public library API, so skip `dotnet-xmldocs`" | `n/a` only for objectively internal members. Public additions/changes go through it. |
+| "User said no tests" | User preference is not a valid `n/a`. Either an objective code-referenced `n/a` exists or `dotnet-tester` is required; if the user insists, name it as a violation and let them decide. |
+| "I'll self-review the diff inline instead of `dotnet-reviewer`" | Phase 5 requires the `dotnet-reviewer` sub-agent + `docs/reviews/` report. Inline self-review does not satisfy it. |
+| "I'll hand-roll it to avoid adding a package" | Avoidance-driven `n/a` is forbidden. The binding follows the natural shape of the work. |
+| "The owner told me to skip it — I'll mark those steps `n/a`" | A waiver is not an `n/a`. Honor an explicit informed waiver if given, but record it as `waived — user instruction`, never `n/a`, never silently. See *Waiver vs. `n/a`*. |
+| "They pushed back / 'nobody does this here' — the workflow is waived" | Pushback, urgency, and social proof are not waivers. Only an explicit, informed skip of a *named* step counts. Vague urgency waives nothing — run at speed. |
+| "I already know C# / the skill — invoking is ceremony" | Skills encode project conventions and modern idioms. Knowing ≠ invoking. Invoke it. |
+| "The skill was invoked last task" | Invocations do not carry over. Re-invoke per task. |
+| "The sub-agent invoked it — covers my own edits" | It does not. Re-invoke before your own follow-up Write/Edit. |
+| "I'll log the `Skill(...)` call even though I ran it after the Write" | Evidence must be a real ordered turn. After-the-fact is `[!]`, not `[x]`. |
+| "No executable project, but I'll skip the App-Smoke-Check check anyway" | Decide it explicitly: run it, or mark `n/a — library-only`. Don't drop it silently. |
+
+---
+
+For detailed per-phase guidance, see
+[references/REFERENCE.md](references/REFERENCE.md).
diff --git a/.claude/skills/dotnet-dev/references/REFERENCE.md b/.claude/skills/dotnet-dev/references/REFERENCE.md
new file mode 100644
index 0000000..4cd3787
--- /dev/null
+++ b/.claude/skills/dotnet-dev/references/REFERENCE.md
@@ -0,0 +1,209 @@
+# dotnet-dev — Detailed Reference
+
+In-depth guidance per phase. Assumes a .NET / C# project. The Skill Map and the
+CRITICAL RULES in `SKILL.md` are authoritative; this document expands the *how*.
+
+---
+
+## Phase 1 — Requirement Review (Detail)
+
+### Goal
+Understand the requirement fully before any code is written, and surface every
+gap before they become rework.
+
+### Steps
+1. **Read the requirement** (issue, story, ticket, message). Identify the core
+   objective and expected outcome.
+2. **Acceptance criteria** — explicit (stated) and implicit (existing tests must
+   still pass, API contracts honored, public additions need XML docs, existing
+   conventions respected).
+3. **Gaps / contradictions / open questions** — write them down. Watch for:
+   - Scope boundaries (what is in / out).
+   - Error-handling behavior (`ProblemDetails`? typed exceptions? Result?).
+   - Backward compatibility (API surface, EF Core migrations).
+   - Target-framework / performance constraints.
+   - Contradictions between the request and existing code/conventions.
+4. **Codebase analysis** — affected `*.csproj`, host type (ASP.NET Core, Worker,
+   Console, MAUI), data layer (EF Core), cross-cutting (DI, Options, Serilog).
+   Locate existing tests (`*.Tests`) and docs. Read `Directory.Build.props`,
+   `Directory.Packages.props`, `.editorconfig`, `nuget.config`. Use Serena /
+   tokensave per project + global tooling rules — not `Explore` agents when
+   tokensave is available.
+5. **`dotnet-inspect`** — invoke whenever an external/platform/NuGet API surface
+   must be verified (types, members, version diffs, extension methods).
+6. **Preliminary Skill Map** — from the requirement, list which bindings the
+   work will touch. It is *preliminary*: persistence (point 7) and dependencies
+   (point 8) are confirmed in Phase 2 and may add `dotnet-ef-core` /
+   `dotnet-nuget-manager`.
+
+### GATE 1 output
+Requirement restated in your words · acceptance criteria · gaps/contradictions/
+open questions · affected scope · preliminary Skill Map table. **Wait.**
+
+---
+
+## Phase 2 — Clarification (Detail)
+
+### Goal
+Resolve the 8 standard implementation dimensions, one at a time, so nothing is
+silently assumed.
+
+### Protocol
+- **One point per message.** Present point _N_: a concrete proposed default,
+  then the open question. Wait for the answer before point _N+1_.
+- **No batching, no skipping.** A point that objectively does not apply is shown
+  with `n/a — <code-referenced reason>` and still acknowledged before moving on.
+- Pre-filling a sensible default is encouraged — it lets the user reply "ok"
+  fast — but the default never replaces the round-trip.
+
+### The 8 points (expanded prompts)
+1. **Project & folder structure** — which `*.csproj`, namespace, folder layout;
+   new projects yes/no.
+2. **Architecture & layering** — controller/service/repo vs vertical slice; DI
+   lifetimes (singleton/scoped/transient); public vs internal surface.
+3. **Naming conventions** — type/method/file/namespace names; suffixes
+   (`Service`, `Handler`, `Options`, `Async`); test naming pattern.
+4. **Public API / contracts** — DTO shape, request/response, `ProblemDetails`,
+   versioning, OpenAPI annotations.
+5. **Errors & edge cases** — exception strategy, Result vs throws, validation
+   style, logging granularity.
+6. **Test strategy** — unit and/or integration, mock boundaries, naming, fakes
+   vs real dependencies, coverage expectation.
+7. **Persistence / EF Core** — entity shape, migrations yes/no, owned types,
+   indexes, query style (LINQ vs spec). Confirms `dotnet-ef-core`.
+8. **Dependencies / NuGet** — allowed/forbidden packages, Central Package
+   Management versions. Confirms `dotnet-nuget-manager`.
+
+### GATE 2 output
+All 8 clarified decisions · the **finalized** Skill Map. **Wait.**
+
+---
+
+## Phase 3 — Task Breakdown (Detail)
+
+### Goal
+A trackable plan of discrete tasks, each self-contained.
+
+### Steps
+- Break into the smallest reasonable tasks; descriptive IDs; enough detail to
+  execute without re-reading the plan.
+- Each task addresses **production code + tests + documentation**.
+- Each task publishes its **Skill-prerequisite checklist** from the Skill Map.
+- Dependencies — common .NET order: entities → EF Core config/migrations →
+  repositories/services → controllers/endpoints; DTOs before consumers; package
+  changes before code using them.
+- Parallelization — group independent tasks for sub-agents; do not parallelize
+  migration/schema work with other EF Core work.
+
+### GATE 3 output
+Task list with per-task checklists · dependency order · parallel groups. **Wait.**
+
+---
+
+## Phase 4 — Implementation + App Smoke-Check (Detail)
+
+### Step 0 — Skill invocation (per task)
+Before any `Write`/`Edit`/code-producing `Bash` for the task, invoke each
+required binding once via the `Skill` tool. A task touching code + tests + docs
+is at least three calls (`dotnet-fundamentals` + `dotnet-tester` +
+`dotnet-xmldocs`) plus stack skills and `dotnet-nuget-manager` if packages
+change. Wait for each skill's content; follow its workflow when producing the
+artifact. Sub-agent dispatch is in addition to Step 0, not a substitute — pass
+the skills explicitly to the sub-agent (sub-agents are stateless).
+
+### Production code
+`dotnet-fundamentals` always; plus `dotnet-aspnet` (web), `dotnet-ef-core` (EF),
+`dotnet-sdk-builder` (typed SDK/HTTP client), `dotnet-inspect` (verify external
+API). Apply project conventions: `Ensure.*` guards, primary constructors,
+nullable reference types, `CancellationToken` propagation, `.ConfigureAwait(false)`
+in library code (not in tests), never `.Result`/`.Wait()`/`.GetAwaiter().GetResult()`.
+
+### Tests
+`dotnet-tester` always when code is written/changed — xUnit + FakeItEasy +
+AwesomeAssertions, plus its second-agent missing-case pass. Cover new/changed
+behavior and the edge cases from Phase 1.
+
+### Documentation
+`dotnet-xmldocs` for every public API addition/change.
+
+### Build & dependencies
+`dotnet-nuget-manager` for any package add/remove/version change (enforces the
+`dotnet` CLI and `Directory.Packages.props`). Then `dotnet build` + `dotnet test`;
+fix failures before the gate.
+
+### App Smoke-Check
+- **Applies** when an executable project exists (`OutputType=Exe`, ASP.NET Core
+  Web/API, Worker Service). **`n/a`** only when library-only.
+- Start in the **background** (servers do not self-exit). Verify startup logs /
+  health endpoint / one representative request. Shut down cleanly. Never block
+  on a foreground long-running process.
+
+### GATE 4 output
+Implemented tasks · build/test result · App-Smoke-Check outcome (or `n/a`
+reason). **Wait.**
+
+---
+
+## Phase 5 — Code Review (Detail)
+
+### Steps
+- Launch a code-review **sub-agent** instructed to invoke `dotnet-reviewer`;
+  also invoke `dotnet-reviewer` in the main conversation. The skill reviews
+  working-tree or branch-vs-`main` changes and writes a severity-tagged Markdown
+  report under `docs/reviews/`.
+- Review covers: correctness/completeness vs requirement, test coverage, doc
+  accuracy, code quality/bugs/security, .NET idioms, convention consistency.
+
+### Evaluate findings
+- **No / minor issues** → fix directly (still invoking the required skills
+  before edits), then gate.
+- **Significant issues** → new tasks (each with its Skill checklist) → return to
+  Phase 4 → re-run Phase 5. If the same issue recurs after 2 cycles, consult the
+  user.
+
+### GATE 5 output
+Findings · report path · rework/no-rework decision. **Wait.**
+
+---
+
+## Phase 6 — Final Summary (Detail)
+
+1. **Requirement** restated briefly.
+2. **Files** created/modified.
+3. **Implementation details** and key design decisions.
+4. **Tests** added/updated and what they cover.
+5. **Documentation** changes (XML docs, READMEs).
+6. **Package changes** (cross-reference `Directory.Packages.props`).
+7. **Decisions / trade-offs.**
+8. **Review notes** — key `dotnet-reviewer` points + report link.
+9. **Things to check** before committing.
+10. **Skill-Invocation Log** — every task's checklist resolved to `[x]`/`[n/a]`/
+    `[!]` with evidence (see `SKILL.md`). Mandatory even when all bindings were
+    correct — it is the audit trail.
+
+End with: *All changes are ready for your review. Commit them yourself when
+satisfied — this workflow creates no commits.*
+
+---
+
+## General Guidelines
+
+### Sub-agents
+- Provide complete context (stateless). Pass the relevant `dotnet-*` skills in
+  the prompt. Use a build/test runner for `dotnet build`/`dotnet test`. Prefer
+  small focused tasks; launch independent tasks in parallel.
+- For code research, follow the project + global tooling rules (Serena →
+  tokensave → built-in; no `Explore` agents when tokensave is available).
+
+### Git
+- NEVER `git commit`, `git add -A`/`.`, branch, tag, or push. Read-only git
+  (`diff`/`status`/`log`) is fine. Stage by name only when explicitly asked;
+  refuse secret-like files (`.env`, `credentials.json`, `*.pem`).
+- If a commit is requested, skip it: *"Committing is your responsibility."*
+
+### Project conventions
+- Honor `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`,
+  `.editorconfig`, `Directory.Build.props`, `Directory.Packages.props`.
+- `Ensure.NotNull(...)` / `Ensure.IsNotNullOrEmpty(...)` /
+  `Ensure.IsNotNullOrWhitespace(...)` from `CreativeCoders.Core` for argument
+  guards in libraries.
diff --git a/.claude/skills/dotnet-ef-core/SKILL.md b/.claude/skills/dotnet-ef-core/SKILL.md
new file mode 100644
index 0000000..10ba55d
--- /dev/null
+++ b/.claude/skills/dotnet-ef-core/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: dotnet-ef-core
+description: Applies Entity Framework Core best practices for .NET projects. Use when designing DbContext, creating entities or relationships, writing LINQ queries, managing migrations, implementing repository patterns, or troubleshooting N+1 queries and performance issues with EF Core.
+---
+
+# Entity Framework Core Best Practices
+
+## When to Use
+
+- Designing or restructuring a `DbContext`, entities, or relationships
+- Writing LINQ queries against EF Core, or troubleshooting N+1 / performance issues
+- Creating, naming, or reviewing EF Core migrations
+- Implementing concurrency control, repository patterns, or change tracking strategies
+- Setting up EF Core tests with SQLite in-memory or Testcontainers
+
+## Data Context Design
+
+- Keep DbContext classes focused and cohesive
+- Use constructor injection for configuration options
+- Override OnModelCreating for fluent API configuration
+- Separate entity configurations using IEntityTypeConfiguration
+- Consider using DbContextFactory pattern for console apps or tests
+
+## Entity Design
+
+- Use meaningful primary keys (consider natural vs surrogate keys)
+- Implement proper relationships (one-to-one, one-to-many, many-to-many)
+- Use data annotations or fluent API for constraints and validations
+- Implement appropriate navigational properties
+- Consider using owned entity types for value objects
+
+## Performance
+
+- Use AsNoTracking() for read-only queries
+- Implement pagination for large result sets with Skip() and Take()
+- Use Include() to eager load related entities when needed
+- Consider projection (Select) to retrieve only required fields
+- Use compiled queries for frequently executed queries
+- Avoid N+1 query problems by properly including related data
+
+## Migrations
+
+- Create small, focused migrations
+- Name migrations descriptively
+- Verify migration SQL scripts before applying to production
+- Consider using migration bundles for deployment
+- Add data seeding through migrations when appropriate
+
+## Querying
+
+- Use IQueryable judiciously and understand when queries execute
+- Prefer strongly-typed LINQ queries over raw SQL
+- Use appropriate query operators (Where, OrderBy, GroupBy)
+- Consider database functions for complex operations
+- Implement specifications pattern for reusable queries
+
+## Change Tracking & Saving
+
+- Use appropriate change tracking strategies
+- Batch your SaveChanges() calls
+- Implement concurrency control for multi-user scenarios (see below)
+- Consider using transactions for multiple operations
+- Use appropriate DbContext lifetimes (scoped for web apps)
+
+### Concurrency Control
+
+See [concurrency-control.md](./references/concurrency-control.md) for `[Timestamp]`, `[ConcurrencyCheck]`, fluent API configuration, and `DbUpdateConcurrencyException` handling patterns.
+
+## Security
+
+- Use parameterized queries to prevent SQL injection
+- Implement appropriate data access permissions
+- Be careful with raw SQL queries
+- Consider data encryption for sensitive information
+- Use migrations to manage database user permissions
+
+## Testing
+
+- Avoid the EF Core In-Memory provider for tests — it does not enforce constraints, referential integrity, or transactions, so tests can pass while real database behavior fails
+- Use **SQLite in-memory mode** for lightweight unit and integration tests that need realistic SQL semantics:
+  ```csharp
+  var connection = new SqliteConnection("DataSource=:memory:");
+  connection.Open();
+  var options = new DbContextOptionsBuilder<AppDbContext>()
+      .UseSqlite(connection)
+      .Options;
+  ```
+- Use **Testcontainers** for integration tests that must match production database behavior (e.g., PostgreSQL, SQL Server):
+  ```csharp
+  var container = new PostgreSqlBuilder().Build();
+  await container.StartAsync();
+  var options = new DbContextOptionsBuilder<AppDbContext>()
+      .UseNpgsql(container.GetConnectionString())
+      .Options;
+  ```
+- Mock DbContext and DbSet only for pure unit tests that do not execute queries
+- Test migrations in isolated environments
+- Consider snapshot testing for model changes
+- Use the `dotnet-tester` skill for generating unit and integration tests after schema changes
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — DI lifetimes for `DbContext`, Options pattern for connection strings, modern C# idioms used in entity types
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Generates DbContext-backed unit and integration tests (SQLite in-memory, Testcontainers)
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Wires EF Core into ASP.NET Core via DI (scoped DbContext lifetimes)
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Reviews EF Core data-access code for performance and security issues
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Adds EF Core providers, Testcontainers, and SQLite packages
diff --git a/.claude/skills/dotnet-ef-core/references/concurrency-control.md b/.claude/skills/dotnet-ef-core/references/concurrency-control.md
new file mode 100644
index 0000000..5720098
--- /dev/null
+++ b/.claude/skills/dotnet-ef-core/references/concurrency-control.md
@@ -0,0 +1,52 @@
+# Concurrency Control
+
+Use `[Timestamp]` for automatic row-version concurrency (SQL Server / PostgreSQL with `rowversion` or `xmin`):
+
+```csharp
+public class Order
+{
+    public int Id { get; set; }
+    public string Status { get; set; } = string.Empty;
+
+    [Timestamp]
+    public byte[] RowVersion { get; set; } = [];
+}
+```
+
+Use `[ConcurrencyCheck]` to protect individual properties without a row version column:
+
+```csharp
+public class Product
+{
+    public int Id { get; set; }
+
+    [ConcurrencyCheck]
+    public decimal Price { get; set; }
+}
+```
+
+Or configure via fluent API:
+
+```csharp
+modelBuilder.Entity<Order>()
+    .Property(o => o.RowVersion)
+    .IsRowVersion();
+
+modelBuilder.Entity<Product>()
+    .Property(p => p.Price)
+    .IsConcurrencyToken();
+```
+
+Catch `DbUpdateConcurrencyException` at the call site and implement a retry or conflict-resolution strategy:
+
+```csharp
+try
+{
+    await context.SaveChangesAsync();
+}
+catch (DbUpdateConcurrencyException ex)
+{
+    // Reload the entity and resolve the conflict, or inform the user
+    await ex.Entries.Single().ReloadAsync();
+}
+```
diff --git a/.claude/skills/dotnet-fundamentals/SKILL.md b/.claude/skills/dotnet-fundamentals/SKILL.md
new file mode 100644
index 0000000..3a643cd
--- /dev/null
+++ b/.claude/skills/dotnet-fundamentals/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: dotnet-fundamentals
+description: Applies modern .NET fundamentals — dependency injection, Options pattern, configuration, and modern C# idioms. Use when registering services in any .NET host (ASP.NET Core, Worker Service, Console, MAUI), binding configuration with IOptions<T>, choosing DI lifetimes, configuring appsettings.json / User Secrets / environment variables, or applying primary constructors, required properties, nullable reference types, and CancellationToken propagation.
+---
+
+# Modern .NET Fundamentals
+
+## When to Use
+
+- Working with .NET/C# Code
+- Registering services in any `IServiceCollection` (ASP.NET Core, Worker Service, Console app, MAUI, library DI extension methods)
+- Choosing a DI lifetime (Transient, Scoped, Singleton) or registering keyed services (.NET 8+)
+- Binding configuration sections to a strongly-typed Options class
+- Setting up `appsettings.json`, environment-specific overrides, User Secrets, or environment variables
+- Adopting primary constructors, `required` properties, nullable reference types, or `CancellationToken` propagation in new code
+
+## Core Principles
+
+- This skill is **technology-agnostic across .NET hosts**. ASP.NET Core, EF Core, and SDK builders all sit on top of these fundamentals.
+- **Interface-first registration** — register services via their abstraction (`AddScoped<IFoo, Foo>()`), not the concrete type. Enables substitution and testing.
+- **No service locator** — never inject `IServiceProvider` into business logic. Constructor-inject the dependencies you actually need.
+- **Options over constructor parameters for configuration** — bind config sections to `IOptions<T>`, do not pass raw `IConfiguration` values around.
+- **Fail fast** — use `ValidateDataAnnotations().ValidateOnStart()` so misconfiguration surfaces at startup, not at first use.
+- **Immutable configuration** — Options classes use `required` properties and `init`-only setters.
+- **Cancellation flows everywhere** — every async method takes a `CancellationToken` with default as its last parameter and forwards it.
+
+## Reference Index
+
+- **[dependency-injection.md](references/dependency-injection.md)** — `IServiceCollection` registration, lifetimes, keyed services, interface-based registration, anti-service-locator
+- **[options-pattern.md](references/options-pattern.md)** — `IOptions<T>` vs `IOptionsMonitor<T>` vs `IOptionsSnapshot<T>`, `BindConfiguration`, `ValidateDataAnnotations`, `ValidateOnStart`
+- **[configuration.md](references/configuration.md)** — `appsettings.json` and environment overrides, User Secrets, environment variables, production secret stores
+- **[modern-patterns.md](references/modern-patterns.md)** — primary constructors, `required` / `init`-only properties, nullable reference types, `CancellationToken` propagation
+
+## Related Skills
+
+- **dotnet-aspnet** — Builds the HTTP layer (controllers, minimal APIs, middleware, routing, auth, ProblemDetails) on an ASP.NET Core host
+- **dotnet-sdk-builder** — Generates .NET SDK / client libraries (DI extension methods, typed HTTP clients, typed Options, typed exceptions)
+- **dotnet-ef-core** — Entity Framework Core data access (DbContext, entities, LINQ, migrations); registered via DI and configured via Options
+- **dotnet-reviewer** — Structured .NET code review producing a severity-tagged Markdown report
+- **dotnet-tester** — Writes and runs C#/.NET unit tests (xUnit, FakeItEasy, AwesomeAssertions) and identifies missing test cases
+- **dotnet-nuget-manager** — Use whenever NuGet packages are added, removed, or updated in a project (dotnet CLI, central version management, version verification)
diff --git a/.claude/skills/dotnet-fundamentals/references/configuration.md b/.claude/skills/dotnet-fundamentals/references/configuration.md
new file mode 100644
index 0000000..8a4c529
--- /dev/null
+++ b/.claude/skills/dotnet-fundamentals/references/configuration.md
@@ -0,0 +1,79 @@
+# Configuration
+
+Configuration in .NET is layered — later sources override earlier ones. The default `HostApplicationBuilder` order is:
+
+1. `appsettings.json`
+2. `appsettings.{Environment}.json` (e.g. `appsettings.Development.json`)
+3. User Secrets (Development only)
+4. Environment variables
+5. Command-line arguments
+
+The first source that supplies a key wins for that key; sources don't merge sections deeply, they override per leaf value.
+
+## `appsettings.json`
+
+Use for defaults that ship with the application:
+
+```json
+{
+  "Smtp": {
+    "Host": "smtp.example.com",
+    "Port": 587
+  },
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information"
+    }
+  }
+}
+```
+
+Use `appsettings.{Environment}.json` for environment-specific overrides:
+
+```json
+// appsettings.Development.json
+{
+  "Smtp": { "Host": "localhost" }
+}
+```
+
+The active environment is set via `DOTNET_ENVIRONMENT` (generic host) or `ASPNETCORE_ENVIRONMENT` (ASP.NET Core).
+
+## User Secrets
+
+For local development secrets, never commit them. Initialize once per project:
+
+```bash
+dotnet user-secrets init
+dotnet user-secrets set "Smtp:Password" "dev-password"
+```
+
+User Secrets are stored outside the project directory (in `~/.microsoft/usersecrets/<UserSecretsId>/secrets.json`) and are only loaded in the Development environment.
+
+## Environment Variables
+
+Use for production secrets and container/Kubernetes deployments. Nested keys use `__` (double underscore) as separator:
+
+```bash
+export Smtp__Host=smtp.prod.example.com
+export Smtp__Password=$(cat /run/secrets/smtp-password)
+```
+
+The `__` separator is portable (works on Linux, macOS, Windows). `:` is also accepted but is not valid in environment variable names on Linux.
+
+## Production Secret Stores
+
+For production, integrate a real secret store rather than environment variables when secrets need rotation, auditing, or RBAC:
+
+- **Azure Key Vault** — `AddAzureKeyVault(...)` from `Azure.Extensions.AspNetCore.Configuration.Secrets`
+- **AWS Secrets Manager** — via `AWSSDK.Extensions.NETCore.Setup`
+- **HashiCorp Vault** — via `VaultSharp` plus a custom configuration provider
+
+These plug into the same `IConfiguration` pipeline, so consuming code keeps using `IOptions<T>` — only the registration in `Program.cs` differs.
+
+## Anti-Patterns
+
+- **Hard-coded secrets** — never commit a real password, API key, or connection string to source control. Local defaults should point at obviously-fake values.
+- **`IConfiguration` injected into business logic** — bind to a typed Options class instead. Business logic should never know about configuration providers.
+- **`config["Foo:Bar"]` indexing across the codebase** — magic strings + no validation. Bind once, inject `IOptions<T>`.
+- **Per-environment code branching** — if behavior differs between Development and Production, model it as configuration, not as `if (env.IsDevelopment())` branches scattered through services.
diff --git a/.claude/skills/dotnet-fundamentals/references/dependency-injection.md b/.claude/skills/dotnet-fundamentals/references/dependency-injection.md
new file mode 100644
index 0000000..330f0b8
--- /dev/null
+++ b/.claude/skills/dotnet-fundamentals/references/dependency-injection.md
@@ -0,0 +1,81 @@
+# Dependency Injection
+
+## Registration
+
+Register services on the host's `IServiceCollection`. The same API applies to ASP.NET Core (`builder.Services`), Worker Services, Console apps using `HostApplicationBuilder`, and library extension methods (`public static IServiceCollection AddMyFeature(this IServiceCollection services)`).
+
+```csharp
+services.AddScoped<IOrderService, OrderService>();
+services.AddSingleton<IClock, SystemClock>();
+services.AddTransient<IEmailFormatter, EmailFormatter>();
+```
+
+- Register services in `Program.cs` or via extension methods (`AddApplicationServices()`, `AddPersistence()`, etc.) to keep `Program.cs` lean.
+- Prefer interface-based registration for testability — register against the abstraction, not the concrete type.
+
+## Lifetimes
+
+- **Transient** — Stateless, lightweight services. New instance per resolution.
+- **Scoped** — One instance per logical operation (per HTTP request in ASP.NET Core, per `IServiceScope` in worker scenarios). Typical for `DbContext`, unit-of-work, and per-request caches.
+- **Singleton** — Thread-safe shared state (caches, configuration providers, expensive-to-build clients). Must be safe for concurrent use.
+
+Lifetime mismatches (e.g. a Singleton capturing a Scoped service) are a common bug — `ValidateScopes` and `ValidateOnBuild` catch this at startup.
+
+```csharp
+var host = Host.CreateApplicationBuilder()
+    .ConfigureContainer<IServiceCollection>((ctx, services) =>
+    {
+        // Register here
+    })
+    .Build();
+```
+
+For ASP.NET Core, scope validation is on by default in Development. For other hosts, enable it explicitly via `ServiceProviderOptions`.
+
+## Keyed Services (.NET 8+)
+
+Use keyed services when multiple implementations of the same interface need to coexist and be selected by key:
+
+```csharp
+services.AddKeyedScoped<IPaymentGateway, StripeGateway>("stripe");
+services.AddKeyedScoped<IPaymentGateway, PayPalGateway>("paypal");
+
+public class CheckoutHandler(
+    [FromKeyedServices("stripe")] IPaymentGateway stripe,
+    [FromKeyedServices("paypal")] IPaymentGateway paypal)
+{
+    // ...
+}
+```
+
+## Anti-Patterns
+
+- **Service locator** — Do not inject `IServiceProvider` into business logic and resolve dependencies at runtime. Constructor-inject the specific dependencies you need.
+- **Capturing scoped services in singletons** — A singleton holding a reference to a scoped service leaks the scoped instance and causes use-after-dispose bugs. Use `IServiceScopeFactory` to create a fresh scope when needed.
+- **Concrete-type registration when an interface exists** — Registering `services.AddScoped<OrderService>()` instead of `services.AddScoped<IOrderService, OrderService>()` defeats substitution and testing.
+- **Static state / singletons outside DI** — All cross-cutting state goes through DI. No `public static` mutable state.
+
+## Library Extension Method Pattern
+
+When shipping a NuGet library that registers services for consumers, expose a single extension method:
+
+```csharp
+public static class MyFeatureServiceCollectionExtensions
+{
+    public static IServiceCollection AddMyFeature(
+        this IServiceCollection services,
+        Action<MyFeatureOptions>? configure = null)
+    {
+        services.AddOptions<MyFeatureOptions>()
+            .BindConfiguration(MyFeatureOptions.SectionName)
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        if (configure is not null)
+            services.Configure(configure);
+
+        services.AddScoped<IMyFeatureService, MyFeatureService>();
+        return services;
+    }
+}
+```
diff --git a/.claude/skills/dotnet-fundamentals/references/modern-patterns.md b/.claude/skills/dotnet-fundamentals/references/modern-patterns.md
new file mode 100644
index 0000000..c8f3e04
--- /dev/null
+++ b/.claude/skills/dotnet-fundamentals/references/modern-patterns.md
@@ -0,0 +1,87 @@
+# Modern C# / .NET Patterns
+
+Conventions for code written against current .NET. Use these consistently in new code; match existing project style if it predates these features.
+
+## Primary Constructors (C# 12)
+
+- For middleware, inject scoped services via `InvokeAsync` parameters, not the primary constructor.
+
+## `required` Properties + `init`-Only Setters
+
+Force callers to supply mandatory values at object initialization; prevent mutation afterward.
+
+```csharp
+public record CreateOrderRequest
+{
+    public required string CustomerId { get; init; }
+    public required IReadOnlyList<OrderItem> Items { get; init; }
+    public string? Notes { get; init; }
+}
+
+var req = new CreateOrderRequest
+{
+    CustomerId = "C-123",
+    Items = items,
+};
+```
+
+- Combine with `record` for value-semantics DTOs.
+- `required` runs at compile time — the compiler refuses initialization expressions that omit a required member.
+- Use `init` (not `set`) for immutable-after-construction shape.
+
+## Nullable Reference Types
+
+Enable project-wide in the `.csproj`:
+
+```xml
+<Nullable>enable</Nullable>
+```
+
+- Declare a reference type as nullable explicitly: `string?` means "may be null", `string` means "guaranteed non-null".
+- Treat nullable warnings as errors (`<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`) in new projects.
+- For legacy code being migrated, use `<Nullable>annotations</Nullable>` first (annotations only, no warnings) to add types incrementally, then flip to `enable`.
+- Use the null-forgiving `!` operator only at provable-non-null boundaries (post-validation, after `ArgumentNullException.ThrowIfNull`). Do not sprinkle it to silence warnings.
+
+## `CancellationToken` Propagation
+
+Every async method takes a `CancellationToken` as its **last** parameter and forwards it to every async call it makes.
+
+```csharp
+public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
+{
+    var dto = await _db.Orders
+        .AsNoTracking()
+        .FirstOrDefaultAsync(o => o.Id == id, ct);
+    return dto is null ? null : await _mapper.MapAsync(dto, ct);
+}
+```
+
+- Parameter is named `ct` or `cancellationToken` consistently within a codebase.
+- Default to `default` only for entry points that have no caller-supplied token (e.g. CLI `Main`); library code should require the caller to pass one.
+- In ASP.NET Core, `HttpContext.RequestAborted` is automatically bound to action parameters of type `CancellationToken`.
+- Never swallow `OperationCanceledException` — let it bubble. The host treats it as expected cancellation.
+
+## File-Scoped Namespaces (C# 10)
+
+```csharp
+namespace MyCompany.MyProduct.Orders;
+
+public class OrderService { /* ... */ }
+```
+
+Default for all new files. Removes one level of indentation across the file.
+
+## `global using` Directives
+
+Centralize common imports in `GlobalUsings.cs`:
+
+```csharp
+global using System;
+global using System.Collections.Generic;
+global using System.Threading;
+global using System.Threading.Tasks;
+global using Microsoft.Extensions.DependencyInjection;
+global using Microsoft.Extensions.Options;
+```
+
+Use the SDK-provided `<ImplicitUsings>enable</ImplicitUsings>` for the default set; add project-specific globals via explicit `global using` declarations.
diff --git a/.claude/skills/dotnet-fundamentals/references/options-pattern.md b/.claude/skills/dotnet-fundamentals/references/options-pattern.md
new file mode 100644
index 0000000..74256cc
--- /dev/null
+++ b/.claude/skills/dotnet-fundamentals/references/options-pattern.md
@@ -0,0 +1,89 @@
+# Options Pattern
+
+Bind configuration sections to strongly-typed classes via `Microsoft.Extensions.Options`. Validate at startup, inject by interface (`IOptions<T>` / `IOptionsMonitor<T>` / `IOptionsSnapshot<T>`).
+
+## Defining an Options Class
+
+```csharp
+public class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public required string Host { get; init; }
+    public int Port { get; init; } = 587;
+    public required string Username { get; init; }
+    public required string Password { get; init; }
+}
+```
+
+- Declare `SectionName` as a `const string` on the class so consumers and tests can refer to it without magic strings.
+- Use `required` properties for values without sane defaults — binding fails clearly if a required value is missing.
+- Use `init`-only setters to keep options immutable after binding.
+
+## Registration
+
+```csharp
+services.AddOptions<SmtpOptions>()
+    .BindConfiguration(SmtpOptions.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+- `BindConfiguration("Smtp")` binds the section automatically and re-binds when configuration reloads.
+- `ValidateDataAnnotations()` runs `[Required]`, `[Range]`, etc. on the options class.
+- `ValidateOnStart()` runs validation at host startup — misconfiguration surfaces immediately instead of at first use.
+
+For complex validation, implement `IValidateOptions<T>`:
+
+```csharp
+public class SmtpOptionsValidator : IValidateOptions<SmtpOptions>
+{
+    public ValidateOptionsResult Validate(string? name, SmtpOptions options)
+    {
+        if (options.Port is < 1 or > 65535)
+            return ValidateOptionsResult.Fail("Port must be 1-65535");
+        return ValidateOptionsResult.Success;
+    }
+}
+
+services.AddSingleton<IValidateOptions<SmtpOptions>, SmtpOptionsValidator>();
+```
+
+## Consuming Options
+
+| Interface | Lifetime | When to use |
+|---|---|---|
+| `IOptions<T>` | Singleton | Static configuration that does not change after startup. Cheapest. |
+| `IOptionsSnapshot<T>` | Scoped (ASP.NET Core only) | Per-request rebinding — picks up changes for each new request. |
+| `IOptionsMonitor<T>` | Singleton with change notifications | Long-lived components (background services, HTTP clients) that need to react to reloads via `OnChange`. |
+
+```csharp
+public class EmailSender(IOptions<SmtpOptions> options)
+{
+    private readonly SmtpOptions _smtp = options.Value;
+    // ...
+}
+
+public class ReloadableEmailSender(IOptionsMonitor<SmtpOptions> monitor)
+{
+    public ReloadableEmailSender(IOptionsMonitor<SmtpOptions> monitor)
+    {
+        monitor.OnChange(opts => RebuildClient(opts));
+    }
+}
+```
+
+## Named Options
+
+When the same options shape exists multiple times (e.g. multiple SMTP backends):
+
+```csharp
+services.Configure<SmtpOptions>("Primary", config.GetSection("Smtp:Primary"));
+services.Configure<SmtpOptions>("Fallback", config.GetSection("Smtp:Fallback"));
+
+public class Mailer(IOptionsMonitor<SmtpOptions> monitor)
+{
+    private readonly SmtpOptions _primary = monitor.Get("Primary");
+    private readonly SmtpOptions _fallback = monitor.Get("Fallback");
+}
+```
diff --git a/.claude/skills/dotnet-inspect/SKILL.md b/.claude/skills/dotnet-inspect/SKILL.md
new file mode 100644
index 0000000..699076c
--- /dev/null
+++ b/.claude/skills/dotnet-inspect/SKILL.md
@@ -0,0 +1,235 @@
+---
+name: dotnet-inspect
+description: Query .NET APIs across NuGet packages, platform libraries, and local files. Search for types, list API surfaces, compare and diff versions, find extension methods and implementors. Use whenever you need to answer questions about .NET library contents.
+---
+
+# dotnet-inspect
+
+Query .NET library APIs — the same commands work across NuGet packages, platform libraries (System.*, Microsoft.AspNetCore.*), and local .dll/.nupkg files.
+
+## Quick Decision Tree
+
+- **Code broken?** → `diff --package Foo@old..new` first, then `member`
+- **What's new in a .NET preview?** → `diff --platform System.Runtime@P2..P3 --additive` per framework library
+- **What types exist?** → `type --package Foo` (discover types in a package or library)
+- **What members does a type have?** → `member Type --package Foo` (compact table by default)
+- **What does a type look like?** → `type Type --package Foo` (tree view for single type)
+- **What are the method signatures?** → `member Type --package Foo -m Method` (full signatures + docs)
+- **What is the source/IL?** → `member Type --package Foo -m Method:1 -v:d` (Source, Lowered C#, IL)
+- **Where is the source code?** → `source Type --package Foo` (SourceLink URLs), `source Type -m Member` (with line numbers)
+- **Want raw source content?** → `source Type --package Foo --cat` (fetches and prints source files)
+- **What constructors exist?** → `member 'Type<T>' --package Foo -m .ctor` (use `<T>` not `<>`)
+- **How many overloads?** → `member Type --package Foo --show-index` (shows `Name:N` indices)
+- **What does this package depend on?** → `depends --package Foo`
+- **What does this type inherit?** → `depends 'INumber<TSelf>'`
+- **Want a dependency diagram?** → `depends --mermaid` (standalone) or `depends --markdown --mermaid` (embedded)
+- **What metadata fields exist?** → `-S Section --fields "PDB*"` (structured query, no DSL)
+- **What version is available?** → `Foo --version` (cache-first), `Foo --latest-version` (always NuGet), `Foo --versions` (list all)
+
+## When to Use This Skill
+
+- **"What types are in this package?"** — `type` discovers types, `find` searches by pattern
+- **"What members does this type have?"** — `member` for methods/properties/events (docs on by default)
+- **"What changed between versions?"** — `diff` classifies breaking/additive changes
+- **"What new APIs shipped in this preview?"** — `diff --platform System.Runtime@prev..current --additive` per framework library
+- **"This code uses an old API — fix it"** — `diff` the old..new version, then `member` to see the new API
+- **"What extends this type?"** — `extensions` finds extension methods/properties (`--reachable` for transitive)
+- **"What implements this interface?"** — `implements` finds concrete types
+- **"What does this type depend on?"** — `depends` walks type hierarchy, package deps, or library refs
+- **"Show dependencies as a diagram"** — `depends --mermaid` for standalone mermaid, `--markdown --mermaid` for embedded
+- **"Where is the source code?"** — `source` returns SourceLink URLs; add member name for line numbers
+- **"What version/metadata does this have?"** — `package` and `library` inspect metadata
+- **"What version is available?"** — `Foo --version` (fast, cache-first — like `docker run`)
+- **"What's the latest on NuGet?"** — `Foo --latest-version` (always queries NuGet — like `docker pull`)
+- **"What versions exist?"** — `Foo --versions` (list all published versions)
+- **"What TFMs are available?"** — `package Foo --tfms`, then `type --package Foo --tfm net8.0`
+- **"Where is the source code?"** — `source` returns SourceLink URLs; add member name for line numbers
+- **"Show me the actual source?"** — `source Type --package Foo --cat` fetches and prints source file contents
+- **"Show me something cool"** — `demo` runs curated showcase queries
+
+## Key Patterns
+
+Default output is **markdown** — headings, tables, and field lists that render well in terminals, editors, and LLM contexts. No flags needed:
+
+```bash
+dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json    # scan members
+dnx dotnet-inspect -y -- type --package System.Text.Json                     # scan types
+dnx dotnet-inspect -y -- diff --package System.CommandLine@2.0.0-beta4.22272.1..2.0.3  # triage changes
+```
+
+Default format is **markdown** — no flags needed. Optional formats: **oneline** (`--oneline`), **plaintext** (`--plaintext`), **json** (`--json`), **mermaid** (`--mermaid`). Verbosity (`-v:q/m/n/d`) controls which sections are included; formatter controls how they render. They compose freely — except `--oneline` and `-v` cannot be combined.
+
+```bash
+dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -v:d  # detailed (source/IL)
+dnx dotnet-inspect -y -- System.Text.Json -v:n --plaintext                      # all local sections, plaintext
+dnx dotnet-inspect -y -- type --package System.Text.Json --oneline              # compact columnar output
+dnx dotnet-inspect -y -- depends Stream --mermaid                               # standalone mermaid diagram
+dnx dotnet-inspect -y -- depends Stream --markdown --mermaid                    # mermaid embedded in markdown
+```
+
+Use `diff` first when fixing broken code — triage changes, then drill into specifics:
+
+```bash
+dnx dotnet-inspect -y -- diff --package System.CommandLine@2.0.0-beta4.22272.1..2.0.3  # what changed?
+dnx dotnet-inspect -y -- member Command --package System.CommandLine@2.0.3               # new API surface
+```
+
+## Platform Diffs & Release Notes
+
+For framework libraries (System.*, Microsoft.AspNetCore.*), use `--platform` instead of `--package`. This is the primary workflow for .NET release notes — diff each framework library between preview versions:
+
+```bash
+dnx dotnet-inspect -y -- diff --platform System.Runtime@P2..P3 --additive        # what's new?
+dnx dotnet-inspect -y -- diff --platform System.Net.Http@P2..P3 --additive       # per-library
+dnx dotnet-inspect -y -- diff --platform System.Text.Json@9.0.0..10.0.0          # across major versions
+```
+
+**Multi-library packages:** `diff --package` works across all libraries in a package (e.g., `Microsoft.Azure.SignalR` with multiple DLLs). For framework ref packages like `Microsoft.NETCore.App.Ref`, prefer `--platform` per-library since it resolves from installed packs.
+
+**Nightly/preview packages from custom feeds:** The `--source` flag works for version listing but not package downloads. Pre-populate the NuGet cache instead:
+
+```bash
+# Pre-populate cache (fails with NU1213 but downloads the package)
+dotnet add package Microsoft.NETCore.App.Ref --version <version> --source <feed-url>
+# Then use normally — resolves from NuGet cache
+dnx dotnet-inspect -y -- diff --platform System.Runtime@P2..P3 --additive
+```
+
+## Version Resolution (Docker-style)
+
+Version queries use Docker-like semantics: cached packages are served in under 15ms, network calls cost 1–4 seconds. Three flags, three behaviors:
+
+| Flag | Behavior | Network | Like Docker... |
+| ---- | -------- | ------- | -------------- |
+| `--version` (bare) | **Local** — returns the version from local cache | Only on cache miss | `docker run nginx` |
+| `--latest-version` | **Remote** — queries nuget.org for the absolute latest | Always | `docker pull nginx` |
+| `--versions` | **Remote** — returns every published version | Always | `docker image ls --all` |
+
+`--version` and bare-name inspection share the same cache. If `Foo --version` returns `2.0.3`, then `Foo` (or `package Foo`) will inspect that same `2.0.3` — no surprises, no extra network call. This is the fast path for most tasks.
+
+`--latest-version` and `--versions` always query nuget.org, so they reflect the latest published state. Use `--latest-version` when you need to confirm the newest version, e.g., before a dependency upgrade.
+
+```bash
+dnx dotnet-inspect -y -- Foo --version           # what's in the cache? (fast, local)
+dnx dotnet-inspect -y -- Foo --latest-version     # what's on nuget.org? (always network)
+dnx dotnet-inspect -y -- Foo --versions           # list all published versions
+dnx dotnet-inspect -y -- Foo --versions 5         # list latest 5 versions
+dnx dotnet-inspect -y -- Foo --versions --preview # include prerelease versions
+```
+
+The same flags work on the `package` subcommand:
+
+```bash
+dnx dotnet-inspect -y -- package Foo --version           # same local cache check
+dnx dotnet-inspect -y -- package Foo --latest-version     # always queries nuget.org
+dnx dotnet-inspect -y -- package Foo --versions           # list all versions
+```
+
+Version pinning with `@version` syntax:
+
+```bash
+dnx dotnet-inspect -y -- Foo@2.0.3                # pinned — no network if cached
+dnx dotnet-inspect -y -- Foo@latest               # always checks nuget.org
+dnx dotnet-inspect -y -- Foo                      # prefer cache, refresh on TTL expiry
+```
+
+**Use `--version` (not `--latest-version`) as the default.** It's fast and returns the same version that bare-name commands will use. Only reach for `--latest-version` when you need the absolute latest from nuget.org.
+
+## Structured Queries (like Go templates, without a DSL)
+
+Discover the schema, then select and project — no template language needed:
+
+```bash
+dnx dotnet-inspect -y -- System.Text.Json -D                          # list sections
+dnx dotnet-inspect -y -- System.Text.Json -D --effective              # sections with data (dry run)
+dnx dotnet-inspect -y -- library System.Text.Json -D --tree           # full schema tree
+dnx dotnet-inspect -y -- System.Text.Json -S Symbols                  # render one section
+dnx dotnet-inspect -y -- System.Text.Json -S Symbols --fields "PDB*"  # project specific fields
+dnx dotnet-inspect -y -- type System.Text.Json --columns Kind,Type    # project specific columns
+```
+
+## Mermaid Diagrams
+
+The `depends` command supports `--mermaid` for Mermaid diagram output. Two modes:
+
+| Flags | Output | Use case |
+| ----- | ------ | -------- |
+| `--mermaid` | Standalone mermaid (`graph TD`) | Pipe to `mmdc`, embed in tooling |
+| `--markdown --mermaid` | Mermaid fenced blocks inside markdown | Render in GitHub, VS Code, docs |
+
+```bash
+dnx dotnet-inspect -y -- depends Stream --mermaid                               # type hierarchy as mermaid
+dnx dotnet-inspect -y -- depends Stream --markdown --mermaid                    # embedded in markdown
+dnx dotnet-inspect -y -- depends --library System.Text.Json --mermaid           # assembly reference graph
+dnx dotnet-inspect -y -- depends --package Markout --mermaid                    # package dependency graph
+```
+
+## Search Scope
+
+Search commands (`find`, `extensions`, `implements`, `depends`) use scope flags:
+
+- **(no flags)** — all platform frameworks (runtime, aspnetcore, netstandard)
+- **`--platform`** — all platform frameworks
+- **`--extensions`** — curated Microsoft.Extensions.* packages
+- **`--aspnetcore`** — curated Microsoft.AspNetCore.* packages
+- **`--package Foo`** — specific NuGet package (combinable with scope flags)
+
+`type`, `member`, `library`, `diff` accept `--platform <name>` as a string for a specific platform library.
+
+## Command Reference
+
+| Command | Purpose |
+| ------- | ------- |
+| `type` | **Discover types** — terse output, no docs, use `--shape` for hierarchy |
+| `member` | **Inspect members** — docs on by default, supports dotted syntax (`-m Type.Member`) |
+| `find` | Search for types by glob or fuzzy match across any scope |
+| `diff` | Compare API surfaces between versions — breaking/additive classification |
+| `extensions` | Find extension methods/properties for a type (`--reachable` for transitive) |
+| `implements` | Find types implementing an interface or extending a base class |
+| `depends` | Walk dependency graphs upward — type hierarchy, package deps, or library refs |
+| `package` | Package metadata, files, versions, dependencies, `search` for NuGet discovery |
+| `library` | Library metadata, symbols, references, SourceLink audit |
+| `source` | **SourceLink URLs** — type-level or member-level (with line numbers), `--cat` to fetch content, `--verify` to check URLs |
+| `demo` | Run curated showcase queries — list, invoke, or feeling-lucky |
+
+## Filtering and Limiting
+
+```bash
+dnx dotnet-inspect -y -- type System.Text.Json -k enum               # filter by kind (type and member commands)
+dnx dotnet-inspect -y -- type System.Text.Json -t "*Converter*"      # glob filter on type names
+dnx dotnet-inspect -y -- member System.Text.Json JsonDocument -m Parse  # filter by member name
+dnx dotnet-inspect -y -- type System.Text.Json -5                    # first 5 lines (like head -5)
+dnx dotnet-inspect -y -- type System.Text.Json --tail 10             # last 10 lines (like tail -10)
+```
+
+**Do not pipe output through `head`, `tail`, or `Select-Object`.** Use built-in `--head` / `--tail`:
+
+- **`-n N`, `--head N`, or `-N`** — first N lines (like `head`). Keeps headers, truncates cleanly.
+- **`--tail N`** — last N lines (like `tail`). Buffers output, emits only the final N lines.
+- **`-m N`** (numeric) — item limit (members per kind section).
+- **`-k Kind`** — filter by kind: `class/struct/interface/enum/delegate` (type) or `method/property/field/event/constructor` (type single-type view, member).
+- **`-S Section`** — show only a specific section (glob-capable).
+
+## Key Syntax
+
+- **Generic types** need quotes: `'Option<T>'`, `'IEnumerable<T>'`
+- **Use `<T>` not `<>`** for generic types — `"Option<>"` resolves to the abstract base, `'Option<T>'` resolves to the concrete generic with constructors
+- **`type` uses `-t`** for type filtering, **`member` uses `-m`** for member filtering (not `--filter`)
+- **Dotted syntax** for `member`: `-m JsonSerializer.Deserialize` or `-m System.Text.Json.JsonSerializer.Deserialize`
+- **Diff ranges** use `..`: `--package System.Text.Json@9.0.0..10.0.0`
+- **Derived types** only show their own members — query the base type too
+
+## Installation
+
+Use `dnx` (like `npx`). Always use `-y` and `--` to prevent interactive prompts:
+
+```bash
+dnx dotnet-inspect -y -- <command>
+```
+
+## Related Skills
+
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Uses dotnet-inspect to investigate API surface and version diffs during reviews
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Queries types and members of existing libraries when generating SDK wrappers
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Inspects packages before upgrading or replacing them
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Discovers ASP.NET Core APIs across versions when migrating or adopting new features
diff --git a/.claude/skills/dotnet-nuget-manager/SKILL.md b/.claude/skills/dotnet-nuget-manager/SKILL.md
new file mode 100644
index 0000000..df2960c
--- /dev/null
+++ b/.claude/skills/dotnet-nuget-manager/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: dotnet-nuget-manager
+description: Manages NuGet packages in .NET projects and solutions. Use when adding, removing, or updating NuGet package references or versions. Enforces dotnet CLI for package operations, supports Directory.Packages.props central version management, and provides version verification workflows. Handles dotnet add/remove package, dotnet list package --outdated, and dotnet restore.
+---
+
+# NuGet Manager
+
+## When to Use
+
+- Adding, removing, or updating NuGet packages in a .NET project or solution
+- Listing outdated packages and planning version bumps
+- Verifying a specific package version exists before bumping it
+- Working in a solution that uses `Directory.Packages.props` central version management
+
+## Prerequisites
+
+- .NET SDK installed (typically .NET 8.0 SDK or later, or a version compatible with the target solution).
+- `dotnet` CLI available on your `PATH`.
+- `jq` (JSON processor) — Linux/macOS; OR
+- PowerShell (`pwsh`) — Windows/cross-platform; required for version verification using `dotnet package search`.
+
+## Core Rules
+
+1.  **NEVER** directly edit `.csproj`, `.props`, or `Directory.Packages.props` files to **add** or **remove** packages. Always use `dotnet add package` and `dotnet remove package` commands.
+2.  **DIRECT EDITING** is ONLY permitted for **changing versions** of existing packages.
+3.  **VERSION UPDATES** must follow the mandatory workflow:
+    - Verify the target version exists on NuGet.
+    - Determine if versions are managed per-project (`.csproj`) or centrally (`Directory.Packages.props`).
+    - Update the version string in the appropriate file.
+    - Immediately run `dotnet restore` to verify compatibility.
+
+## Workflows
+
+### Adding a Package
+Use `dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>]`.
+Example: `dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json`
+
+### Removing a Package
+Use `dotnet remove [<PROJECT>] package <PACKAGE_NAME>`.
+Example: `dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json`
+
+### Updating Package Versions
+When updating a version, follow these steps:
+
+1.  **Verify Version Existence**:
+    Check if the version exists using the `dotnet package search` command with exact match and JSON formatting. 
+    Using `jq`:
+    `dotnet package search <PACKAGE_NAME> --exact-match --format json | jq -e '.searchResult[].packages[] | select(.version == "<VERSION>")'`
+    Using PowerShell:
+    `(dotnet package search <PACKAGE_NAME> --exact-match --format json | ConvertFrom-Json).searchResult.packages | Where-Object { $_.version -eq "<VERSION>" }`
+    
+2.  **Determine Version Management**:
+    - Search for `Directory.Packages.props` in the solution root. If present, versions should be managed there via `<PackageVersion Include="Package.Name" Version="1.2.3" />`.
+    - If absent, check individual `.csproj` files for `<PackageReference Include="Package.Name" Version="1.2.3" />`.
+
+3.  **Apply Changes**:
+    Modify the identified file with the new version string.
+
+4.  **Verify Stability**:
+    Run `dotnet restore` on the project or solution. If errors occur, revert the change and investigate.
+
+### Listing Outdated Packages
+
+Use `dotnet list package --outdated` to find packages with newer versions available.
+
+**Per project:**
+```bash
+dotnet list src/MyProject/MyProject.csproj package --outdated
+```
+
+**Entire solution:**
+```bash
+dotnet list package --outdated
+```
+
+The output shows the current version, the latest resolved version, and the latest available version for each package. Use this as the basis for deciding which packages to update, then follow the **Updating Package Versions** workflow for each.
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Used when adding `Microsoft.Extensions.*` packages for DI, Options, and Configuration
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Invokes this skill for health-check, resilience, and middleware packages
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invokes this skill in Step 7 to add SDK runtime dependencies
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Used when a review surfaces outdated or vulnerable packages
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Inspect package APIs before upgrading or replacing them
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — Adds EF Core providers, Testcontainers, and SQLite packages
+
diff --git a/.claude/skills/dotnet-reviewer/SKILL.md b/.claude/skills/dotnet-reviewer/SKILL.md
new file mode 100644
index 0000000..63d6f97
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: dotnet-reviewer
+description: Performs structured code reviews on .NET 10+ projects. Reviews either uncommitted working-tree changes or committed changes on the current feature branch (vs. main). Produces a Markdown report under docs/reviews/ with severity-tagged findings ([Critical|Major|Minor|Suggestion|Nitpick][Security|Performance|Architecture|Code-Quality|Tests|.NET-Idioms]) and fix suggestions. Must NOT activate on generic "review my code" requests; other-language reviewers must not be hijacked.
+---
+
+# dotnet-reviewer
+
+Structured code review for .NET 10+ projects.
+
+## When to Use This Skill
+
+A Code review for a .NET 10+ project is needed.
+The user may add language preferences (e.g., "in German") — apply that to the report only. The skill itself remains in English.
+
+## Prerequisites
+
+- `git` repo with `main` branch (for branch mode).
+- `dotnet ≥ 10` SDK if any of build/format/test will run.
+- `bash` 3.2+ available (macOS default works).
+- `python3` available (used by scripts for safe JSON encoding).
+
+## Workflow
+
+Follow these steps in order.
+
+### Step 1 — Interactive prompt
+
+Ask the user three things:
+
+1. **Mode:** `uncommitted` (working-tree vs HEAD, includes staged/unstaged/untracked) or `branch` (current branch vs `main`).
+2. **Tools:** for each of `build`, `format`, `test` — yes or no. Default no for all three.
+3. **Report language:** default English. If they want another language, capture it.
+
+Validate inputs against the whitelist. Re-prompt on invalid input.
+
+### Step 2 — Detect .NET version
+
+Run `scripts/detect-dotnet-version.sh --repo-root <repo>`.
+
+- Exit 0: parse JSON `{sdk, target_frameworks, project_files}`. Pick the highest `net<N>.0` from `target_frameworks` to drive checklist selection.
+- Exit 4 (SDK < 10 or none): abort. Tell the user "this skill targets .NET 10+; detected `<X>`."
+- Exit 5 (malformed): show offending file. Ask the user whether to proceed without version-awareness. If yes, fall back to general checklists only.
+- Exit 2 (not a directory) or 1 (usage): bug — report and abort.
+
+### Step 3 — Collect diff
+
+Run `scripts/collect-diff.sh --repo-root <repo> --mode <mode> --baseline main`.
+
+- Exit 0 with `files == 0`: report "no changes to review" and exit.
+- Exit 0 with `files > 0`: continue.
+- Exit 2: not a git repo — abort.
+- Exit 3 (branch mode, missing `main`): abort, tell user.
+
+### Step 4 — Large-diff strategy gate
+
+If `loc > 2000` OR `files > 50`, ask the user to choose:
+
+- **(B) Review everything** — note token cost in report header.
+- **(C) Prioritize** — review files matching `*Service.cs`, `*Controller.cs`, files without sibling `*.Tests/*Tests.cs` first; summarize the rest.
+- **(D) Chunk file-by-file** — review each file independently; group findings by file.
+
+If C is chosen but no files match the priority heuristics, fall back to D and note the fallback transparently in the report.
+
+### Step 5 — Run requested tool checks
+
+For each tool the user selected, invoke `scripts/run-checks.sh --repo-root <repo>` with the appropriate flag(s). Parse JSON.
+
+If a tool isn't installed, the script reports the failure inside the JSON — log "X not available, skipping" and continue. Don't abort.
+
+### Step 6 — Review
+
+Walk the diff against:
+1. The version-specific checklist (`references/review-checklist-net<N>.md`).
+2. `references/review-checklist-security.md`.
+3. `references/review-checklist-performance.md`.
+4. `references/review-checklist-architecture.md`.
+5. `references/review-checklist-code-quality.md`.
+
+Fold tool findings into the issue list using the severity mapping defined in `references/severity-taxonomy.md`:
+- `dotnet build` errors → Critical
+- `dotnet build` warnings → Minor
+- `dotnet test` failures → Critical
+- `dotnet format` violations → Suggestion
+
+Each finding MUST include a fix suggestion as a code block (`csharp` fenced) — no auto-patching.
+
+### Step 7 — Render report
+
+Generate the report following `references/report-format.md` exactly:
+- Title + metadata block
+- Detailed Executive Summary (counts, top-3 risks, LOC, scope)
+- Findings ordered by severity desc, then file path asc
+- Tool Output Appendix
+
+### Step 8 — Write report
+
+Path: `docs/reviews/YYYY-MM-DD-<branch>-<mode>.md`. Branch name is sanitized (replace `/` with `-`).
+
+If the path exists, append `-2`, `-3`, … until unique. Create `docs/reviews/` if missing. **Never auto-commit. Never overwrite.**
+
+Output to chat: the file path and a one-line summary (e.g., `"Wrote review with 2 Critical, 5 Major findings to docs/reviews/…"`).
+
+## Output Contract
+
+- Single Markdown file under `docs/reviews/`.
+- Format strictly per `references/report-format.md`.
+- Severity and area tags from `references/severity-taxonomy.md`.
+
+## Resource Index
+
+- `scripts/detect-dotnet-version.sh` — SDK / target framework detection
+- `scripts/collect-diff.sh` — diff collection with exclusions
+- `scripts/run-checks.sh` — optional dotnet build/format/test
+- `references/severity-taxonomy.md`
+- `references/report-format.md`
+- `references/review-checklist-net10.md`
+- `references/review-checklist-security.md`
+- `references/review-checklist-performance.md`
+- `references/review-checklist-architecture.md`
+- `references/review-checklist-code-quality.md`
+
+## Things This Skill Never Does
+
+- Auto-patches or auto-commits the report.
+- Bypasses git hooks (`--no-verify`, `--no-gpg-sign`).
+- Runs destructive operations as "fixes" (no `git reset`, no deletions).
+- Includes secrets in logs or the report.
+- Reviews .NET versions below 10 — aborts with a clear message.
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Review findings reference DI lifetime, Options, and configuration best practices
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — Code-quality checklist references XML documentation conventions
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Test-quality findings reference this skill's expectations
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — EF Core findings reference these data-access best practices
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — ASP.NET Core findings reference this skill's conventions
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Surfaced outdated/vulnerable packages are addressed via this skill
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Used to investigate API surface and version diffs during review
diff --git a/.claude/skills/dotnet-reviewer/references/report-format.md b/.claude/skills/dotnet-reviewer/references/report-format.md
new file mode 100644
index 0000000..301d3e9
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/report-format.md
@@ -0,0 +1,78 @@
+# Report Format
+
+The reviewer writes one Markdown file to `docs/reviews/YYYY-MM-DD-<branch>-<mode>.md`.
+Never overwrite — append `-2`, `-3`, … on collision. Never auto-commit.
+
+## Required Sections
+
+1. Title + metadata block
+2. Executive Summary (detailed)
+3. Findings, ordered by severity desc, then by file path
+4. Tool Output Appendix (if any tool ran)
+
+## Skeleton
+
+```markdown
+# .NET Code Review — <branch> (<mode>)
+
+**Date:** YYYY-MM-DD
+**Mode:** uncommitted | branch (vs. main)
+**Detected SDK:** 10.0.x
+**Target Framework(s):** net10.0, …
+**Tools run:** build=Y/N · format=Y/N · test=Y/N
+**Exclusions:** .gitignore, *.min.js, wwwroot/lib/**
+**Review strategy:** full | prioritized | chunked
+**Diff size:** <files> files, <loc> changed LOC
+
+## Executive Summary
+
+| Severity | Count |
+|---|---|
+| Critical | N |
+| Major | N |
+| Minor | N |
+| Suggestion | N |
+| Nitpick | N |
+
+**Top risks:**
+1. <one line>
+2. <one line>
+3. <one line>
+
+**Overall:** <1–2 sentence assessment>
+
+## Findings
+
+### [Critical][Security] src/Api/UserController.cs:42
+<one-line description>
+
+<recommendation paragraph>
+
+```csharp
+// fix suggestion
+```
+
+### [Major][Performance] src/Data/Repo.cs:88
+…
+
+## Tool Output Appendix
+
+### dotnet build
+- 0 errors, 2 warnings (see findings above for warnings folded in).
+
+### dotnet test
+- 12 passed, 0 failed (duration: 4s).
+
+### dotnet format
+- Skipped.
+```
+
+## Rules
+
+- **Every finding MUST include a fix suggestion** as a code block. If the fix is structural (no single-snippet rewrite), describe the steps in prose and provide the most-affected snippet.
+- Do not paste raw diff content. Reference `path:line` instead.
+- File paths are repo-relative.
+- Group findings by severity desc, ties broken by file path asc.
+- Tool warnings/errors that are already covered by a hand-written finding should not be duplicated in the appendix — note "folded into findings".
+- If strategy `chunked` was used, group findings under `## Findings — <file>` subsections.
+- If strategy `prioritized` was used, list deferred files at the end as `## Files Not Reviewed in Detail`.
diff --git a/.claude/skills/dotnet-reviewer/references/review-checklist-architecture.md b/.claude/skills/dotnet-reviewer/references/review-checklist-architecture.md
new file mode 100644
index 0000000..773733b
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/review-checklist-architecture.md
@@ -0,0 +1,37 @@
+# Review Checklist — Architecture
+
+## Layering
+
+- Domain references no infrastructure (no EF Core attributes on domain entities; no `HttpClient` in domain).
+- Application layer orchestrates — does not reach into UI/infrastructure types directly.
+- Controllers / minimal-API handlers stay thin: parse, dispatch to application service, map result.
+- Infrastructure adapters implement domain/application interfaces, not the other way around.
+
+## Dependency Direction
+
+- Outer rings depend on inner rings. Flag any inner-ring file with a `using` of an outer-ring namespace.
+- Solution structure should make this provable; if it doesn't (single project, mixed namespaces), call it out.
+
+## SOLID
+
+- **SRP:** classes that change for multiple reasons. Public surface that mixes orchestration with persistence.
+- **OCP:** strategy patterns where `if (type == X) … else if (type == Y) …` is repeated across files.
+- **LSP:** subclass that throws `NotSupportedException` on a base member.
+- **ISP:** "fat" interfaces with one consumer per method. Split or use mark-only interfaces.
+- **DIP:** new-ing dependencies inside a class instead of injecting (except for value objects).
+
+## Dependency Injection
+
+See the `dotnet-aspnet` skill (Dependency Injection + Configuration sections) for lifetime rules and the Options pattern. Reviewer-specific hook: flag DI changes that capture a `Scoped` service inside a `Singleton`, call `BuildServiceProvider()` during composition, or register `IOptions<T>` without `ValidateOnStart()`.
+
+## Pattern Consistency
+
+- New code matches the existing project pattern. If this file uses CQRS handlers and you added a controller method that bypasses them, flag it.
+- Naming consistency: `XxxService` vs. `XxxRepository` vs. `XxxHandler` — pick one and stay consistent within a bounded context.
+- New pattern introductions (e.g., switching from MediatR to direct calls) need an architectural rationale; flag if introduced silently.
+
+## Module Boundaries
+
+- Each project (.csproj) has a clear purpose. Flag projects whose name and contents have drifted.
+- Public API of a project is intentional — `internal` over `public` unless cross-project consumption is required.
+- `InternalsVisibleTo` only for tests; flag if used to share types with non-test projects.
diff --git a/.claude/skills/dotnet-reviewer/references/review-checklist-code-quality.md b/.claude/skills/dotnet-reviewer/references/review-checklist-code-quality.md
new file mode 100644
index 0000000..ada4779
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/review-checklist-code-quality.md
@@ -0,0 +1,57 @@
+# Review Checklist — Code Quality
+
+## Naming
+
+- Methods are verbs. Properties are nouns. Async methods end in `Async`.
+- No Hungarian notation (`strName`, `iCount`).
+- Booleans read as questions: `IsValid`, `HasItems`, `CanRetry`.
+- Acronyms: `Url`, `Id`, `Api` (PascalCase per .NET conventions, not `URL`/`ID`/`API`).
+- Type parameters: `T`, or `TKey`/`TValue` — descriptive when more than one.
+
+## Nullability
+
+- `<Nullable>enable</Nullable>` is on (project-level check).
+- No `!` (null-forgiving operator) without a comment explaining why.
+- No `#nullable disable` regions in new code.
+- API surface honors nullability annotations — methods returning `T?` actually return null in some path.
+
+## Complexity
+
+- Methods over ~30 lines or with 4+ levels of nesting deserve a closer look.
+- A `switch` with more than ~7 arms over the same value usually wants polymorphism or a lookup table.
+- Boolean parameters often hide two methods — flag and suggest splitting.
+
+## Exception Handling
+
+- Catch the specific exception type, not `Exception`. `catch (Exception)` requires justification.
+- Never swallow exceptions silently. Logging counts only if the log line carries enough context to diagnose.
+- Don't use exceptions for control flow.
+- Wrap third-party exceptions at the boundary; do not leak them into domain code.
+
+## IDisposable / IAsyncDisposable
+
+- `using` (or `using` declarations) for every `IDisposable` you create.
+- `IDisposable` types as fields require the owning class to also be disposable.
+- `IAsyncDisposable` consumed with `await using`, not `using`.
+
+## Dead Code
+
+- Unused `using` directives → format check should catch; flag if format check is off.
+- Unreachable code (`return` followed by statements).
+- Unused private members. Public unused members may be API for a consumer — leave alone unless clearly orphaned.
+
+## Comments and Docs
+
+- Public API has XML docs, especially for libraries. See the `dotnet-xmldocs` skill for the tag conventions (`<summary>`, `<param>`, `<returns>`, `<exception>`, etc.).
+- Comments explain *why*, not *what*. Flag comments that restate the code.
+- TODOs without a ticket reference are a smell; flag.
+
+## Tests (cross-cutting)
+
+See the `dotnet-tester` skill for AAA layout, `Method_Condition_Expected` naming, mocking conventions, and edge-case coverage. Reviewer-specific hook: flag any new public behavior that ships without at least one test, and any test body containing conditional logic (`if`/`for`).
+
+## Logging
+
+- Structured logging (named placeholders), not string concatenation.
+- Log level matches consequence: `Error` for exceptions reaching the boundary, `Warning` for recoverable degraded paths, `Information` for state transitions, `Debug` for detail.
+- No PII in logs (email, user names, full request bodies) without a redaction strategy.
diff --git a/.claude/skills/dotnet-reviewer/references/review-checklist-net10.md b/.claude/skills/dotnet-reviewer/references/review-checklist-net10.md
new file mode 100644
index 0000000..8c67a22
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/review-checklist-net10.md
@@ -0,0 +1,30 @@
+# Review Checklist — .NET 10
+
+Apply when `detect-dotnet-version.sh` reports `target_frameworks` containing `net10.0`.
+
+## Language Idioms
+
+- **Primary constructors** — prefer over redundant private fields when the parameter is used directly. Flag: legacy `ctor + private readonly field` pattern in new code.
+- **Collection expressions** — `[1, 2, 3]` over `new[] { 1, 2, 3 }` and `new List<int> { 1, 2, 3 }`. Flag: verbose collection initialization.
+- **Required members** — `required` modifier replaces hand-rolled validation in constructors. Flag: throws in constructor for missing init-only properties.
+- **`field` keyword** — auto-property backing-field access (preview in 9, stable in 10). Flag: unnecessary backing field declarations.
+- **Pattern matching** — list patterns, relational patterns. Flag: chained `if (x.Length > 0 && x[0] == …)`.
+- **`init` and `required` together** — for immutable POCOs.
+
+## API Idioms
+
+- `System.Threading.Lock` (new lock type) over `object`-based `lock` for new code.
+- `Random.Shared` for non-cryptographic randomness — never `new Random()` in hot path.
+- `TimeProvider` for testable time — flag direct `DateTime.UtcNow` in code that should be testable.
+- `JsonSerializerContext` (source-gen) over reflection-based `JsonSerializer` on hot paths.
+
+## Project Configuration
+
+- `<Nullable>enable</Nullable>` MUST be on. Flag projects without it.
+- `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` recommended for libraries.
+- `<LangVersion>` should not be pinned below the SDK's default unless a comment explains why.
+- `ImplicitUsings` enabled — flag stale top-of-file using directives that are already implicit.
+
+## Non-version-specific checks
+
+For language- and runtime-neutral pitfalls (`.Result`/`.Wait()`, `async void`, allocation hot spots, etc.) see `review-checklist-performance.md` and `review-checklist-code-quality.md`. This file covers only what is specific to .NET 10.
diff --git a/.claude/skills/dotnet-reviewer/references/review-checklist-performance.md b/.claude/skills/dotnet-reviewer/references/review-checklist-performance.md
new file mode 100644
index 0000000..15f5030
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/review-checklist-performance.md
@@ -0,0 +1,44 @@
+# Review Checklist — Performance
+
+## async/await
+
+- No `.Result`, `.Wait()`, `GetAwaiter().GetResult()` in async code paths.
+- `async void` only on event handlers.
+- `Task.Run` not used to "fake async" over CPU-bound work that already runs on a worker thread (e.g., inside an existing async pipeline).
+- `ConfigureAwait(false)` on library code (not application code in modern ASP.NET).
+- `ValueTask` for hot paths that frequently complete synchronously; do not consume `ValueTask` more than once.
+- `IAsyncEnumerable<T>` for streaming; flag `List<T>` accumulation when callers can stream.
+
+## Allocations
+
+- `string` concatenation in loops → `StringBuilder` or `string.Create`.
+- `string.Format` with hot-path frequency → interpolated handlers.
+- LINQ `ToList()` / `ToArray()` immediately followed by another enumeration — extra allocation for nothing.
+- `params object[]` on hot paths — allocates per call. Use overloads.
+- Closures capturing `this` in hot lambdas — flag if measurably hot.
+- Boxing: `int` → `object`, generic constraints missing.
+
+## Span / Memory
+
+- Parsing/slicing strings: `ReadOnlySpan<char>` over `Substring`.
+- File / network buffers: `Memory<byte>` / `IBufferWriter<byte>` over `byte[]`.
+- `stackalloc` for small fixed buffers in hot paths (with bounds check).
+
+## EF Core
+
+See the `dotnet-ef-core` skill (Performance section) for the full list of EF Core performance pitfalls. Reviewer-specific hook: flag any new query against a `DbContext` that is missing `.AsNoTracking()` on a read-only path, that calls `.ToList()` before a filter, or that uses `foreach` to iterate parent entities while issuing per-row child queries (N+1).
+
+## Hot-Path Heuristics
+
+A method is "hot" if any of:
+- It's on a request path of an HTTP server.
+- It's inside a `for` / `while` over a user-sized collection.
+- It's called from `Hosted` / `BackgroundService` loops.
+- A comment or naming suggests perf-sensitive use ("inner loop", "hot", "fast path").
+
+## Concurrency
+
+- Shared mutable state without synchronization (lock, `Interlocked`, immutable patterns).
+- `ConcurrentDictionary` misuse — `GetOrAdd` with allocating factory called on every hit.
+- `SemaphoreSlim` not awaited in `using` / `try/finally`.
+- `Task.WhenAll` with thousands of tasks → bound concurrency (`Parallel.ForEachAsync` with `MaxDegreeOfParallelism`).
diff --git a/.claude/skills/dotnet-reviewer/references/review-checklist-security.md b/.claude/skills/dotnet-reviewer/references/review-checklist-security.md
new file mode 100644
index 0000000..adc6d24
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/review-checklist-security.md
@@ -0,0 +1,61 @@
+# Review Checklist — Security
+
+## Input Validation
+
+- All public-API entry points (controllers, minimal-API handlers, gRPC, message handlers) validate input.
+- DTOs use `[Required]`, `[Range]`, `[StringLength]`, or FluentValidation rules. Flag DTOs without any validation.
+- Reject untrusted input before it reaches the data layer. No ad-hoc string parsing in business logic.
+
+## Injection
+
+- **SQL:** parameterized queries via EF Core LINQ, `FromSqlInterpolated`, or `DbCommand` with parameters. Flag: `FromSqlRaw` with interpolation, raw `SqlCommand` with concatenation.
+- **Command/Process:** `Process.Start` with user-controlled args — flag any concatenation; require `ProcessStartInfo` with `ArgumentList`.
+- **LDAP/XPath:** sanitized filter construction.
+- **Path traversal:** `Path.Combine` does not protect — validate that the resolved absolute path is under the intended root.
+
+## Authentication / Authorization
+
+- `[Authorize]` (or equivalent) on every non-anonymous endpoint. Flag controllers without `[Authorize]` at class level when most actions need auth.
+- Role/policy checks match the intent (no `[Authorize(Roles = "Admin")]` for user-scoped data; use resource-based authorization).
+- No "fallback to anonymous" branches in middleware.
+
+## Secrets and Credentials
+
+- No secrets in source: API keys, connection strings with passwords, JWT keys.
+- `appsettings.*.json` with secrets must be `.gitignore`-d; production uses a secret manager.
+- Logs do not include `request.Headers`, `Request.Body`, or full URLs containing tokens.
+- `HttpClient` does not blindly trust certs (`ServerCertificateCustomValidationCallback` should not return `true`).
+
+## Deserialization & Serialization
+
+- `JsonSerializer` does not deserialize untrusted JSON to `object` or `dynamic`.
+- `BinaryFormatter` is forbidden — flag any usage.
+- XML deserialization disables DTD processing (`XmlReaderSettings.DtdProcessing = Prohibit`).
+
+## Cryptography
+
+- No `MD5` or `SHA1` for security purposes. Use `SHA256+`.
+- No `RandomNumberGenerator.Create()` followed by predictable seeding — use `RandomNumberGenerator.GetBytes()`.
+- AES with `CipherMode.ECB` is forbidden. Prefer authenticated modes (`AesGcm`).
+- No hard-coded IVs or keys.
+
+## Web App Specific
+
+- CSRF protection on state-changing endpoints (cookie auth + non-GET).
+- Anti-forgery tokens for forms.
+- CORS is restrictive — `AllowAnyOrigin` only on read-only public endpoints.
+- HSTS, secure cookies, `SameSite=Lax` minimum.
+- Output encoding — Razor auto-encodes; `Html.Raw` is a code smell that needs justification.
+
+## OWASP Mapping
+
+When reporting, reference the OWASP Top 10 category in parentheses:
+- A01 Broken Access Control
+- A02 Cryptographic Failures
+- A03 Injection
+- A04 Insecure Design
+- A05 Security Misconfiguration
+- A07 Identification & Auth Failures
+- A08 Software & Data Integrity Failures
+- A09 Security Logging Failures
+- A10 SSRF
diff --git a/.claude/skills/dotnet-reviewer/references/severity-taxonomy.md b/.claude/skills/dotnet-reviewer/references/severity-taxonomy.md
new file mode 100644
index 0000000..9aa92c7
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/references/severity-taxonomy.md
@@ -0,0 +1,52 @@
+# Severity Taxonomy and Area Tags
+
+Every finding is tagged `[Severity][Area]` followed by `path:line`.
+
+## Severity Levels
+
+| Severity | When to use | Examples |
+|---|---|---|
+| **Critical** | Ship-blocker. Production correctness, security, data loss, or a failing test. | SQL injection, unhandled `null` deref on hot path, failing test, build error. |
+| **Major** | Will hurt users or maintainers but not a ship-blocker. | Missing input validation on a public API, race condition under load, broken contract with caller. |
+| **Minor** | Real issue, low impact, deserves a fix in this PR. | Build warning, sloppy exception handling, missing log context, dead code. |
+| **Suggestion** | Improvement worth considering. Author can accept or reject. | Refactor opportunity, alternative idiom, better naming, format violation. |
+| **Nitpick** | Cosmetic. Author should ignore unless trivial. | Whitespace, comment phrasing, minor style preference. |
+
+## Area Tags
+
+Pick the **dominant** concern. If two apply, pick the higher-severity area.
+
+| Tag | Scope |
+|---|---|
+| `Security` | Authn/authz, input validation, secrets, injection, deserialization, crypto, OWASP. |
+| `Performance` | Allocations, async/await misuse, EF query shape, hot-path heuristics, Span/Memory. |
+| `Architecture` | Layer/dependency direction, SOLID, DI misuse, pattern consistency, coupling. |
+| `Code-Quality` | Naming, complexity, nullability, IDisposable, dead code, exception strategy. |
+| `Tests` | Missing coverage, flaky tests, weak assertions, test maintenance smell. |
+| `.NET-Idioms` | Version-specific idioms (Primary Ctors, Collection Expressions, Required Members, …). |
+
+## Mapping from Tool Outputs
+
+| Tool finding | Severity | Area |
+|---|---|---|
+| `dotnet build` error | Critical | Code-Quality (or context-driven) |
+| `dotnet build` warning | Minor | Code-Quality |
+| `dotnet test` failure | Critical | Tests |
+| `dotnet format` violation | Suggestion | Code-Quality |
+
+## Examples
+
+```
+[Critical][Security] src/Api/UserController.cs:42
+User input is concatenated directly into a SQL string.
+
+Use parameterized queries via `FromSqlInterpolated` or EF Core's LINQ.
+
+```csharp
+// before
+var users = ctx.Users.FromSqlRaw($"SELECT * FROM Users WHERE Name = '{name}'");
+
+// after
+var users = ctx.Users.FromSqlInterpolated($"SELECT * FROM Users WHERE Name = {name}");
+```
+```
diff --git a/.claude/skills/dotnet-reviewer/scripts/collect-diff.sh b/.claude/skills/dotnet-reviewer/scripts/collect-diff.sh
new file mode 100644
index 0000000..75ecc02
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/scripts/collect-diff.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# collect-diff.sh — collect a unified diff in uncommitted or branch mode.
+# Output JSON: {loc, files, file_list, diff}
+# Exit codes: 0 ok (incl. empty diff), 1 usage, 2 not git, 3 baseline missing.
+
+set -u
+
+usage() {
+  cat <<EOF
+collect-diff.sh — collect a unified diff with exclusions applied
+
+Usage:
+  collect-diff.sh --repo-root <path> --mode uncommitted|branch [--baseline main]
+  collect-diff.sh --help
+
+Exclusions:
+  - .gitignore (implicit via git diff)
+  - *.min.js
+  - wwwroot/lib/**
+
+Exit codes:
+  0  success (empty diff is success)
+  1  usage error
+  2  not a git repository
+  3  baseline branch not found (branch mode only)
+EOF
+}
+
+REPO_ROOT="" MODE="" BASELINE="main"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --mode)      MODE=${2:-};      shift 2 ;;
+    --baseline)  BASELINE=${2:-};  shift 2 ;;
+    --help|-h)   usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" && -n "$MODE" ]] || { usage >&2; exit 1; }
+case "$MODE" in uncommitted|branch) ;; *) echo "invalid --mode: $MODE" >&2; exit 1 ;; esac
+[[ -d "$REPO_ROOT/.git" ]] || { echo "not a git repository: $REPO_ROOT" >&2; exit 2; }
+
+cd "$REPO_ROOT"
+
+if [[ "$MODE" == "branch" ]]; then
+  if ! git rev-parse --verify --quiet "$BASELINE" -- >/dev/null; then
+    echo "baseline branch not found: $BASELINE" >&2
+    exit 3
+  fi
+fi
+
+# Guard: uncommitted mode against an empty repo (no HEAD yet) — abort cleanly.
+if [[ "$MODE" == "uncommitted" ]] && ! git rev-parse --verify --quiet HEAD -- >/dev/null; then
+  echo "repository has no commits yet (HEAD missing)" >&2
+  exit 3
+fi
+
+# pathspec exclusions on top of .gitignore
+EXCLUDES=(
+  ':(exclude)*.min.js'
+  ':(exclude,glob)wwwroot/lib/**'
+)
+
+if [[ "$MODE" == "uncommitted" ]]; then
+  # working-tree changes vs HEAD (staged + unstaged + untracked)
+  diff_payload=$(git diff HEAD --no-renames -- . "${EXCLUDES[@]}")
+  # Append untracked files as added-from-empty diffs
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    diff_payload+=$'\n'$(git diff --no-index --no-renames /dev/null "$f" 2>/dev/null || true)
+  done < <(git ls-files --others --exclude-standard -- . "${EXCLUDES[@]}")
+else
+  diff_payload=$(git diff "$BASELINE"...HEAD --no-renames -- . "${EXCLUDES[@]}")
+fi
+
+# Count files & LOC from the diff
+files=0
+loc=0
+file_list=()
+while IFS= read -r line; do
+  case "$line" in
+    "+++ b/"*) f=${line#+++ b/}; [[ "$f" != "/dev/null" ]] && { file_list+=("$f"); files=$((files+1)); } ;;
+    "+"*|"-"*)
+      [[ "$line" == "+++ "* || "$line" == "--- "* ]] || loc=$((loc+1))
+      ;;
+  esac
+done <<< "$diff_payload"
+
+# emit JSON (escape diff payload for JSON string)
+json_escape() {
+  printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()), end="")'
+}
+
+list_json() {
+  local first=1
+  printf '['
+  for v in "$@"; do
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '"%s"' "${v//\"/\\\"}"
+  done
+  printf ']'
+}
+
+diff_json=$(json_escape "$diff_payload")
+fl_json=$(list_json ${file_list[@]+"${file_list[@]}"})
+
+printf '{"loc":%d,"files":%d,"file_list":%s,"diff":%s}\n' \
+  "$loc" "$files" "$fl_json" "$diff_json"
diff --git a/.claude/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh b/.claude/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh
new file mode 100644
index 0000000..abc16df
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# detect-dotnet-version.sh — Detect .NET SDK and target frameworks in a repo.
+# Outputs JSON: {sdk, target_frameworks[], project_files[]}
+# Exit codes: 0 ok, 1 usage, 4 SDK<10, 5 malformed project file.
+
+set -u
+
+usage() {
+  cat <<EOF
+detect-dotnet-version.sh — detect .NET SDK and target frameworks
+
+Usage: detect-dotnet-version.sh --repo-root <path>
+       detect-dotnet-version.sh --help
+
+Exit codes:
+  0  success
+  1  usage error
+  4  SDK below 10 or no .NET version detected
+  5  malformed global.json or *.csproj
+EOF
+}
+
+REPO_ROOT=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --help|-h)   usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" ]] || { echo "missing --repo-root" >&2; usage >&2; exit 1; }
+[[ -d "$REPO_ROOT" ]] || { echo "not a directory: $REPO_ROOT" >&2; exit 1; }
+
+# --- parse global.json (optional) ---
+SDK="unknown"
+if [[ -f "$REPO_ROOT/global.json" ]]; then
+  SDK=$(grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$REPO_ROOT/global.json" \
+        | head -n1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+  if [[ -z "$SDK" ]]; then
+    echo "malformed global.json: $REPO_ROOT/global.json" >&2
+    exit 5
+  fi
+  sdk_major=${SDK%%.*}
+  if [[ "$sdk_major" =~ ^[0-9]+$ ]] && [[ "$sdk_major" -lt 10 ]]; then
+    echo "global.json pins SDK $SDK; this skill targets .NET 10+" >&2
+    exit 4
+  fi
+fi
+
+# --- find all *.csproj and extract <TargetFramework(s)> ---
+project_files_json="[]"
+tfms_json="[]"
+# bash 3.2 compatible: read into array via while loop
+projects=()
+while IFS= read -r line; do
+  projects+=("$line")
+done < <(find "$REPO_ROOT" -type f -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*' 2>/dev/null | sort)
+
+if [[ ${#projects[@]} -eq 0 ]]; then
+  echo "no *.csproj found under $REPO_ROOT" >&2
+  exit 4
+fi
+
+all_tfms=()
+rel_paths=()
+
+for p in "${projects[@]}"; do
+  rel=${p#"$REPO_ROOT/"}
+  rel_paths+=("$rel")
+  # crude check for malformed XML: must contain </Project>
+  if ! grep -q '</Project>' "$p"; then
+    echo "malformed csproj: $p" >&2
+    exit 5
+  fi
+  # extract single or plural element
+  tfm_line=$(grep -oE '<TargetFramework[s]?>[^<]+</TargetFramework[s]?>' "$p" | head -n1 || true)
+  if [[ -z "$tfm_line" ]]; then
+    echo "no TargetFramework in: $p" >&2
+    exit 5
+  fi
+  tfm_value=$(printf '%s' "$tfm_line" | sed -E 's|<TargetFrameworks?>([^<]+)</TargetFrameworks?>|\1|')
+  IFS=';' read -r -a parts <<<"$tfm_value"
+  for t in "${parts[@]}"; do
+    [[ -n "$t" ]] && all_tfms+=("$t")
+  done
+done
+
+# --- enforce .NET 10+ ---
+ok=0
+for t in "${all_tfms[@]}"; do
+  if [[ "$t" =~ ^net([0-9]+)\.[0-9]+$ ]]; then
+    major=${BASH_REMATCH[1]}
+    if [[ $major -ge 10 ]]; then ok=1; break; fi
+  fi
+done
+
+if [[ $ok -eq 0 ]]; then
+  echo "no target framework >= net10.0 detected; found: ${all_tfms[*]}" >&2
+  exit 4
+fi
+
+# --- emit JSON (manual, jq-free) ---
+json_array() {
+  local first=1
+  printf '['
+  for v in "$@"; do
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '"%s"' "${v//\"/\\\"}"
+  done
+  printf ']'
+}
+
+tfms_json=$(json_array "${all_tfms[@]}")
+project_files_json=$(json_array "${rel_paths[@]}")
+
+printf '{"sdk":"%s","target_frameworks":%s,"project_files":%s}\n' \
+  "$SDK" "$tfms_json" "$project_files_json"
diff --git a/.claude/skills/dotnet-reviewer/scripts/run-checks.sh b/.claude/skills/dotnet-reviewer/scripts/run-checks.sh
new file mode 100644
index 0000000..df5fbea
--- /dev/null
+++ b/.claude/skills/dotnet-reviewer/scripts/run-checks.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# run-checks.sh — run optional dotnet build|format|test, emit structured JSON.
+# Output JSON: {build:{ok,warnings[],errors[]}|null, format:{ok,violations[]}|null, test:{ok,failed[],duration}|null}
+# Always exits 0 (tool failures are reported in JSON, not via exit code) unless usage error.
+# DOTNET_BIN env overrides `dotnet` (used by tests).
+
+set -u
+
+usage() {
+  cat <<EOF
+run-checks.sh — run dotnet build/format/test and emit structured JSON
+
+Usage:
+  run-checks.sh --repo-root <path> [--build] [--format] [--test]
+  run-checks.sh --help
+
+Each requested check runs independently; failures are reported in JSON, not via exit code.
+Set DOTNET_BIN to override the dotnet binary path (used by tests).
+EOF
+}
+
+REPO_ROOT=""; DO_BUILD=0; DO_FORMAT=0; DO_TEST=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --build)  DO_BUILD=1; shift ;;
+    --format) DO_FORMAT=1; shift ;;
+    --test)   DO_TEST=1; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" && -d "$REPO_ROOT" ]] || { usage >&2; exit 1; }
+
+DOTNET=${DOTNET_BIN:-dotnet}
+
+run_dotnet() {
+  # captures stdout+stderr into the named variable, returns the exit code
+  local _out_var=$1; shift
+  local _tmp; _tmp=$(mktemp)
+  local _rc=0
+  # shellcheck disable=SC2086
+  ( cd "$REPO_ROOT" && $DOTNET "$@" ) >"$_tmp" 2>&1 || _rc=$?
+  printf -v "$_out_var" '%s' "$(cat "$_tmp")"
+  rm -f "$_tmp"
+  return "$_rc"
+}
+
+json_string() {
+  python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()), end="")' <<<"$1"
+}
+
+json_string_array() {
+  local first=1
+  printf '['
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '%s' "$(json_string "$line")"
+  done <<<"$1"
+  printf ']'
+}
+
+BUILD_JSON="null"
+if [[ $DO_BUILD -eq 1 ]]; then
+  out=""
+  run_dotnet out build --nologo --verbosity minimal || true
+  warnings=$(grep -E ': warning [A-Z]+[0-9]+' <<<"$out" || true)
+  errors=$(grep -E ': error [A-Z]+[0-9]+' <<<"$out" || true)
+  ok="true"; [[ -n "$errors" ]] && ok="false"
+  BUILD_JSON=$(printf '{"ok":%s,"warnings":%s,"errors":%s}' \
+    "$ok" \
+    "$(json_string_array "$warnings")" \
+    "$(json_string_array "$errors")")
+fi
+
+FORMAT_JSON="null"
+if [[ $DO_FORMAT -eq 1 ]]; then
+  out=""
+  rc=0
+  run_dotnet out format --verify-no-changes --no-restore || rc=$?
+  violations=$(grep -E '\([0-9]+,[0-9]+\)' <<<"$out" || true)
+  ok="true"; [[ $rc -ne 0 ]] && ok="false"
+  FORMAT_JSON=$(printf '{"ok":%s,"violations":%s}' \
+    "$ok" "$(json_string_array "$violations")")
+fi
+
+TEST_JSON="null"
+if [[ $DO_TEST -eq 1 ]]; then
+  out=""
+  rc=0
+  start=$(date +%s)
+  run_dotnet out test --nologo --verbosity minimal || rc=$?
+  end=$(date +%s)
+  failed=$(grep -E '^Failed:' <<<"$out" || true)
+  ok="true"; [[ $rc -ne 0 ]] && ok="false"
+  TEST_JSON=$(printf '{"ok":%s,"failed":%s,"duration":%d}' \
+    "$ok" "$(json_string_array "$failed")" "$((end - start))")
+fi
+
+printf '{"build":%s,"format":%s,"test":%s}\n' "$BUILD_JSON" "$FORMAT_JSON" "$TEST_JSON"
diff --git a/.claude/skills/dotnet-sdk-builder/SKILL.md b/.claude/skills/dotnet-sdk-builder/SKILL.md
index 2f7f0c3..fafbf4d 100644
--- a/.claude/skills/dotnet-sdk-builder/SKILL.md
+++ b/.claude/skills/dotnet-sdk-builder/SKILL.md
@@ -1,12 +1,19 @@
 ---
 name: dotnet-sdk-builder
-description: Generates complete .NET SDK libraries with DI support, interfaces, typed HTTP clients, Options pattern, and typed exceptions. Use when asked to create a .NET SDK, build a .NET client library, wrap a REST API in C#, or generate a typed HTTP client. Invokes csharp-docs for XML documentation and tester for tests.
+description: Generates complete .NET SDK libraries with DI support, interfaces, typed HTTP clients, Options pattern, and typed exceptions. Use when asked to create a .NET SDK, build a .NET client library, wrap a REST API in C#, or generate a typed HTTP client. Invokes dotnet-xmldocs for XML documentation and dotnet-tester for tests.
 ---
 
 # .NET SDK Library Builder
 
 Generate complete, production-ready .NET SDK libraries from existing C# classes or API documentation. The output follows Microsoft's library design guidelines with full DI support, testability via interfaces, and idiomatic C# patterns.
 
+## When to Use
+
+- Building a new .NET SDK or client library from existing C# classes, OpenAPI/Swagger specs, or REST API docs
+- Wrapping a REST API in a typed C# client with DI registration (`AddXxx(...)`)
+- Generating typed HTTP clients with `IHttpClientFactory`, Options pattern, and typed exceptions
+- Producing libraries that follow Microsoft's library design guidelines (interface-first, no static state)
+
 ## Workflow Overview
 
 Follow these steps in order. See the reference files for detailed guidance on each phase.
@@ -92,26 +99,15 @@ Generate all components. See [di-patterns.md](references/di-patterns.md) and [ht
 | `XxxException` (+ subtypes) | Typed exceptions with diagnostic properties |
 | Model classes | Request/response DTOs |
 
-**NuGet packages to add:**
-
-```xml
-<PackageReference Include="Microsoft.Extensions.Http" Version="*" />
-<PackageReference Include="Microsoft.Extensions.Options" Version="*" />
-<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="*" />
-<!-- If resilience requested: -->
-<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="*" />
-```
-
-Always use the latest stable, compatible with target framework version.
-Always use skill 'nuget-manager' for managing NuGet packages and package versions. 
+**Required NuGet packages:** `Microsoft.Extensions.Http`, `Microsoft.Extensions.Options`, `Microsoft.Extensions.DependencyInjection.Abstractions` — plus `Microsoft.Extensions.Http.Resilience` if Step 5 selected resilience. Use the `dotnet-nuget-manager` skill to add them; do not edit `.csproj` directly.
 
 ### Step 8: Document the Code
 
-After generating all source files, invoke the `csharp-docs` skill to add XML documentation comments to all public types and members.
+After generating all source files, invoke the `dotnet-xmldocs` skill to add XML documentation comments to all public types and members.
 
 ### Step 9: Write Tests
 
-After documentation is complete, invoke the `tester` skill to generate unit and integration tests for the library.
+After documentation is complete, invoke the `dotnet-tester` skill to generate unit and integration tests for the library.
 
 ## Key Design Principles
 
@@ -127,3 +123,12 @@ After documentation is complete, invoke the `tester` skill to generate unit and
 - **[di-patterns.md](references/di-patterns.md)** — DI registration, Options pattern, extension method patterns
 - **[http-client-patterns.md](references/http-client-patterns.md)** — IHttpClientFactory, typed clients, resilience, typed exceptions
 - **[project-setup.md](references/project-setup.md)** — New project structure, folder layout, `.csproj` conventions
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Provides the DI, Options, and configuration patterns this skill emits in generated SDKs
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — Invoked in Step 8 to document generated SDKs with XML comments
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Invoked in Step 9 to generate unit and integration tests
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Invoked in Step 7 to add SDK runtime dependencies
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Queries existing libraries when generating SDK wrappers
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Generates typed HTTP clients for consuming ASP.NET Core APIs
diff --git a/.claude/skills/dotnet-sdk-builder/references/project-setup.md b/.claude/skills/dotnet-sdk-builder/references/project-setup.md
index 4ffda6f..db141d3 100644
--- a/.claude/skills/dotnet-sdk-builder/references/project-setup.md
+++ b/.claude/skills/dotnet-sdk-builder/references/project-setup.md
@@ -36,7 +36,7 @@ Always ask the user for confirmation before creating a new project if not explic
 **Key settings:**
 - `<Nullable>enable</Nullable>` — always for new projects when .NET version supports it.
 - `<GenerateDocumentationFile>true</GenerateDocumentationFile>` — required for XML doc generation.
-- `<NoWarn>CS1591</NoWarn>` — suppress "missing XML comment" warnings during development; remove after `csharp-docs` skill adds all docs.
+- `<NoWarn>CS1591</NoWarn>` — suppress "missing XML comment" warnings during development; remove after `dotnet-xmldocs` skill adds all docs.
 - `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` — enforces code quality.
 - `<LangVersion>latest</LangVersion>` — enables the latest C# features for the target framework.
 
@@ -69,6 +69,8 @@ MyCompany.GitHub/
 - No `Services/` or `Abstractions/` sub-folders for small libraries — keep it flat.
 - For larger libraries with multiple API areas, group by area: `Repositories/`, `Users/`, etc.
 
+> This layout applies to **library** projects. Web/API applications should organize by feature/domain instead — see the `dotnet-aspnet` skill.
+
 ## Naming Conventions
 
 | Artifact | Pattern | Example |
diff --git a/.claude/skills/dotnet-tester/SKILL.md b/.claude/skills/dotnet-tester/SKILL.md
index dfb91ba..12775ff 100644
--- a/.claude/skills/dotnet-tester/SKILL.md
+++ b/.claude/skills/dotnet-tester/SKILL.md
@@ -3,8 +3,19 @@ name: dotnet-tester
 description: Writes, executes, and completes unit tests for C#/.NET code using xUnit, FakeItEasy, and AwesomeAssertions. Uses a second agent to identify missing test cases. Use when asked to create .NET tests or improve test coverage.
 ---
 
+# .NET Tester
+
 Write comprehensive unit tests for the specified code. Follow a multi-step process with automatic identification of missing test cases.
 
+## When to Use
+
+- User asks to create unit tests, add tests, or improve test coverage for C#/.NET code
+- New C#/.NET production code lacks tests and needs them
+- An existing test suite is missing edge cases or error-path coverage
+- Working in a C# project that uses xUnit, FakeItEasy, AwesomeAssertions/FluentAssertions, NUnit, MSTest, or Moq
+
+Do **not** use this skill for non-.NET test code, or for integration tests that primarily exercise external systems without unit-level concerns.
+
 ## Conventions
 
 - **Test Framework**: xUnit
@@ -12,7 +23,7 @@ Write comprehensive unit tests for the specified code. Follow a multi-step proce
 - **Assertions**: AwesomeAssertions (a fork of FluentAssertions with identical API — use `Should()` as usual)
 - **Structure**: Each test method has Arrange/Act/Assert blocks, marked with comments
 - **Language**: English for code, comments, and test names
-- **Style**: Adopt the existing test style from nearby test files in the project
+- **Style**: The stack above is the default. If the project already uses a different stack (NUnit, MSTest, Moq, FluentAssertions, …), match the existing convention instead of switching.
 
 ## Phase 1: Write Tests
 
@@ -113,8 +124,17 @@ At the end, provide a summary:
 ## Important Notes
 
 - Do **not write tests for trivial getters/setters** without logic
+- Do **not write tests to check if properties are initialized correctly after construction**
 - Do **not mock value types** or simple DTOs – create real instances
 - Test **behavior**, not implementation details
 - Use **descriptive test names** in the format `MethodName_Scenario_ExpectedBehavior`
 - For `[Theory]` tests: Use `[InlineData]` for simple types, `[MemberData]` for complex objects
 - Use `A.CallTo(...).MustHaveHappened()` sparingly – only when the call is the expected behavior
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Test DI-registered services using `IServiceCollection` overrides
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — DbContext-backed unit and integration tests (SQLite in-memory, Testcontainers)
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Test-quality checks during code review
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invoked by it in Step 9 to generate tests for new SDK libraries
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Unit and integration tests for ASP.NET Core endpoints
diff --git a/.claude/skills/dotnet-xmldocs/SKILL.md b/.claude/skills/dotnet-xmldocs/SKILL.md
new file mode 100644
index 0000000..b688596
--- /dev/null
+++ b/.claude/skills/dotnet-xmldocs/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: dotnet-xmldocs
+description: Adds and reviews C# XML documentation comments following Microsoft's documentation standards. Use when writing or reviewing C# code that includes public APIs, complex logic, or when documentation is missing or insufficient. Covers <summary>, <param>, <returns>, <exception>, <remarks>, and all standard XML doc tags.
+---
+
+# C# Documentation Best Practices
+
+## When to Use
+
+- Writing or reviewing XML documentation comments (`///`) on C# types and members
+- Adding documentation to public APIs of a new or existing C# library
+- Reviewing missing, insufficient, or non-Microsoft-style XML docs in C# code
+- Generating documentation that feeds OpenAPI/Swagger output or NuGet symbols
+
+## General Guidelines
+
+- Public members should be documented with XML comments.
+- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.
+
+## Guidance for all APIs
+
+- Use `<summary>` to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb.
+- Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context.
+- Use `<see langword>` for language-specific keywords like `null`, `true`, `false`, `int`, `bool`, etc.
+- Use `<c>` for inline code snippets.
+- Use `<example>` for usage examples on how to use the member.
+  - Use `<code>` for code blocks. `<code>` tags should be placed within an `<example>` tag. Add the language of the code example using the `language` attribute, for example, `<code language="csharp">`.
+- Use `<see cref>` to reference other types or members inline (in a sentence).
+- Use `<seealso>` for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs.
+- Use `<inheritdoc/>` to inherit documentation from base classes or interfaces.
+  - Unless there is major behavior change, in which case you should document the differences.
+
+## Member-Specific Rules
+
+See [member-documentation-rules.md](./references/member-documentation-rules.md) for detailed wording conventions for methods (`<param>`, `<returns>`), constructors, properties (`<value>`, Gets/Sets patterns), and exceptions (`<exception cref>`).
+
+## Related Skills
+
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — XML docs feed OpenAPI/Swagger output
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invokes this skill in Step 8 to document generated SDKs
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Code-quality checklist references these conventions for public-API docs
diff --git a/.claude/skills/dotnet-xmldocs/references/member-documentation-rules.md b/.claude/skills/dotnet-xmldocs/references/member-documentation-rules.md
new file mode 100644
index 0000000..8f58133
--- /dev/null
+++ b/.claude/skills/dotnet-xmldocs/references/member-documentation-rules.md
@@ -0,0 +1,41 @@
+# Member-Specific Documentation Rules
+
+## Methods
+
+- Use `<param>` to describe method parameters.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...".
+  - If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...".
+  - If the parameter is a Boolean, the wording should be of the form "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`.".
+  - If the parameter is an "out" parameter, the wording should be of the form "When this method returns, contains .... This parameter is treated as uninitialized.".
+- Use `<paramref>` to reference parameter names in documentation.
+- Use `<typeparam>` to describe type parameters in generic types or methods.
+- Use `<typeparamref>` to reference type parameters in documentation.
+- Use `<returns>` to describe what the method returns.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the return type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`.".
+
+## Constructors
+
+- The summary wording should be "Initializes a new instance of the <Class> class [or struct].".
+
+## Properties
+
+- The `<summary>` should start with:
+  - "Gets or sets..." for a read-write property.
+  - "Gets..." for a read-only property.
+  - "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value.
+- Use `<value>` to describe the value of the property.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - If the property has a default value, add it in a separate sentence, for example, "The default is `<see langword="false" />`".
+  - If the value type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ...".
+
+## Exceptions
+
+- Use `<exception cref>` to document exceptions thrown by constructors, properties, indexers, methods, operators, and events.
+- Document all exceptions thrown directly by the member.
+- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter.
+- The description of the exception describes the condition under which it's thrown.
+  - Omit "Thrown if ..." or "If ..." at the beginning of the sentence. Just state the condition directly, for example "An error occurred when accessing a Message Queuing API."
diff --git a/.claude/skills/dotnet/SKILL.md b/.claude/skills/dotnet/SKILL.md
new file mode 100644
index 0000000..6766638
--- /dev/null
+++ b/.claude/skills/dotnet/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: dotnet
+description: Entry point and router for .NET and C# work — directs you to the right specialized .NET skill. Use when a request mentions .NET or C# in general but the specific tool is not obvious, or to get an overview of the available .NET skills. Routes to knowledge skills (dotnet-fundamentals, dotnet-aspnet, dotnet-ef-core, dotnet-xmldocs) and workflow skills (dotnet-sdk-builder, dotnet-tester, dotnet-reviewer, dotnet-inspect, dotnet-nuget-manager). When the matching skill is already clear, invoke that skill directly instead.
+---
+
+# .NET / C# Skill Router
+
+Signpost to the specialized .NET skills. This skill holds no best-practice knowledge
+of its own — it maps a request to the appropriate specialized skill.
+
+## When to Use
+
+- A task concerns .NET or C#, but it is unclear which specialized skill applies.
+- You need an overview of the available .NET skills and their responsibilities.
+
+When the matching skill is already clear, load it directly — the router is only
+orientation, not an intermediate step.
+
+## Routing
+
+### Knowledge skills (best practices, `references/` only)
+
+| Concern | Skill |
+|---------|-------|
+| Dependency Injection, Options pattern, Configuration, modern C# idioms (for any .NET host) | `dotnet-fundamentals` |
+| ASP.NET Core Web/REST APIs: controllers, Minimal APIs, middleware, routing, model binding, validation, auth, ProblemDetails, OpenAPI, health checks, CORS, rate limiting | `dotnet-aspnet` |
+| Entity Framework Core: DbContext, entities/relationships, LINQ, migrations, repository patterns, N+1/performance | `dotnet-ef-core` |
+| C# XML doc comments (`<summary>`, `<param>`, `<returns>`, …) | `dotnet-xmldocs` |
+
+### Workflow skills (active tools, scripts, agents)
+
+| Concern | Skill |
+|---------|-------|
+| Generate a .NET SDK / client library / typed HTTP client | `dotnet-sdk-builder` |
+| Write/run unit tests (xUnit, FakeItEasy, AwesomeAssertions) | `dotnet-tester` |
+| Structured code review for .NET 10+ (explicit invocation only, see below) | `dotnet-reviewer` |
+| Query .NET APIs in NuGet packages, platform libraries, or local files | `dotnet-inspect` |
+| Manage NuGet packages (add/remove/update, `--outdated`, Central Package Management) | `dotnet-nuget-manager` |
+
+## Notes
+
+- **`dotnet-reviewer` activates only on explicit name** — the phrases
+  `dotnet-reviewer`, `dotnet code review`, or `dotnet review`. It does **not** trigger
+  on generic "review my code", and the router does not trigger it automatically.
+- **Composition:** `dotnet-sdk-builder` invokes `dotnet-xmldocs` and `dotnet-tester`;
+  `dotnet-aspnet` and `dotnet-ef-core` build on `dotnet-fundamentals`.
diff --git a/.claude/skills/implementer/SKILL.md b/.claude/skills/implementer/SKILL.md
new file mode 100644
index 0000000..d1f0aa7
--- /dev/null
+++ b/.claude/skills/implementer/SKILL.md
@@ -0,0 +1,255 @@
+---
+name: implementer
+description: >
+  Iterative implementation workflow for requirements. Use this skill when asked to
+  implement a feature, user story, requirement, or change request. Guides through
+  5 phases: requirement review, implementation planning, sub-agent-driven implementation
+  (code, tests, documentation), code review with rework loop, and final summary.
+  Never commits code — the user always commits manually.
+allowed-tools: Read Grep Glob Edit Create Task
+---
+
+# Implementer — Iterative Requirement Implementation Flow
+
+An iterative, structured workflow for implementing requirements end-to-end.
+Covers production code, tests, and documentation updates in every cycle.
+
+> **CRITICAL RULE — NO COMMITS:** You must NEVER commit code or create git commits.
+> The user always commits manually. If asked to commit, skip that request and inform
+> the user that committing is their responsibility.
+
+> **CRITICAL RULE — USE SPECIALIZED SKILLS:** Never implement, test, document, or review
+> with only your built-in knowledge when a specialized skill for the detected technology
+> exists. Discover available skills at runtime and use them. This skill names NO concrete
+> skills on purpose — it works with whatever skills exist now or are added later.
+
+## Flow Overview
+
+```
+Phase 1: Requirement Review
+    ↓
+Phase 2: Implementation Plan
+    ↓
+Phase 3: Implementation (Sub-Agents) ◄──┐
+    ↓                                    │
+Phase 4: Review (Sub-Agent)              │
+    ↓ (rework needed?)──────────────────►┘
+    ↓ (all good)
+Phase 5: Summary
+```
+
+## Skill Discovery & Capability Slots
+
+This workflow relies on **discovering specialized skills at runtime** rather than naming
+them. Concrete skill names change over time — names are never hardcoded here.
+
+**How discovery works:**
+
+1. **Detect the tech stack** by *signals* (manifest/build files, source extensions, configs),
+   per affected file/module — repos may mix stacks. Examples like `*.csproj` → .NET or
+   `package.json` → TypeScript are illustrative only; infer any stack from its signals
+   (see [Phase 1.5](references/REFERENCE.md#phase-15)).
+2. **List the available skills** using your runtime's skill-listing mechanism (do not assume
+   a fixed directory).
+3. **Classify each skill by its `description`** — match purpose and technology from the text,
+   never from the name — and fill these **capability slots**:
+
+| Slot | Filled by a skill whose description covers… | Used in |
+|------|---------------------------------------------|---------|
+| `language-implementation` | writing code for the detected stack | Phase 3 |
+| `language-testing` | the stack's test framework / test conventions | Phase 3 |
+| `language-docs` | the stack's documentation conventions | Phase 3 |
+| `language-review` | reviewing code for the detected stack | Phase 4 |
+| `build-deps` | builds / package & dependency management | Phase 3 |
+
+Always show the capability slots to the user.
+**Usage rule:** If a slot is filled, you MUST use that skill for the matching work and pass
+it as context to any sub-agent doing that work (sub-agents are stateless). If no skill
+matches a slot, fall back to generic conventions and note the empty slot in the plan. if you delegate work to a sub-agent,
+you MUST pass the slot skill explicitly.
+
+**Slot fulfillment is by invocation, not by listing.** A capability slot counts as fulfilled
+only when its skill has been invoked via the `Skill` tool **in this conversation, for this
+task**. Listing a skill in the slot table, paraphrasing its description, or relying on prior
+knowledge of the technology does NOT count as fulfillment. The rule is identical whether you
+do the work yourself or dispatch a sub-agent — self-execution does not waive the
+invocation, and a sub-agent invocation does not waive it for the main agent's own
+follow-up edits.
+
+**A single task may have multiple slots filled at once** (e.g. implementation + testing +
+documentation in one task, or two language-implementation slots when a stack mixes
+sub-technologies). In that case every assigned slot must be invoked independently — one
+slot's invocation never substitutes for another's, and you must not collapse the
+invocations even when the same task touches all of them. Invocations from a previous task
+do NOT carry over either; re-invoke at the start of every task where the slot applies.
+
+## Phase 1 — Requirement Review
+
+Analyze the requirement before any code is written:
+
+1. Read and understand the requirement thoroughly
+2. Identify acceptance criteria (explicit and implicit)
+3. Clarify ambiguities — ask the user targeted questions using the ask_user tool
+4. Identify affected components, files, and modules in the current codebase
+5. Check for existing tests, documentation, and related code
+6. **Detect the tech stack and run skill discovery** (see *Skill Discovery & Capability
+   Slots*): build the capability-slot map for the affected areas
+
+**Output:** Confirmed understanding of the requirement, resolved ambiguities, identified
+scope, and the filled capability-slot map (with any empty slots noted).
+
+## Phase 2 — Implementation Plan
+
+Create a structured plan with trackable tasks:
+
+1. Break the requirement into discrete implementation tasks
+2. Each task MUST include all three aspects:
+  - **Production code** changes
+  - **Test** additions or updates
+  - **Documentation** updates (if applicable)
+3. **Each task MUST publish a Skill-prerequisite checklist** listing every capability slot
+   it depends on (from the Phase 1 discovery). The checklist is part of the plan text the
+   user sees; it is not optional, and it is not collapsed even when a task touches every
+   slot. The format is:
+
+   ```
+   Task #N: <subject>
+     Skill prerequisites (Step 0 of Phase 3):
+       [ ] <slot-id>            — filled by "<skill name from discovery>"
+       [ ] <other-slot-id>      — filled by "<other skill name>"
+       [ ] <slot-id-with-gap>   — EMPTY (no matching skill; generic fallback)
+   ```
+
+   When Step 0 fires in Phase 3, each `[ ]` is replaced with `[x]` (or annotated with
+   "n/a — slot empty" for empty slots). Multiple skills filling the same slot get their own
+   line each. The same skill appearing in two different slots is two separate
+   prerequisites — never deduplicated.
+4. Define task dependencies (what must be done first)
+5. Identify tasks that can be parallelized via sub-agents
+
+**Output:** Task list with dependencies and a per-task Skill-prerequisite checklist, ready
+for implementation. Any task missing its checklist is not a valid plan entry.
+
+## Phase 3 — Implementation
+
+Execute tasks using sub-agents for parallel work where possible:
+
+1. For each task (or group of independent tasks):
+  - **Step 0 — invoke every assigned slot skill.** Before any `Write`, `Edit`, or
+    code-producing `Bash` call for this task, call the `Skill` tool **once per capability
+    slot** the task is assigned to. If the task has multiple slots (e.g.
+    `language-implementation` + `language-testing` + `language-docs` at the same time, or
+    two slots of the same kind), invoke them all — one invocation never substitutes for
+    another. Wait for each skill's content to load and follow its workflow when producing
+    the corresponding artifact. A skill invocation made for a previous task does NOT carry
+    over; re-invoke per task.
+  - Delegate to sub-agents (explore for research, task for builds/tests, general-purpose
+    for complex changes), passing the relevant slot skill(s) as context. Sub-agent
+    dispatch is in addition to — not instead of — Step 0: the main agent still needs the
+    slot's workflow loaded for any follow-up edits it makes itself.
+  - Implement production code changes using the skill(s) filling the
+    `language-implementation` slot.
+  - Write or update tests using the skill(s) filling the `language-testing` slot.
+  - Update relevant documentation using the skill(s) filling the `language-docs` slot.
+2. Run existing tests and linters to verify changes don't break anything (use the
+   `build-deps` slot if filled — invoke it the same way as any other slot).
+3. Track task completion status. Only mark a task `completed` once every slot assigned to
+   it has been invoked AND the corresponding artifact (code / tests / docs) has been
+   produced or explicitly recorded as not-applicable for this task.
+
+**Important:** Respect the project's existing conventions, patterns, and tooling. If a
+capability slot is filled, you MUST use it; only fall back to generic work when the slot is
+empty.
+
+### Worked example — beginning a task with multiple slots
+
+Suppose Task #N has three slots assigned: `language-implementation`, `language-testing`,
+and `language-docs`, each filled by some discovered skill. The correct opening of the task
+looks like this (skill names are placeholders — substitute whatever Phase 1 discovery
+produced for each slot):
+
+```
+TaskUpdate(taskId=N, status=in_progress)
+Skill(skill="<skill filling language-implementation>")   ← MUST fire before production-code Write/Edit
+Skill(skill="<skill filling language-testing>")          ← MUST fire before test-code Write/Edit
+Skill(skill="<skill filling language-docs>")             ← MUST fire before doc Write/Edit
+# ...follow each invoked skill's workflow...
+Write(file_path=".../<production file>", content=...)
+Write(file_path=".../<test file>",       content=...)
+Edit(file_path=".../<doc file>",         ...)
+```
+
+Notes:
+
+- Three slots → three `Skill(...)` calls. Two slots → two calls. Five → five. No collapsing.
+- If you dispatch a sub-agent for one of the slots, the `Skill(...)` call still happens
+  here in the main conversation first, and the slot skill name is also passed to the
+  sub-agent prompt.
+- Omitting any `Skill(...)` line above is exactly the failure mode the rules in this
+  section exist to prevent.
+
+## Phase 4 — Review
+
+Run a thorough code review using a sub-agent:
+
+1. Launch a code-review sub-agent to analyze all changes made. If the `language-review` slot
+   is filled, use that skill (it knows stack-specific pitfalls); otherwise use a generic
+   review. When both a stack-specific and a generic review skill exist, combine them.
+2. The review checks for:
+  - Correctness and completeness against the requirement
+  - Test coverage for new/changed code
+  - Documentation accuracy
+  - Code quality, potential bugs, and security issues
+3. Evaluate review findings:
+  - **Rework needed:** Create new tasks for findings and return to **Phase 3**
+  - **All good:** Proceed to **Phase 5**
+
+## Phase 5 — Summary
+
+Provide a comprehensive summary of all work done:
+
+1. List all files created or modified
+2. Describe what was implemented and why
+3. List all tests added or updated
+4. List all documentation changes
+5. Note any decisions made during implementation
+6. Highlight anything the user should review before committing
+7. **Publish the Skill-invocation log.** For every task in the plan, reproduce the
+   Skill-prerequisite checklist from Phase 2 with each entry resolved. Each line MUST
+   carry one of three states, with evidence:
+
+  - `[x] <slot-id> — invoked at <evidence>` — `<evidence>` is a verifiable pointer such
+    as "turn N", "before Write of `<file>`", or the exact `Skill(skill="…")` call. Generic
+    phrases like "considered" or "applied" are NOT acceptable evidence.
+  - `[n/a] <slot-id> — empty in Phase 1 discovery; generic fallback used` — only valid
+    when Phase 1 left the slot empty.
+  - `[!] <slot-id> — NOT invoked` — a workflow violation. Whenever this state appears you
+    MUST (a) name it explicitly here as a violation, (b) NOT mark the affected task as
+    truly complete in your prose summary, and (c) recommend a concrete follow-up pass
+    that re-runs the missing slot's workflow on the produced artifact.
+
+   The log is mandatory even when every slot was invoked correctly — it serves as the
+   audit trail for the user. If the plan contained no tasks (e.g. requirement was a
+   no-op), state that explicitly instead of omitting the log.
+
+> **Reminder:** The user will commit the changes themselves. Do NOT create any commits.
+
+## Red Flags — Do Not Skip Specialized Skills
+
+If you catch yourself thinking any of these, STOP and use the discovered slot skill:
+
+| Rationalization | Reality |
+|-----------------|---------|
+| "I already know this language well" | The skill may encode project-specific conventions you don't know. Consult it. |
+| "It's a tiny change, no skill needed" | Small changes still follow the stack's patterns. Use the slot. |
+| "I'll just use the generic approach" | Generic is the fallback ONLY when no slot skill exists. |
+| "Discovery takes too long" | Discovery is one listing + classification. Skipping it produces off-convention code. |
+| "The sub-agent will figure it out" | Sub-agents are stateless — pass them the slot skill explicitly. |
+| "I already listed the slot in the plan" | A listed slot is not an invoked skill. The slot is only fulfilled when the `Skill` tool has fired in this conversation for this task. |
+| "I'll just do this small bit myself instead of dispatching" | Self-execution does NOT waive the slot requirement. Invoke the slot skill first, then write. |
+| "One slot covers everything in this task" | Each filled slot is its own workflow. Implementation, testing, documentation, build, and review slots must each be invoked when assigned — never collapse them. |
+| "The slot was invoked in the previous task" | Invocations do NOT carry over between tasks. Re-invoke at the start of every task the slot applies to. |
+
+---
+
+For detailed guidance on each phase, see [references/REFERENCE.md](references/REFERENCE.md).
diff --git a/.claude/skills/implementer/references/REFERENCE.md b/.claude/skills/implementer/references/REFERENCE.md
new file mode 100644
index 0000000..261b37e
--- /dev/null
+++ b/.claude/skills/implementer/references/REFERENCE.md
@@ -0,0 +1,326 @@
+# Implementer Skill — Detailed Reference
+
+This document provides in-depth guidance for each phase of the implementer workflow.
+
+---
+
+## Phase 1 — Requirement Review (Detail)
+
+### Goal
+
+Ensure a thorough understanding of the requirement before any implementation begins.
+Prevent wasted effort from misunderstood requirements or unclear scope.
+
+### Steps
+
+#### 1.1 Read the Requirement
+
+- Read the full requirement text (issue, user story, ticket, or user message)
+- Identify the core objective: What should change? What is the expected outcome?
+
+#### 1.2 Identify Acceptance Criteria
+
+- Extract explicit acceptance criteria from the requirement
+- Derive implicit criteria from context (e.g., existing tests must still pass, existing API contracts must be honored)
+- List edge cases that should be covered
+
+#### 1.3 Clarify Ambiguities
+
+- If anything is unclear, use the `ask_user` tool to ask targeted questions
+- Do NOT assume answers to ambiguous requirements — always ask
+- Common ambiguities to watch for:
+  - Scope boundaries (what is in/out)
+  - Error handling behavior
+  - Performance expectations
+  - Backward compatibility requirements
+
+#### 1.4 Analyze the Codebase
+
+- Identify files, modules, and components affected by the requirement
+- Understand the existing architecture and patterns in the affected area
+- Look for existing tests that cover the affected area
+- Check for documentation that needs updating
+- Use explore sub-agents for large codebase investigations
+
+#### 1.5 Detect Stack & Discover Skills
+
+This step builds the **capability-slot map** used by all later phases. Never hardcode skill
+names — classify by each skill's `description`.
+
+1. **Detect the tech stack** per affected file/module (repos may be multi-stack). Detect by
+   *signals*, not a fixed list — this keeps detection working for stacks not yet imagined:
+   - **Manifest / build files** declaring language, dependencies, or build config
+     (e.g. a `*.csproj`, `pom.xml`/`build.gradle`, `package.json`, `pyproject.toml`,
+     `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`). These are the strongest signal.
+   - **Source file extensions** of the affected files (e.g. `.cs`, `.java`, `.ts`, `.go`).
+   - **Lockfiles, toolchain configs, and CI files** that name a runtime or framework.
+   - **Framework markers** inside manifests/configs (a dependency name often identifies the
+     framework, not just the language).
+
+   The list above is illustrative, not exhaustive. The rule is: infer language + framework
+   from whatever build/manifest/config/source signals are present, then map that stack to
+   capability slots — regardless of whether this skill ever mentioned that stack.
+2. **List the available skills** using your runtime's own skill-listing mechanism. Do NOT
+   assume a fixed directory — the location varies across platforms (Claude Code, Copilot,
+   Codex) and across repos.
+3. **Classify each skill by its `description`** and fill the capability slots:
+   `language-implementation`, `language-testing`, `language-docs`, `language-review`,
+   `build-deps`. Match on purpose + technology mentioned in the description, never on name.
+4. For multi-stack repos, maintain a slot map **per stack** and select the right one per task.
+5. Review instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) and
+   follow any project conventions and coding standards found.
+
+Record empty slots explicitly — they mean "use the generic fallback" for that work.
+
+### Output
+
+Present the user with:
+- A summary of the requirement in your own words
+- The identified acceptance criteria
+- Any clarifying questions (if applicable)
+- The affected areas of the codebase
+- The detected tech stack(s) and the filled capability-slot map (note any empty slots)
+
+Wait for user confirmation before proceeding to Phase 2.
+
+---
+
+## Phase 2 — Implementation Plan (Detail)
+
+### Goal
+
+Create a clear, trackable plan that breaks the requirement into discrete tasks.
+Each task should be self-contained and include code, tests, and documentation.
+
+### Steps
+
+#### 2.1 Define Tasks
+
+- Break the requirement into the smallest reasonable tasks
+- Each task should be completable independently (or with clear dependencies)
+- Use descriptive kebab-case IDs for task tracking
+- Every task description must include enough detail to execute without referring back to the plan
+
+#### 2.2 Task Structure
+
+Each task MUST address these three aspects:
+
+1. **Production Code:** What code changes are needed?
+2. **Tests:** What tests must be written or updated?
+3. **Documentation:** What documentation needs updating? (can be "none" if truly not applicable)
+
+Each task MUST also record its **capability slots** (from Phase 1.5), e.g.
+`language-implementation`, `language-testing`, `language-docs`, `build-deps`. If a needed
+slot is empty, mark it as "generic fallback" so the gap is visible in the plan.
+
+#### 2.3 Dependencies
+
+- Identify which tasks depend on others
+- Tasks without dependencies can be parallelized
+- Common dependency patterns:
+  - Data model changes before API changes
+  - Core logic before integration
+  - Shared utilities before consumers
+
+#### 2.4 Parallelization Strategy
+
+- Group independent tasks for parallel execution via sub-agents
+- Consider resource constraints (e.g., database schema changes should not be parallelized)
+- Prefer smaller, focused sub-agent tasks over large monolithic ones
+
+### Output
+
+Present the user with:
+- The complete task list with descriptions and per-task capability-slot assignments
+- A dependency graph (which tasks block which)
+- The planned execution order
+- Which tasks will be parallelized
+
+Wait for user confirmation before proceeding to Phase 3.
+
+---
+
+## Phase 3 — Implementation (Detail)
+
+### Goal
+
+Execute the implementation plan using sub-agents for efficient parallel work.
+
+### Steps
+
+#### 3.1 Task Execution
+
+For each task (or parallel group of independent tasks):
+
+1. **Update task status** to `in_progress`
+2. **Choose the right sub-agent type:**
+   - `explore` — For codebase research and analysis
+   - `task` — For running builds, tests, linters (returns brief summary on success, full output on failure)
+   - `general-purpose` — For complex multi-step code changes
+3. **Provide complete context** to the sub-agent:
+   - What to implement
+   - Which files to modify
+   - What tests to write
+   - What conventions to follow
+   - The capability-slot skill(s) assigned to this task — pass them explicitly, since
+     sub-agents are stateless and cannot discover your slot map on their own
+4. **Review sub-agent output** before moving to next task
+5. **Update task status** to `done`
+
+#### 3.2 Code Quality
+
+- **Use the `language-implementation` slot skill** if filled; only write code from generic
+  knowledge when the slot is empty
+- Follow existing code style and conventions
+- Do not introduce new dependencies unless explicitly required
+- Keep changes minimal and focused on the requirement
+- Use existing patterns found in the codebase
+
+#### 3.3 Testing
+
+- **Use the `language-testing` slot skill** if filled (it knows the stack's test framework
+  and conventions); only fall back to generic testing when the slot is empty
+- Write tests that cover the new/changed behavior
+- Ensure existing tests still pass
+- Cover edge cases identified in Phase 1
+
+#### 3.4 Documentation
+
+- **Use the `language-docs` slot skill** if filled (e.g. the stack's doc-comment conventions);
+  only fall back to generic documentation when the slot is empty
+- Update inline code documentation where needed
+- Update README or other docs if the change affects usage
+- Keep documentation changes in sync with code changes
+
+#### 3.5 Verification
+
+After all tasks are complete:
+- Run the full test suite using a `task` sub-agent (use the `build-deps` slot skill for the
+  correct build/test commands if filled)
+- Run any existing linters or type checkers
+- Fix any failures before proceeding
+
+### Important Constraints
+
+- **NEVER commit code.** The user will commit when ready.
+- **NEVER skip tests.** Every code change must have corresponding tests.
+- **Respect existing patterns.** Do not refactor unrelated code.
+
+---
+
+## Phase 4 — Review (Detail)
+
+### Goal
+
+Ensure implementation quality through an automated code review before the user commits.
+
+### Steps
+
+#### 4.1 Launch Code Review
+
+Launch a code-review sub-agent with these instructions:
+- If the `language-review` slot is filled, use that skill (stack-specific pitfalls); if a
+  generic review skill also exists, combine both. Use generic-only when no slot is filled.
+- Review ALL changes made during this implementation session
+- Compare changes against the original requirement and acceptance criteria
+- Focus on substantive issues only (not style or formatting)
+
+#### 4.2 Review Criteria
+
+The review sub-agent checks for:
+
+1. **Correctness:** Does the implementation satisfy the requirement and all acceptance criteria?
+2. **Completeness:** Are there missing edge cases, error handling, or untested paths?
+3. **Test Coverage:** Do tests adequately cover the new/changed code?
+4. **Documentation:** Is documentation accurate and up to date?
+5. **Code Quality:** Are there bugs, security issues, or logic errors?
+6. **Consistency:** Does the code follow project conventions and patterns?
+
+#### 4.3 Evaluate Findings
+
+After the review:
+
+- **No issues found:** Proceed to Phase 5
+- **Minor issues found:** Fix them directly, then proceed to Phase 5
+- **Significant issues found:**
+  1. Create new tasks for each finding
+  2. Return to Phase 3 to address them
+  3. After fixing, run Phase 4 again (rework loop)
+
+#### 4.4 Rework Loop
+
+The rework loop (Phase 3 → Phase 4) continues until:
+- The review finds no significant issues
+- OR the user explicitly approves the current state
+
+There is no hard limit on rework iterations, but if the same issues recur after 2 rework cycles, consult the user for guidance.
+
+---
+
+## Phase 5 — Summary (Detail)
+
+### Goal
+
+Provide a clear, comprehensive summary so the user knows exactly what was done and can review before committing.
+
+### Steps
+
+#### 5.1 Change Summary
+
+Create a structured summary containing:
+
+1. **Requirement:** Brief restatement of the original requirement
+2. **Files Modified:** List all files that were created or changed
+3. **Implementation Details:** What was implemented and key design decisions
+4. **Tests Added/Updated:** List all test files and what they cover
+5. **Documentation Changes:** List all documentation updates
+6. **Decisions Made:** Any design decisions or trade-offs during implementation
+7. **Review Notes:** Key points from the review phase
+8. **Things to Check:** Anything the user should manually verify before committing
+
+#### 5.2 Final Reminder
+
+End with a clear reminder:
+
+> All changes are ready for your review. When you are satisfied, please commit
+> the changes yourself. The AI will not create any commits.
+
+---
+
+## General Guidelines
+
+### Sub-Agent Best Practices
+
+- Always provide **complete context** to sub-agents (they are stateless)
+- Use `explore` agents for research, `task` agents for builds/tests, `general-purpose` for complex changes
+- Launch independent tasks in **parallel** for efficiency
+- Review sub-agent output before acting on it
+
+### Git and Commit Rules
+
+- **NEVER** run `git commit`, `git add`, or any commit-related commands
+- **NEVER** create branches, tags, or push to remotes
+- If the user or a tool requests a commit, **skip it** and inform the user:
+  *"Committing is your responsibility. I've skipped this commit request."*
+- You MAY use `git diff`, `git status`, `git log`, and other read-only git commands for analysis
+
+### Handling Project-Specific Conventions
+
+- Always check for instruction files at the start (CLAUDE.md, AGENTS.md, etc.)
+- Run skill discovery (Phase 1.5) and use the resulting capability slots — never hardcode
+  skill names, so the workflow keeps working as skills are added or renamed
+- Follow the project's existing patterns for code style, testing, and documentation
+- When in doubt, ask the user about project conventions
+
+### Capability Slots — Quick Reference
+
+| Slot | Purpose | Phase |
+|------|---------|-------|
+| `language-implementation` | writing code for the detected stack | 3.2 |
+| `language-testing` | the stack's test framework / conventions | 3.3 |
+| `language-docs` | the stack's documentation conventions | 3.4 |
+| `language-review` | stack-specific code review | 4 |
+| `build-deps` | build, package & dependency management | 3.5 |
+
+**Rule:** A filled slot MUST be used (and passed to sub-agents); an empty slot means generic
+fallback. Classify skills into slots by their `description`, never by name.
diff --git a/.claude/skills/refactoring/SKILL.md b/.claude/skills/refactoring/SKILL.md
index 83e126c..57cc674 100644
--- a/.claude/skills/refactoring/SKILL.md
+++ b/.claude/skills/refactoring/SKILL.md
@@ -4,8 +4,8 @@ description: Refactors existing code to improve structure, readability, and main
 ---
 
 # Refactoring Skill
-
-Unless explicitly asked to refactor code directly, generate a refactoring plan first and only apply it if the user approves.
+- Use language-specific skills when ever possible.
+- Unless explicitly asked to refactor code directly, generate a refactoring plan first and only apply it if the user approves.
 
 ## Workflow
 
diff --git a/.claude/skills/writing-skills/SKILL.md b/.claude/skills/writing-skills/SKILL.md
index c3b73d8..b3c2de6 100644
--- a/.claude/skills/writing-skills/SKILL.md
+++ b/.claude/skills/writing-skills/SKILL.md
@@ -93,7 +93,7 @@ skills/
 ## SKILL.md Structure
 
 **Frontmatter (YAML):**
-- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
+- Two required fields: `name` and `description` (see [agentskills.io/specification](./references/agentskills-specification.md) for all supported fields)
 - Max 1024 characters total
 - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
 - `description`: Third-person, describes ONLY when to use (NOT what it does)
@@ -604,7 +604,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 **GREEN Phase - Write Minimal Skill:**
 - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
-- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
+- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](./references/agentskills-specification.md))
 - [ ] Description starts with "Use when..." and includes specific triggers/symptoms
 - [ ] Description written in third person
 - [ ] Keywords throughout for search (errors, symptoms, tools)
diff --git a/.claude/skills/writing-skills/anthropic-best-practices.md b/.claude/skills/writing-skills/anthropic-best-practices.md
index 9f3f6ec..2ff406d 100644
--- a/.claude/skills/writing-skills/anthropic-best-practices.md
+++ b/.claude/skills/writing-skills/anthropic-best-practices.md
@@ -10,7 +10,7 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs
 
 ### Concise is key
 
-The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
+The [context window](./references/context-windows.md) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
 
 * The system prompt
 * Conversation history
@@ -246,11 +246,11 @@ SKILL.md serves as an overview that points Claude to detailed materials as neede
 
 A basic Skill starts with just a SKILL.md file containing metadata and instructions:
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
+![Simple SKILL.md file showing YAML frontmatter and markdown body](./assets/agent-skills-simple-file.png)
 
 As your Skill grows, you can bundle additional content that Claude loads only when needed:
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
+![Bundling additional reference files like reference.md and forms.md.](./assets/agent-skills-bundling-content.png)
 
 The complete Skill directory structure might look like this:
 
@@ -916,7 +916,7 @@ Even if Claude could write a script, pre-made scripts offer advantages:
 * Save time (no code generation required)
 * Ensure consistency across uses
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
+![Bundling executable scripts alongside instruction files](./assets/agent-skills-executable-scripts.png)
 
 The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
 
diff --git a/.claude/skills/writing-skills/assets/agent-skills-bundling-content.png b/.claude/skills/writing-skills/assets/agent-skills-bundling-content.png
new file mode 100644
index 0000000..08cfa9e
Binary files /dev/null and b/.claude/skills/writing-skills/assets/agent-skills-bundling-content.png differ
diff --git a/.claude/skills/writing-skills/assets/agent-skills-executable-scripts.png b/.claude/skills/writing-skills/assets/agent-skills-executable-scripts.png
new file mode 100644
index 0000000..044f3e1
Binary files /dev/null and b/.claude/skills/writing-skills/assets/agent-skills-executable-scripts.png differ
diff --git a/.claude/skills/writing-skills/assets/agent-skills-simple-file.png b/.claude/skills/writing-skills/assets/agent-skills-simple-file.png
new file mode 100644
index 0000000..8c72e51
Binary files /dev/null and b/.claude/skills/writing-skills/assets/agent-skills-simple-file.png differ
diff --git a/.claude/skills/writing-skills/references/agentskills-specification.md b/.claude/skills/writing-skills/references/agentskills-specification.md
new file mode 100644
index 0000000..4ee41da
--- /dev/null
+++ b/.claude/skills/writing-skills/references/agentskills-specification.md
@@ -0,0 +1,193 @@
+# Agent Skills Specification
+
+> The complete format specification for Agent Skills.
+
+## Directory Structure
+
+A skill is a directory containing, at minimum, a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+## `SKILL.md` Format
+
+The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
+
+### Frontmatter
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
+| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
+| `license` | No | License name or reference to a bundled license file. |
+| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
+| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
+| `allowed-tools` | No | Space-separated string of pre-approved tools the skill may use. (Experimental) |
+
+**Minimal example:**
+
+```markdown
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+**Example with optional fields:**
+
+```markdown
+---
+name: pdf-processing
+description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: "1.0"
+---
+```
+
+### `name` Field
+
+- Must be 1-64 characters
+- May only contain unicode lowercase alphanumeric characters (`a-z`) and hyphens (`-`)
+- Must not start or end with a hyphen (`-`)
+- Must not contain consecutive hyphens (`--`)
+- Must match the parent directory name
+
+**Valid:** `pdf-processing`, `data-analysis`, `code-review`
+**Invalid:** `PDF-Processing` (uppercase), `-pdf` (starts with hyphen), `pdf--processing` (consecutive hyphens)
+
+### `description` Field
+
+- Must be 1-1024 characters
+- Should describe both what the skill does and when to use it
+- Should include specific keywords that help agents identify relevant tasks
+
+**Good:** `Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.`
+
+**Poor:** `Helps with PDFs.`
+
+### `license` Field
+
+- Specifies the license applied to the skill
+- Keep short: either the name of a license or the name of a bundled license file
+
+```yaml
+license: Proprietary. LICENSE.txt has complete terms
+```
+
+### `compatibility` Field
+
+- Must be 1-500 characters if provided
+- Only include if your skill has specific environment requirements
+
+```yaml
+compatibility: Designed for Claude Code (or similar products)
+compatibility: Requires git, docker, jq, and access to the internet
+compatibility: Requires Python 3.14+ and uv
+```
+
+> Most skills do not need the `compatibility` field.
+
+### `metadata` Field
+
+- A map from string keys to string values
+- Used for additional properties not defined by the spec
+
+```yaml
+metadata:
+  author: example-org
+  version: "1.0"
+```
+
+### `allowed-tools` Field
+
+- A space-separated string of tools that are pre-approved to run
+- Experimental. Support may vary between agent implementations
+
+```yaml
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+```
+
+### Body Content
+
+The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
+
+Recommended sections:
+
+- Step-by-step instructions
+- Examples of inputs and outputs
+- Common edge cases
+
+Consider splitting longer `SKILL.md` content into referenced files.
+
+## Optional Directories
+
+### `scripts/`
+
+Contains executable code that agents can run. Scripts should:
+
+- Be self-contained or clearly document dependencies
+- Include helpful error messages
+- Handle edge cases gracefully
+
+### `references/`
+
+Contains additional documentation that agents can read when needed:
+
+- `REFERENCE.md` - Detailed technical reference
+- `FORMS.md` - Form templates or structured data formats
+- Domain-specific files (`finance.md`, `legal.md`, etc.)
+
+Keep individual reference files focused. Agents load these on demand.
+
+### `assets/`
+
+Contains static resources:
+
+- Templates (document templates, configuration templates)
+- Images (diagrams, examples)
+- Data files (lookup tables, schemas)
+
+## Progressive Disclosure
+
+Skills should be structured for efficient use of context:
+
+1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills
+2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
+3. **Resources** (as needed): Files in `scripts/`, `references/`, or `assets/` are loaded only when required
+
+Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
+
+## File References
+
+When referencing other files in your skill, use relative paths from the skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Validation
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
+
+```bash
+skills-ref validate ./my-skill
+```
+
+This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
+
+---
+
+Source: https://agentskills.io/specification
diff --git a/.claude/skills/writing-skills/references/context-windows.md b/.claude/skills/writing-skills/references/context-windows.md
new file mode 100644
index 0000000..47d21a9
--- /dev/null
+++ b/.claude/skills/writing-skills/references/context-windows.md
@@ -0,0 +1,66 @@
+# Context Windows
+
+As conversations grow, you'll eventually approach context window limits. This guide explains how context windows work and introduces strategies for managing them effectively.
+
+## Understanding the Context Window
+
+The "context window" refers to all the text a language model can reference when generating a response, including the response itself. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to handle more complex and lengthy prompts, but more context isn't automatically better. As token count grows, accuracy and recall degrade, a phenomenon known as *context rot*. This makes curating what's in context just as important as how much space is available.
+
+> **Tip:** For a deep dive into why long contexts degrade and how to engineer around it, see "Effective context engineering" from Anthropic.
+
+## Key Concepts
+
+- **Progressive token accumulation:** As the conversation advances through turns, each user message and assistant response accumulates within the context window. Previous turns are preserved completely.
+- **Linear growth pattern:** The context usage grows linearly with each turn.
+- **Context window capacity:** The total available context window (up to 1M tokens) represents the maximum capacity for storing conversation history and generating new output.
+- **Input-output flow:** Each turn consists of an input phase (all previous conversation history plus the current user message) and an output phase (generates a response that becomes part of future input).
+
+## The Context Window with Extended Thinking
+
+When using extended thinking, all input and output tokens, including thinking tokens, count toward the context window limit with some nuances:
+
+- Thinking budget tokens are a subset of `max_tokens`, billed as output tokens
+- Previous thinking blocks are automatically stripped from the context window calculation by the API
+- Effective calculation: `context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens`
+
+## The Context Window with Tool Use
+
+When combining extended thinking with tool use:
+
+1. **First turn:** Tools configuration + user message as input; extended thinking + text + tool use request as output
+2. **Tool result handling:** Extended thinking block **must** be returned with corresponding tool results
+3. **Subsequent turns:** Previous thinking blocks are stripped; new thinking generated for each user turn
+
+> **Important:** When posting tool results, the entire unmodified thinking block (including signature portions) must be included. Modified thinking blocks cause API errors.
+
+## Model Context Window Sizes
+
+- Claude Opus 4.6, Sonnet 4.6: 1M-token context window
+- Claude Sonnet 4.5, Sonnet 4: 200k-token context window
+
+A single request can include up to 600 images or PDF pages (100 for 200k-token models).
+
+## Context Awareness
+
+Claude Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 feature **context awareness** — they track their remaining token budget throughout a conversation. At conversation start, Claude receives its total budget, and after each tool call, it receives an update on remaining capacity.
+
+Benefits:
+- Long-running agent sessions with sustained focus
+- Multi-context-window workflows where state transitions matter
+- Complex tasks requiring careful token management
+
+## Managing Context with Compaction
+
+For conversations approaching context limits, **server-side compaction** provides automatic summarization that condenses earlier parts of a conversation, enabling long-running conversations beyond context limits.
+
+Additional strategies via **context editing**:
+- **Tool result clearing** — Clear old tool results in agentic workflows
+- **Thinking block clearing** — Manage thinking blocks with extended thinking
+
+## Newer Model Behavior
+
+Newer Claude models (starting with Claude Sonnet 3.7) return a validation error when prompt and output tokens exceed the context window, rather than silently truncating. Use the token counting API to estimate usage before sending messages.
+
+---
+
+Source: https://platform.claude.com/docs/en/build-with-claude/context-windows
diff --git a/.github/agents/dotnet-developer.md b/.github/agents/dotnet-developer.md
index 08f9656..fe21dee 100644
--- a/.github/agents/dotnet-developer.md
+++ b/.github/agents/dotnet-developer.md
@@ -17,11 +17,11 @@ Use the following skills based on the task at hand:
 
 | Area | Skill | Description |
 |------|-------|-------------|
-| Web & REST APIs | [dotnet-aspnet](../../skills/csharp/dotnet-aspnet/SKILL.md) | ASP.NET Core controllers, minimal APIs, middleware, auth, and API conventions |
-| SDK & Library Development | [dotnet-sdk-builder](../../skills/csharp/dotnet-sdk-builder/SKILL.md) | Generate .NET SDK libraries with DI support, typed HTTP clients, and Options pattern |
-| Testing | [dotnet-tester](../../skills/csharp/dotnet-tester/SKILL.md) | Write and execute unit tests using xUnit, FakeItEasy, and AwesomeAssertions |
-| Data Access | [ef-core](../../skills/csharp/ef-core/SKILL.md) | Entity Framework Core best practices, DbContext design, migrations, and queries |
-| Package Management | [nuget-manager](../../skills/csharp/nuget-manager/SKILL.md) | Add, remove, and update NuGet packages via dotnet CLI |
-| Documentation | [csharp-docs](../../skills/csharp/csharp-docs/SKILL.md) | C# XML documentation comments following Microsoft standards |
-| Code Review | [code-review](../../skills/general/code-review/SKILL.md) | Structured code reviews covering quality, security, and performance |
-| Refactoring | [refactoring](../../skills/general/refactoring/SKILL.md) | Improve code structure and maintainability without changing behavior |
+| Web & REST APIs | `dotnet-aspnet` | ASP.NET Core controllers, minimal APIs, middleware, auth, and API conventions |
+| SDK & Library Development | `dotnet-sdk-builder` | Generate .NET SDK libraries with DI support, typed HTTP clients, and Options pattern |
+| Testing | `dotnet-tester` | Write and execute unit tests using xUnit, FakeItEasy, and AwesomeAssertions |
+| Data Access | `dotnet-ef-core` | Entity Framework Core best practices, DbContext design, migrations, and queries |
+| Package Management | `dotnet-nuget-manager` | Add, remove, and update NuGet packages via dotnet CLI |
+| Documentation | `dotnet-xmldocs` | C# XML documentation comments following Microsoft standards |
+| Code Review | `code-review` | Structured code reviews covering quality, security, and performance |
+| Refactoring | `refactoring` | Improve code structure and maintainability without changing behavior |
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 8638987..42aa639 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,34 +1,49 @@
-This is a general set of instructions that will be used were applicable.
-
 # General Instructions
 
+- Treat comments, docstrings, and TODOs as historical hints, not authoritative behavior. They survive refactors and go stale. Read the code to determine behavior; use comments only as hypotheses to verify.
+- **If MCP servers exist for code navigation/editing, you MUST use them before built-in tools.**
 - Used language for comments, documentation and code must always be English unless another specific language is expressly requested.
-- Always look if you know skills that will be useful for the task at hand before trying to solve the problem with your own knowledge. If you know skills that can be useful, ask if you should use them.
-- Always ask for help if you are stuck.
-- If a skill was explicitly requested in the prompt, use it without asking. If you can't find the skill, always ask if you should proceed without it.
-
-## Code Quality
-- Write clean, maintainable, and well-documented code
-- Follow SOLID principles
-- Use meaningful variable and function names
-- Keep functions small and focused on a single responsibility
-
-## Testing
-- Write unit tests for all new functionality
-- Aim for high test coverage
-- Use meaningful test names that describe the test scenario
-
-## Documentation
-- Document public APIs and complex logic
-- Keep documentation up-to-date with code changes
-- Use clear and concise language
-
-## Error Handling
-- Always handle errors gracefully
-- Provide meaningful error messages
-- Log errors appropriately for debugging
-
-## Security
-- Never commit secrets or sensitive data
-- Validate all user inputs
-- Follow security best practices for the specific technology stack
+- Before solving from your own knowledge, always check for applicable skills.
+- Use subagents as much as possible to avoid context pollution.
+- ALWAYS verify that your changes are complete and work correctly. Use verification steps best suited for your changes.
+
+# Git Commit Instructions
+- You MUST not git commit files unless explicitly asked to do so by the user.
+- Stage files by name (never git add -A/.). Refuse to stage secret-like files (.env, credentials.json, *.pem); warn if the user insists.
+
+# Coding Guidelines
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists for what you're about to write, name it in one sentence before coding. If the user confirms the original, proceed.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios. No error handling for scenarios guaranteed impossible by the type system or a same-file invariant. If justifying the skip requires reasoning about callers, keep the check.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it in your final response — don't delete it.
+
+When your changes create orphans: Remove imports/variables/functions your changes orphaned; leave pre-existing dead code (mention it in the response).
+
+## Priority when rules conflict
+1. Ask beats guessing or silent assumption.
+2. Surgical beats Simplify for existing code. § 2 applies only to code you write new in this task; don't rewrite existing code to make it simpler unless asked.
+3. Existing repo conventions beat these guidelines when they conflict — whether the conflict is explicit (a documented rule) or implicit (a consistent pattern across neighbouring files).
diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md
index 0ad36e1..63e5cc1 100644
--- a/.github/instructions/csharp.instructions.md
+++ b/.github/instructions/csharp.instructions.md
@@ -5,17 +5,10 @@ applyTo: '**/*.cs'
 
 # C# Development
 
-## C# Instructions
-
 - Always use the latest stable C# version available in the project's target framework.
-- Write clear and concise comments for each function.
 
 ## General Instructions
 
-- Make only high confidence suggestions when reviewing code changes.
-- Write code with good maintainability practices, including comments on why certain design decisions were made.
-- Handle edge cases and write clear exception handling.
-- For libraries or external dependencies, mention their usage and purpose in comments.
 - Use `Ensure.NotNull(...)` from `CreativeCoders.Core` for null guards
 - Use `Ensure.IsNotNullOrEmpty(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty
 - Use `Ensure.IsNotNullOrWhitespace(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty or whitespace
@@ -33,14 +26,6 @@ public void DoSomething(string input, string fileName)
 _service = Ensure.NotNull(service);
 ```
 
-## Naming Conventions
-
-- Follow PascalCase for component names, method names and public members.
-- Use camelCase for local variables.
-- Use _camelCase for private fields.
-- Prefix interface names with "I" (e.g., IUserService).
-- Use naming conventions from surrounding code if different from Naming conventions above.
-
 ## Formatting
 
 - Apply code-formatting style defined in `.editorconfig`.
@@ -48,102 +33,65 @@ _service = Ensure.NotNull(service);
 - Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`,
   `using`, `try`, etc.).
 - Ensure that the final return statement of a method is on its own line.
-- Use pattern matching and switch expressions wherever possible.
 - Use `nameof` instead of string literals when referring to member names.
-- Use the `csharp-docs` skill to ensure XML documentation follows best practices.
-- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection
-
-## Project Setup and Structure
-
-- Guide users through creating a new .NET project with the appropriate templates.
-- Explain the purpose of each generated file and folder to build understanding of the project structure.
-- Demonstrate how to organize code using feature folders or domain-driven design principles.
-- Show proper separation of concerns with models, services, and data access layers.
-- Explain the Program.cs and configuration system in ASP.NET Core including environment-specific settings.
+- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection.
+- Use naming conventions from surrounding code when they differ from standard C# conventions.
 
 ## Modern C# Features
 
-- Prefer **switch expressions** over switch statements
-- Use **pattern matching** wherever possible
-- Use **primary constructors** when no constructor body is needed
-- Use private fields with guards instead of using primary constructor parameters directly, unless the parameter is assigned to a property.
+- **Default to a primary constructor**, also with `Ensure.*` guards — put the guard in the field initializer, not a constructor body:
+  ```csharp
+  public sealed class Foo(IBar bar) : IFoo
+  {
+      private readonly IBar _bar = Ensure.NotNull(bar);
+  }
+  ```
+- Reference the fields, never the raw parameters (avoids capturing unguarded params).
+- Use a classic constructor only when init needs real statements (control flow, ordering, multistep setup, logic before base(...)/this(...)). Guards/initializers don't count.
+- A parameter assigned to a property goes via the property initializer, not a backing field.
 
 ## Async/Await
 
 - In **library code** always use `.ConfigureAwait(false)`
-- In **tests** do not use `.ConfigureAwait(false)` (disabled via tests/.editorconfig)
+- In **tests** do not use `.ConfigureAwait(false)` (disable for tests via tests/.editorconfig)
+- YOU MUST NOT USE `.GetAwaiter().GetResult()` OR `.Result` OR `.Wait()` TO BLOCK ON ASYNC CODE. If there is no other way ask the user what to do.
 
 ## Nullable Reference Types
 
 - Declare variables non-nullable, and check for `null` at entry points.
 - Always use `is null` or `is not null` instead of `== null` or `!= null`.
-- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
-- Do not add redundant null checks when the type system already guarantees non-null
-
-## Data Access Patterns
-
-- Guide the implementation of a data access layer using Entity Framework Core.
-- Explain different options (SQL Server, SQLite, In-Memory) for development and production.
-- Demonstrate repository pattern implementation and when it's beneficial.
-- Show how to implement database migrations and data seeding.
-- Explain efficient query patterns to avoid common performance issues.
-
-## Authentication and Authorization
-
-- Guide users through implementing authentication using JWT Bearer tokens.
-- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core.
-- Show how to implement role-based and policy-based authorization.
-- Demonstrate integration with Microsoft Entra ID (formerly Azure AD).
-- Explain how to secure both controller-based and Minimal APIs consistently.
-
-## Validation and Error Handling
-
-- Guide the implementation of model validation using data annotations and FluentValidation.
-- Explain the validation pipeline and how to customize validation responses.
-- Demonstrate a global exception handling strategy using middleware.
-- Show how to create consistent error responses across the API.
-- Explain problem details (RFC 7807) implementation for standardized error responses.
+- Trust the C# null annotations — don't add null checks when the type system guarantees non-null.
 
-## API Versioning and Documentation
+## Documentation
 
-- Guide users through implementing and explaining API versioning strategies.
-- Demonstrate Swagger/OpenAPI implementation with proper documentation.
-- Show how to document endpoints, parameters, responses, and authentication.
-- Explain versioning in both controller-based and Minimal APIs.
-- Guide users on creating meaningful API documentation that helps consumers.
-
-## Logging and Monitoring
-
-- Guide the implementation of structured logging using Serilog or other providers.
-- Explain the logging levels and when to use each.
-- Demonstrate integration with Application Insights for telemetry collection.
-- Show how to implement custom telemetry and correlation IDs for request tracking.
-- Explain how to monitor API performance, errors and usage patterns.
+- Document all public members with XML documentation.
+- Use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
+- If you change code, always update the relevant XML documentation.
 
 ## Testing
 
-- Always include test cases for critical paths of the application.
-- Always use the `dotnet-tester` skill for detailed testing conventions and workflows when writing tests.
-
-## Performance Optimization
-
-- Guide users on implementing caching strategies (in-memory, distributed, response caching).
-- Explain asynchronous programming patterns and why they matter for API performance.
-- Demonstrate pagination, filtering, and sorting for large data sets.
-- Show how to implement compression and other performance optimizations.
-- Explain how to measure and benchmark API performance.
-
-## Deployment and DevOps
-
-- Guide users through containerizing their API using .NET's built-in container support (
-  `dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`).
-- Explain the differences between manual Dockerfile creation and .NET's container publishing features.
-- Explain CI/CD pipelines for NET applications.
-- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options.
-- Show how to implement health checks and readiness probes.
-- Explain environment-specific configurations for different deployment stages.
+- Always include test cases for code changes.
+- Always use the `dotnet-tester` skill for writing tests.
 
 ## Console
+
 - Use AnsiConsole for console input and output. Always use IAnsiConsole via dependency injection.
 - Use colored output where it makes sense. For example, use green for success messages, red for errors and yellow for warnings.
 - Use tables for structured output when displaying lists of data or multiple pieces of related information.
+
+## Logging
+
+- Use Serilog for logging.
+- Configure Serilog with appropriate sinks (e.g., file, console, Azure Application Insights) based on environment.
+- Always use structured logging with properties for better log analysis and correlation.
+
+## Skills Reference
+
+- You MUST use the `dotnet-aspnet` skill for ASP.NET Core projects (project structure, middleware, auth, validation, error handling, API versioning, OpenAPI).
+- You MUST use the `dotnet-ef-core` skill for Entity Framework Core data access patterns.
+- You MUST use the `dotnet-sdk-builder` skill for creating .NET SDK/client libraries.
+- You MUST use the `dotnet-reviewer` skill for Reviewing .NET Code.
+- You MUST use the `dotnet-tester` skill for writing and editing tests.
+- You MUST use the `dotnet-nuget-manager` skill for NuGet package management.
+- You MUST use the `dotnet-inspect` skill to query .NET APIs in NuGet packages, platform libraries (System.*, Microsoft.AspNetCore.*), or local .dll/.nupkg files — discover types and members, diff API surfaces between versions, find extension methods/implementors, locate SourceLink URLs, and triage breakages caused by package upgrades.
+- You MUST use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
diff --git a/.github/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md b/.github/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md
new file mode 100644
index 0000000..5963161
--- /dev/null
+++ b/.github/skills/convert-plaintext-to-md/references/azure-devops-markdown-guidance.md
@@ -0,0 +1,173 @@
+# Azure DevOps Markdown Guidance
+
+This reference describes Markdown syntax supported by Azure DevOps features including Wiki pages, README files, dashboards, and pull requests.
+
+## Supported Features
+
+| Markdown type | Definition of Done | Widget | Pull Requests | README | Wiki |
+|---|---|---|---|---|---|
+| Headings | Yes | Yes | Yes | Yes | Yes |
+| Paragraphs/line breaks | Yes | Yes | Yes | Yes | Yes |
+| Blockquotes | Yes | Yes | Yes | Yes | Yes |
+| Horizontal rules | Yes | Yes | Yes | Yes | Yes |
+| Emphasis (bold, italic) | Yes | Yes | Yes | Yes | Yes |
+| Tables | No | Yes | Yes | Yes | Yes |
+| Lists (ordered, unordered) | Yes | Yes | Yes | Yes | Yes |
+| Links | Yes | Yes | Yes | Yes | Yes |
+| Images | No | Yes | Yes | Yes | Yes |
+| Code highlighting | No | Yes | Yes | Yes | Yes |
+| Math notation | No | No | Yes | Yes | Yes |
+| Checklists/task lists | No | No | Yes | Yes | Yes |
+| Mermaid diagrams | No | No | No | No | Yes |
+
+> **Note:** Markdown in Azure DevOps doesn't support JavaScript or iframes.
+
+## Headings
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
+##### Heading 5
+###### Heading 6
+```
+
+## Paragraphs and Line Breaks
+
+Use a blank line for new paragraphs. Use two spaces at line end or `<br/>` for line breaks within a paragraph.
+
+## Blockquotes
+
+```markdown
+> Single blockquote
+>> Nested blockquote
+```
+
+## Horizontal Rules
+
+Use three or more hyphens, asterisks, or underscores on a line by themselves.
+
+## Emphasis
+
+```markdown
+*Italic* or _Italic_
+**Bold** or __Bold__
+***Bold italic***
+~~Strikethrough~~
+```
+
+## Code Highlighting
+
+**Inline:** Use single backticks `` `code` ``
+
+**Block:** Use triple backticks with optional language identifier:
+
+````markdown
+```javascript
+const x = 1;
+```
+````
+
+Supported languages include: ActionScript, Apex, Bash, C, C#, C++, CSS, Dart, Go, Groovy, Haskell, HTML, Java, JavaScript, JSON, Kotlin, Lua, Markdown, Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Shell, SQL, Swift, TypeScript, XML, YAML, and more.
+
+## Tables
+
+```markdown
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+```
+
+Alignment with colons: `:---` (left), `:---:` (center), `---:` (right).
+
+## Lists
+
+**Ordered:**
+
+```markdown
+1. First item
+2. Second item
+```
+
+**Unordered:**
+
+```markdown
+- Item 1
+- Item 2
+```
+
+**Nested:** Indent with spaces.
+
+## Links
+
+```markdown
+[Link text](URL)
+[Link text](URL "Title")
+```
+
+**Anchor links:** Link to headings within the same page using `#section-name`.
+
+## Images
+
+```markdown
+![Alt text](image-url)
+![Alt text](image-url =WIDTHxHEIGHT)
+```
+
+Azure DevOps supports image resizing with `=WIDTHxHEIGHT` syntax.
+
+## Checklists / Task Lists
+
+```markdown
+- [ ] Incomplete task
+- [x] Completed task
+```
+
+## Mathematical Notation
+
+**Inline:** `$` delimiters: `$e^{i\pi} = -1$`
+
+**Block:** `$$` delimiters:
+
+```markdown
+$$
+\sum_{i=1}^{n} x_i
+$$
+```
+
+Uses KaTeX for rendering.
+
+## Mermaid Diagrams (Wiki only)
+
+````markdown
+```mermaid
+graph TD;
+    A-->B;
+    B-->C;
+```
+````
+
+Supports: flowcharts, sequence diagrams, Gantt charts, and more.
+
+## Collapsible Sections
+
+```html
+<details>
+  <summary>Click to expand</summary>
+
+  Content here (leave blank line after summary tag).
+</details>
+```
+
+## Emoji
+
+Use standard emoji shortcodes: `:smile:`, `:thumbsup:`, etc.
+
+## Special Characters
+
+Escape special Markdown characters with backslash: `\*`, `\#`, `\[`, etc.
+
+## HTML Tags
+
+Supported HTML tags in Wiki include: `<div>`, `<span>`, `<img>`, `<br>`, `<table>`, `<tr>`, `<td>`, `<th>`, `<strong>`, `<em>`, `<code>`, `<pre>`, `<blockquote>`, `<ul>`, `<ol>`, `<li>`, `<h1>`-`<h6>`, `<hr>`, `<p>`, `<a>`, `<details>`, `<summary>`, `<video>`, `<audio>`.
diff --git a/.github/skills/convert-plaintext-to-md/references/considerations.md b/.github/skills/convert-plaintext-to-md/references/considerations.md
index c8f77e1..5e053ed 100644
--- a/.github/skills/convert-plaintext-to-md/references/considerations.md
+++ b/.github/skills/convert-plaintext-to-md/references/considerations.md
@@ -35,6 +35,6 @@ When converting documentation, do **not** halt the conversion when the text docu
 
 When in doubt, consult these resources for markdown best practices:
 
-- [GitHub Basic Writing and Formatting Syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
-- [Markdown Extended Syntax](https://www.markdownguide.org/extended-syntax/)
-- [Azure DevOps Markdown Guidance](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops)
+- [GitHub Basic Writing and Formatting Syntax](./github-basic-formatting.md)
+- [Markdown Extended Syntax](./markdown-extended-syntax.md)
+- [Azure DevOps Markdown Guidance](./azure-devops-markdown-guidance.md)
diff --git a/.github/skills/convert-plaintext-to-md/references/github-basic-formatting.md b/.github/skills/convert-plaintext-to-md/references/github-basic-formatting.md
new file mode 100644
index 0000000..efaa03b
--- /dev/null
+++ b/.github/skills/convert-plaintext-to-md/references/github-basic-formatting.md
@@ -0,0 +1,153 @@
+# GitHub Basic Writing and Formatting Syntax Reference
+
+## Headings
+
+Create hierarchy using 1-6 hash symbols. GitHub automatically generates a table of contents when you use multiple headings.
+
+```markdown
+# First-level heading
+## Second-level heading
+### Third-level heading
+```
+
+## Text Styling
+
+| Style | Syntax | Example |
+|-------|--------|---------|
+| Bold | `** **` or `__ __` | `**bold text**` |
+| Italic | `* *` or `_ _` | `*italicized text*` |
+| Strikethrough | `~~ ~~` | `~~mistaken text~~` |
+| Bold & italic | `** **` and `_ _` | `**_extremely_ important**` |
+| Subscript | `<sub> </sub>` | `<sub>subscript</sub>` |
+| Superscript | `<sup> </sup>` | `<sup>superscript</sup>` |
+| Underline | `<ins> </ins>` | `<ins>underlined</ins>` |
+
+## Quoting Text
+
+Use `>` to create block quotes:
+
+```markdown
+> Text that is a quote
+```
+
+## Code Formatting
+
+**Inline code:** Use single backticks for code within sentences:
+
+```markdown
+Use `git status` to list changes.
+```
+
+**Code blocks:** Use triple backticks for standalone code:
+
+````markdown
+```
+git status
+git add
+git commit
+```
+````
+
+## Color Support
+
+Display colors using supported models within backticks:
+
+- Hex: `` `#0969DA` ``
+- RGB: `` `rgb(9, 105, 218)` ``
+- HSL: `` `hsl(212, 92%, 45%)` ``
+
+## Links
+
+Wrap link text in brackets and URL in parentheses:
+
+```markdown
+[Link text](https://example.com)
+```
+
+**Section links:** Link directly to any heading using its anchor.
+
+**Relative links:** Use paths relative to current file:
+
+```markdown
+[Contribution guidelines](docs/CONTRIBUTING.md)
+```
+
+## Images
+
+Include images using exclamation mark, alt text in brackets, and URL in parentheses:
+
+```markdown
+![Alt text](image-url.png)
+```
+
+The `<picture>` HTML element is supported for theme-adaptive images.
+
+## Lists
+
+**Unordered lists:** Use `-`, `*`, or `+`
+
+**Ordered lists:** Use numbers followed by periods
+
+**Nested lists:** Indent items under parent items using spaces or tabs
+
+## Task Lists
+
+Create checkboxes with `[ ]` for incomplete and `[x]` for complete tasks:
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+```
+
+## Mentions & References
+
+- **Mention people/teams:** `@username` or `@organization/team-name`
+- **Reference issues:** `#` followed by issue number or title
+
+## Emojis
+
+Use `:EMOJICODE:` format: `:+1:`, `:shipit:`
+
+## Paragraphs & Line Breaks
+
+Create paragraphs by leaving blank lines between text. For line breaks:
+
+- Two trailing spaces at line end
+- Backslash `\` at line end
+- HTML `<br/>`
+
+## Footnotes
+
+```markdown
+Here is a footnote[^1].
+
+[^1]: Footnote content here.
+```
+
+Footnotes render at document bottom regardless of placement.
+
+## Alerts
+
+Five alert types emphasize critical information:
+
+```markdown
+> [!NOTE]
+> Essential information users should know.
+
+> [!TIP]
+> Helpful advice for better outcomes.
+
+> [!IMPORTANT]
+> Key information for success.
+
+> [!WARNING]
+> Urgent information requiring immediate attention.
+
+> [!CAUTION]
+> Warns about risks and negative outcomes.
+```
+
+## Special Features
+
+- **HTML comments:** `<!-- Hidden content -->`
+- **Escape formatting:** Backslash before markdown characters: `\*not italicized\*`
diff --git a/.github/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md b/.github/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md
new file mode 100644
index 0000000..bbc1ab0
--- /dev/null
+++ b/.github/skills/convert-plaintext-to-md/references/markdown-extended-syntax.md
@@ -0,0 +1,133 @@
+# Markdown Extended Syntax Reference
+
+The extended syntax builds upon basic Markdown by adding advanced features. Not all Markdown applications support extended syntax — check your application's documentation to confirm compatibility.
+
+## Tables
+
+Create tables using pipes (`|`) and hyphens (`---`):
+
+```markdown
+| Syntax      | Description |
+| ----------- | ----------- |
+| Header      | Title       |
+| Paragraph   | Text        |
+```
+
+### Alignment
+
+Add colons to align columns:
+
+- Left: `:---`
+- Center: `:---:`
+- Right: `---:`
+
+### Formatting in Tables
+
+Supported: links, code (backticks only), emphasis.
+Not supported: headings, blockquotes, lists, horizontal rules, images.
+
+### Escaping Pipes
+
+Use HTML entity `&#124;` to display pipe characters.
+
+## Fenced Code Blocks
+
+Use triple backticks or tildes without indentation:
+
+````markdown
+```json
+{
+  "example": "value"
+}
+```
+````
+
+Specify language after opening backticks for syntax highlighting.
+
+## Footnotes
+
+```markdown
+Text here.[^1]
+
+[^1]: This is the footnote.
+```
+
+## Heading IDs
+
+Add custom IDs to headings:
+
+```markdown
+### Heading {#custom-id}
+```
+
+Link to IDs with `[Link text](#custom-id)`.
+
+## Definition Lists
+
+```markdown
+Term
+: Definition of the term.
+```
+
+## Strikethrough
+
+Use double tildes:
+
+```markdown
+~~Strikethrough text~~
+```
+
+## Task Lists
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+```
+
+## Emoji
+
+### Direct Copy-Paste
+
+Paste emoji directly from sources like Emojipedia.
+
+### Shortcodes
+
+```markdown
+Gone camping! :tent: Be back soon.
+```
+
+## Highlight
+
+```markdown
+==Important words==
+```
+
+Or use HTML: `<mark>text</mark>`
+
+## Subscript
+
+```markdown
+H~2~O
+```
+
+Or HTML: `H<sub>2</sub>O`
+
+## Superscript
+
+```markdown
+X^2^
+```
+
+Or HTML: `X<sup>2</sup>`
+
+## Automatic URL Linking
+
+Most processors auto-link URLs. Disable by wrapping in backticks:
+
+```markdown
+`http://www.example.com`
+```
+
+---
+
+> **Note:** Support varies significantly across applications. Always test extended syntax features in your specific Markdown processor.
diff --git a/.github/skills/create-readme/SKILL.md b/.github/skills/create-readme/SKILL.md
index 81cc12b..acff6c8 100644
--- a/.github/skills/create-readme/SKILL.md
+++ b/.github/skills/create-readme/SKILL.md
@@ -7,11 +7,11 @@ description: Creates a comprehensive, professional README.md for a project. Use
 
 1. Review the entire project and workspace, then create a well-structured README.md.
 2. Take inspiration from these readme files for structure, tone, and content:
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-chat-langchainjs/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/Azure-Samples/serverless-recipes-javascript/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/run-on-output/refs/heads/main/README.md
-   - https://raw.githubusercontent.com/sinedied/smoke/refs/heads/main/README.md
+   - [serverless-chat-langchainjs](./references/serverless-chat-langchainjs-readme.md)
+   - [serverless-recipes-javascript](./references/serverless-recipes-javascript-readme.md)
+   - [run-on-output](./references/run-on-output-readme.md)
+   - [smoke](./references/smoke-readme.md)
 3. Do not overuse emojis, and keep the readme concise and to the point.
 4. Do not include sections like "LICENSE", "CONTRIBUTING", "CHANGELOG", etc. There are dedicated files for those sections.
-5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (https://github.com/orgs/community/discussions/16925) where appropriate.
+5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (see [reference](./references/github-admonition-syntax.md)) where appropriate.
 6. If you find a logo or icon for the project, use it in the readme's header.
diff --git a/.github/skills/create-readme/references/github-admonition-syntax.md b/.github/skills/create-readme/references/github-admonition-syntax.md
new file mode 100644
index 0000000..324df13
--- /dev/null
+++ b/.github/skills/create-readme/references/github-admonition-syntax.md
@@ -0,0 +1,60 @@
+# GitHub Markdown Alerts (Admonition Syntax)
+
+GitHub supports a markdown extension for creating highlighted alert blocks using blockquote syntax. This feature helps emphasize critical information in documentation with distinctive colors and icons.
+
+## Syntax
+
+The basic syntax uses blockquote markers (`>`) with a bracket notation:
+
+```markdown
+> [!TYPE]
+> Your alert content here
+```
+
+## Supported Alert Types
+
+### NOTE
+
+```markdown
+> [!NOTE]
+> Highlights information users should consider, even when skimming.
+```
+
+### TIP
+
+```markdown
+> [!TIP]
+> Optional information to help users be more successful.
+```
+
+### IMPORTANT
+
+```markdown
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+```
+
+### WARNING
+
+```markdown
+> [!WARNING]
+> Critical content demanding immediate attention due to potential risks.
+```
+
+### CAUTION
+
+```markdown
+> [!CAUTION]
+> Negative potential consequences of an action.
+```
+
+## Key Features
+
+- A line break must follow the alert type marker
+- Alerts render as `div` elements with semantic styling rather than blockquote elements
+- Works in READMEs, Markdown files, wikis, issues, pull requests, and discussions
+- Each alert type uses distinct visual styling (colors and icons) for clarity
+
+## Source
+
+Originally discussed at: https://github.com/orgs/community/discussions/16925
diff --git a/.github/skills/create-readme/references/run-on-output-readme.md b/.github/skills/create-readme/references/run-on-output-readme.md
new file mode 100644
index 0000000..971734d
--- /dev/null
+++ b/.github/skills/create-readme/references/run-on-output-readme.md
@@ -0,0 +1,146 @@
+<div align="center">
+  <img src="icon.png" width="96" alt="run-on-output logo">
+  
+  # run-on-output
+  *Execute tasks when CLI output patterns are detected*
+  
+  [![Build Status](https://img.shields.io/github/actions/workflow/status/sinedied/run-on-output/ci.yml?style=flat-square)](https://github.com/sinedied/run-on-output/actions)
+  [![npm version](https://img.shields.io/npm/v/run-on-output?style=flat-square)](https://www.npmjs.com/package/run-on-output)
+  [![Node.js](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)](https://nodejs.org)
+  [![XO code style](https://shields.io/badge/code_style-5ed9c7?logo=xo&labelColor=gray&style=flat-square)](https://github.com/xojs/xo)
+  [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+  ⭐ If you like this project, star it on GitHub!
+
+  [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Examples](#examples)
+
+</div>
+
+
+A lightweight Node.js CLI tool that monitors command output in real-time and triggers actions when specific patterns are found. Perfect for automation workflows, development environments, and CI/CD pipelines.
+
+## Features
+
+- 🎯 **Pattern Matching** - Monitor stdout/stderr for regex patterns or plain strings
+- ⚡ **Real-time Monitoring** - Output is forwarded in real-time while monitoring  
+- 🔧 **Flexible Actions** - Display messages or execute commands when patterns match
+- 📝 **Multiple Patterns** - Wait for multiple patterns before triggering actions
+- 🚀 **Zero Dependencies** - Built with Node.js built-in modules only
+
+## Installation
+
+```bash
+npm install -g run-on-output
+```
+
+Or use without installing:
+
+```bash
+npx run-on-output [options] <command> [args...]
+```
+
+## Usage
+
+### Basic Examples
+
+**Display a message when server starts:**
+```bash
+run-on-output -s "Server started" -m "🚀 Server is ready" npm start
+```
+
+**Execute a health check when server is listening:**
+```bash
+run-on-output -p "listening on port \\d+" -r "curl http://localhost:3000/health" node server.js
+```
+
+**Monitor development environment startup:**
+```bash
+run-on-output -s "webpack compiled,server ready" -m "✅ Development environment ready" npm run dev
+```
+
+**Multiple actions - show message and open browser:**
+```bash
+run-on-output -s "ready" -m "Server is up" -r "open http://localhost:3000" npm start
+```
+
+**Run npm script when server is ready:**
+```bash
+run-on-output -s "Server running" -n "test" node server.js
+```
+
+> [!TIP]
+> You can use the short alias `roo` instead of `run-on-output` for faster typing:
+> ```bash
+> roo -s "Server started" -m "🚀 Server is ready" npm start
+> ```
+
+### Command Line Options
+
+```
+run-on-output [OPTIONS] <command> [args...]
+
+OPTIONS:
+  -p, --patterns <patterns>    Comma-separated list of regex patterns to watch for
+  -s, --strings <strings>      Comma-separated list of plain strings to watch for
+  -r, --run <command>          Command to execute after all patterns are found
+  -n, --npm <script>           npm script to run after all patterns are found
+  -m, --message <text>         Message to display after all patterns are found
+  -h, --help                   Show this help message
+
+REQUIREMENTS:
+  - Either --patterns or --strings must be specified (but not both)
+  - At least one of --run, --npm, or --message must be specified
+```
+
+### Pattern Types
+
+**Plain Strings (`-s, --strings`)**
+- Matches exact text (case-insensitive)
+- Easier to use for simple text matching
+- Example: `-s "Server started,Database connected"`
+
+**Regex Patterns (`-p, --patterns`)**
+- Use regular expressions for complex matching
+- Supports all JavaScript regex features
+- Example: `-p "listening on port \\d+,ready in \\d+ms"`
+
+## Examples
+
+**Development Workflow**
+```bash
+# Wait for both webpack and server, then open browser
+run-on-output -s "webpack compiled,Local:" -r "open http://localhost:3000" npm run dev
+
+# Monitor test runner and show completion message
+run-on-output -s "Tests completed" -m "✅ All tests passed" npm test
+```
+
+**CI/CD Pipeline**
+```bash
+# Wait for deployment completion and run smoke tests
+run-on-output -p "deployment.*complete" -r "./scripts/smoke-test.sh" deploy.sh
+
+# Monitor build process and trigger notifications
+run-on-output -s "Build successful" -r "slack-notify '#dev' 'Build completed'" npm run build
+```
+
+**Docker & Containers**
+```bash
+# Wait for container health check and run integration tests
+run-on-output -s "healthy" -r "npm run test:integration" docker-compose up
+
+# Monitor database initialization
+run-on-output -p "database.*ready" -m "📁 Database initialized" ./start-db.sh
+```
+
+**API Development**
+```bash
+# Wait for API server and run endpoint tests
+run-on-output -p "server.*listening.*port" -r "npm run test:api" node api.js
+
+# Monitor microservices startup and run deployment script
+run-on-output -s "auth-service ready,user-service ready" -n "deploy" ./start-services.sh
+
+# Combine message, command and npm script
+run-on-output -s "Database connected" -m "🎉 Ready for testing" -n "test:integration" npm start
+```
diff --git a/.github/skills/create-readme/references/serverless-chat-langchainjs-readme.md b/.github/skills/create-readme/references/serverless-chat-langchainjs-readme.md
new file mode 100644
index 0000000..b36fbba
--- /dev/null
+++ b/.github/skills/create-readme/references/serverless-chat-langchainjs-readme.md
@@ -0,0 +1,280 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<img src="./packages/webapp/public/favicon.png" alt="" align="center" height="64" />
+
+# Serverless AI Chat with RAG using LangChain.js
+
+[![Open project in GitHub Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/Azure-Samples/serverless-chat-langchainjs?hide_repo_select=true&ref=main&quickstart=true)
+[![Join Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Community-blue?style=flat-square&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+[![Official Learn documentation](https://img.shields.io/badge/Documentation-00a3ee?style=flat-square)](https://learn.microsoft.com/azure/developer/javascript/ai/get-started-app-chat-template-langchainjs)
+[![Watch to learn about RAG and this sample on YouTube](https://img.shields.io/badge/YouTube-d95652.svg?style=flat-square&logo=youtube)](https://www.youtube.com/watch?v=xkFOmx5yxIA&list=PLlrxD0HtieHi5ZpsHULPLxm839IrhmeDk&index=4)
+[![dev.to blog post walkthrough](https://img.shields.io/badge/Blog%20post-black?style=flat-square&logo=dev.to)](https://dev.to/azure/build-a-serverless-chatgpt-with-rag-using-langchainjs-3487)
+<br>
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Azure-Samples/serverless-chat-langchainjs/build-test.yaml?style=flat-square&label=Build)](https://github.com/Azure-Samples/serverless-chat-langchainjs/actions)
+![Node version](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
+[![Ollama + Llama3.1](https://img.shields.io/badge/Ollama-Llama3.1-ff7000?style=flat-square)](https://ollama.com/library/llama3.1)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+:star: If you like this sample, star it on GitHub — it helps a lot!
+
+[Overview](#overview) • [Get started](#getting-started) • [Run the sample](#run-the-sample) • [Resources](#resources) • [FAQ](#faq) • [Troubleshooting](#troubleshooting)
+
+![Animation showing the chat app in action](./docs/images/demo.gif)
+
+</div>
+
+This sample shows how to build a serverless AI chat experience with Retrieval-Augmented Generation using [LangChain.js](https://js.langchain.com/) and Azure. The application is hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview) and [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript), with [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/vector-) as the vector database. You can use it as a starting point for building more complex AI applications.
+
+> [!TIP]
+> You can test this application locally without any cost using [Ollama](https://ollama.com/). Follow the instructions in the [Local Development](#local-development) section to get started.
+
+## Overview
+
+Building AI applications can be complex and time-consuming, but using LangChain.js and Azure serverless technologies allows to greatly simplify the process. This application is a chatbot that uses a set of enterprise documents to generate responses to user queries.
+
+We provide sample data to make this sample ready to try, but feel free to replace it with your own. We use a fictitious company called _Contoso Real Estate_, and the experience allows its customers to ask support questions about the usage of its products. The sample data includes a set of documents that describes its terms of service, privacy policy and a support guide.
+
+<div align="center">
+  <img src="./docs/images/architecture.drawio.png" alt="Application architecture" width="640px" />
+</div>
+
+This application is made from multiple components:
+
+- A web app made with a single chat web component built with [Lit](https://lit.dev) and hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview). The code is located in the `packages/webapp` folder.
+
+- A serverless API built with [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript) and using [LangChain.js](https://js.langchain.com/) to ingest the documents and generate responses to the user chat queries. The code is located in the `packages/api` folder.
+
+- A database to store chat sessions and the text extracted from the documents and the vectors generated by LangChain.js, using [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/).
+
+- A file storage to store the source documents, using [Azure Blob Storage](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction).
+
+We use the [HTTP protocol for AI chat apps](https://aka.ms/chatprotocol) to communicate between the web app and the API.
+
+## Features
+
+- **Serverless Architecture**: Utilizes Azure Functions and Azure Static Web Apps for a fully serverless deployment.
+- **Retrieval-Augmented Generation (RAG)**: Combines the power of Azure Cosmos DB and LangChain.js to provide relevant and accurate responses.
+- **Chat Sessions History**: Maintains a personal chat history for each user, allowing them to revisit previous conversations.
+- **Scalable and Cost-Effective**: Leverages Azure's serverless offerings to provide a scalable and cost-effective solution.
+- **Local Development**: Supports local development using Ollama for testing without any cloud costs.
+
+## Getting started
+
+There are multiple ways to get started with this project.
+
+The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
+
+> [!IMPORTANT]
+> If you want to run this sample entirely locally using Ollama, you have to follow the instructions in the [local environment](#use-your-local-environment) section.
+
+### Use your local environment
+
+You need to install following tools to work on your local machine:
+
+- [Node.js LTS](https://nodejs.org/download/)
+- [Azure Developer CLI](https://aka.ms/azure-dev/install)
+- [Git](https://git-scm.com/downloads)
+- [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_
+  - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
+  - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
+- [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_
+
+Then you can get the project code:
+
+1. [**Fork**](https://github.com/Azure-Samples/serverless-chat-langchainjs/fork) the project to create your own copy of this repository.
+2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
+
+<div align="center">
+  <img src="./docs/images/clone-url.png" alt="Screenshot showing how to copy the repository URL" width="400px" />
+</div>
+3. Open a terminal and run this command to clone the repo: <code> git clone &lt;your-repo-url&gt; </code>
+
+### Use GitHub Codespaces
+
+You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
+
+[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/serverless-chat-langchainjs?hide_repo_select=true&ref&quickstart=true)
+
+### Use a VSCode dev container
+
+A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+You will also need to have [Docker](https://www.docker.com/products/docker-desktop) installed on your machine to run the container.
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/serverless-chat-langchainjs)
+
+## Run the sample
+
+There are multiple ways to run this sample: locally using Ollama or Azure OpenAI models, or by deploying it to Azure.
+
+### Deploy the sample to Azure
+
+#### Azure prerequisites
+
+- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents).
+- **Azure subscription with access enabled for the Azure OpenAI service**. You can request access with [this form](https://aka.ms/oaiapply).
+- **Azure account permissions**:
+  - Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](docs/deploy_existing.md#resource-group).
+  - Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
+
+#### Cost estimation
+
+See the [cost estimation](./docs/cost.md) details for running this sample on Azure.
+
+#### Deploy the sample
+
+1. Open a terminal and navigate to the root of the project.
+2. Authenticate with Azure by running `azd auth login`.
+3. Run `azd up` to deploy the application to Azure. This will provision Azure resources, deploy this sample, and build the search index based on the files found in the `./data` folder.
+   - You will be prompted to select a base location for the resources. If you're unsure of which location to choose, select `eastus2`.
+   - By default, the OpenAI resource will be deployed to `eastus2`. You can set a different location with `azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location>`. Currently only a short list of locations is accepted. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and may become outdated as availability changes.
+
+The deployment process will take a few minutes. Once it's done, you'll see the URL of the web app in the terminal.
+
+<div align="center">
+  <img src="./docs/images/azd-up.png" alt="Screenshot of the azd up command result" width="600px" />
+</div>
+
+You can now open the web app in your browser and start chatting with the bot.
+
+##### Enhance security
+
+When deploying the sample in an enterprise context, you may want to enforce tighter security restrictions to protect your data and resources. See the [enhance security](./docs/enhance-security.md) guide for more information.
+
+#### Enable CI/CD
+
+If you want to enable Continuous Deployment for your forked repository, you need to configure the Azure pipeline first:
+
+1. Open a terminal at the root of your forked project.
+2. Authenticate with Azure by running `azd auth login`.
+3. Run `azd pipeline config` to configure the required secrets and variables for connecting to Azure from GitHub Actions.
+   - This command will set up the necessary Azure service principal and configure GitHub repository secrets.
+   - Follow the prompts to complete the configuration.
+
+Once configured, the GitHub Actions workflow will automatically deploy your application to Azure whenever you push changes to the main branch.
+
+#### Clean up
+
+To clean up all the Azure resources created by this sample:
+
+1. Run `azd down --purge`
+2. When asked if you are sure you want to continue, enter `y`
+
+The resource group and all the resources will be deleted.
+
+### Run the sample locally with Ollama
+
+If you have a machine with enough resources, you can run this sample entirely locally without using any cloud resources. To do that, you first have to install [Ollama](https://ollama.com) and then run the following commands to download the models on your machine:
+
+```bash
+ollama pull llama3.1:latest
+ollama pull nomic-embed-text:latest
+```
+
+> [!NOTE]
+> The `llama3.1` model with download a few gigabytes of data, so it can take some time depending on your internet connection.
+
+After that you have to install the NPM dependencies:
+
+```bash
+npm install
+```
+
+Then you can start the application by running the following command which will start the web app and the API locally:
+
+```bash
+npm start
+```
+
+Then, open a new terminal running concurrently and run the following command to upload the PDF documents from the `/data` folder to the API:
+
+```bash
+npm run upload:docs
+```
+
+This only has to be done once, unless you want to add more documents.
+
+You can now open the URL `http://localhost:8000` in your browser to start chatting with the bot.
+
+> [!NOTE]
+> While local models usually works well enough to answer the questions, sometimes they may not be able to follow perfectly the advanced formatting instructions for the citations and follow-up questions. This is expected, and a limitation of using smaller local models.
+
+### Run the sample locally with Azure OpenAI models
+
+First you need to provision the Azure resources needed to run the sample. Follow the instructions in the [Deploy the sample to Azure](#deploy-the-sample-to-azure) section to deploy the sample to Azure, then you'll be able to run the sample locally using the deployed Azure resources.
+
+Once your deployment is complete, you should see a `.env` file in the `packages/api` folder. This file contains the environment variables needed to run the application using Azure resources.
+
+To run the sample, you can then use the same commands as for the Ollama setup. This will start the web app and the API locally:
+
+```bash
+npm start
+```
+
+Open the URL `http://localhost:8000` in your browser to start chatting with the bot.
+
+Note that the documents are uploaded automatically when deploying the sample to Azure with `azd up`.
+
+> [!TIP]
+> You can switch back to using Ollama models by simply deleting the `packages/api/.env` file and starting the application again. To regenerate the `.env` file, you can run `azd env get-values > packages/api/.env`.
+
+## Resources
+
+Here are some resources to learn more about the technologies used in this sample:
+
+- [LangChain.js documentation](https://js.langchain.com)
+- [Generative AI with JavaScript](https://github.com/microsoft/generative-ai-with-javascript)
+- [Generative AI For Beginners](https://github.com/microsoft/generative-ai-for-beginners)
+- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/overview)
+- [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/)
+- [Ask YouTube: LangChain.js + Azure Quickstart sample](https://github.com/Azure-Samples/langchainjs-quickstart-demo)
+- [Chat + Enterprise data with Azure OpenAI and Azure AI Search](https://github.com/Azure-Samples/azure-search-openai-javascript)
+- [Revolutionize your Enterprise Data with Chat: Next-gen Apps w/ Azure OpenAI and AI Search](https://aka.ms/entgptsearchblog)
+
+You can also find [more Azure AI samples here](https://github.com/Azure-Samples/azureai-samples).
+
+## FAQ
+
+You can find answers to frequently asked questions in the [FAQ](./docs/faq.md).
+
+## Troubleshooting
+
+If you have any issue when running or deploying this sample, please check the [troubleshooting guide](./docs/troubleshooting.md). If you can't find a solution to your problem, please [open an issue](https://github.com/Azure-Samples/serverless-chat-langchainjs/issues) in this repository.
+
+## Guidance
+
+For more detailed guidance on how to use this sample, please refer to the [tutorial](./docs/tutorial/01-introduction.md).
+
+## Getting Help
+
+If you get stuck or have any questions about building AI apps, join:
+
+[![Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+
+If you have product feedback or errors while building visit:
+
+[![Azure AI Foundry Developer Forum](https://img.shields.io/badge/GitHub-Azure_AI_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum)
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.
diff --git a/.github/skills/create-readme/references/serverless-recipes-javascript-readme.md b/.github/skills/create-readme/references/serverless-recipes-javascript-readme.md
new file mode 100644
index 0000000..d361fd6
--- /dev/null
+++ b/.github/skills/create-readme/references/serverless-recipes-javascript-readme.md
@@ -0,0 +1,162 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<img src="./docs/images/icon.png" alt="" align="center" height="96" />
+
+# Serverless Recipes for JavaScript/TypeScript
+
+[![Open project in GitHub Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/Azure-Samples/serverless-recipes-javascript?hide_repo_select=true&ref=main&quickstart=true)
+[![Join Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Community-blue?style=flat-square&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Azure-Samples/serverless-recipes-javascript/build-test.yaml?style=flat-square&label=Build)](https://github.com/Azure-Samples/serverless-recipes-javascript/actions)
+![Node version](https://img.shields.io/badge/Node.js->=20-3c873a?style=flat-square)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+⭐ If you like this project, star it on GitHub — it helps a lot!
+
+[Get started](#getting-started) • [Run the samples](#run-the-samples) • [Samples list](#samples-list) • [Resources](#resources) • [Troubleshooting](#troubleshooting)
+
+</div>
+
+This repository is a collection of code examples demonstrating how to build serverless applications using TypeScript and Azure. Each recipe is a standalone sample that demonstrates how to build a specific feature or use a specific technology. You can use these samples as a starting point for your own projects or to learn more about serverless development with Azure.
+
+> [!NOTE]
+> **What's Serverless?**<br>
+> Serverless computing allows you to build and run applications without managing infrastructure. You can focus on your code and let the cloud provider handle the rest. Azure provides a wide range of serverless services, including [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript), [Azure Static Web Apps]([Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview), [Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db/nosql/), and more.
+
+## Why serverless?
+
+Let's say you're a developer for the Contoso Solutions company, and you've been tasked to build new applications with a fast turnaround time, startup style. You need to build these apps quickly with a low initial budget, and you don't want to worry about managing servers, scaling, or infrastructure. **You want to focus on writing code and delivering value to your users.**
+
+*This is exactly where serverless is a great fit!*
+
+While walking through this collection of ready-to-use code examples, you'll learn how to solve common problems and build applications using many of the serverless technologies available on Azure. The best part? You only need to pay attention to the code and the business logic, all samples are ready to deploy and run in your Azure account.
+
+## Prerequisites
+- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents).
+- **GitHub account**. If you don't have one, you can [create a free GitHub account](https://github.com/signup). You can optionally use [GitHub Copilot Free](https://github.com/features/copilot) to help you write code and ship your application even faster.
+
+## Getting started
+
+There are multiple ways to get started with this project.
+
+The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
+
+<details open>
+<summary><h3>Use GitHub Codespaces</h3></summary>
+
+You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
+
+[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=flat-square&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/serverless-recipes-javascript?hide_repo_select=true&ref&quickstart=true)
+
+</details>
+
+<details>
+<summary><h3>Use a VSCode dev container</h3></summary>
+
+A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+
+You will also need to have [Docker](https://www.docker.com/get-started/) installed on your machine to run the container.
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=flat-square&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/serverless-recipes-javascript)
+
+</details>
+
+<details>
+<summary><h3>Use your local environment</h3></summary>
+
+You need to install following tools to work on your local machine:
+
+- [Node.js LTS](https://nodejs.org/en/download)
+- [Azure Developer CLI](https://aka.ms/azure-dev/install)
+- [Git](https://git-scm.com/downloads)
+- [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_
+  - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
+  - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
+- [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_
+
+Then you can get the project code:
+
+1. [**Fork**](https://github.com/Azure-Samples/serverless-recipes-javascript/fork) the project to create your own copy of this repository.
+2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
+
+   ![Screenshot showing how to copy the repository URL](./docs/images/clone-url.png)
+3. Open a terminal and run this command to clone the repo: `git clone <your-repo-url>`
+
+</details>
+
+## Run the samples
+
+After setting up your environment, you can deploy and run any of the samples. Each sample is a standalone project that you can run independently. Follows these steps to run a sample:
+
+```bash
+# Open the sample directory
+cd samples/<sample-name>
+
+# Install dependencies
+npm install
+
+# Deploy the sample to Azure
+azd auth login
+azd up
+```
+
+Once the initial deployment is completed, you can also run the sample locally with `npm start`.
+You can check the `README.md` file in each sample directory for more specific instructions.
+
+## Samples list
+
+<!-- #begin-samples -->
+
+| | Sample | Deployment Time | Video | Blog |
+| --- |:--- | --- | --- | --- |
+| <img src="./samples/openai-extension-embeddings/docs/images/icon.png" width="32px"/> | [Azure Functions OpenAI extension - embeddings](./samples/openai-extension-embeddings) | 5min | - | - |
+| <img src="./samples/openai-extension-textcompletion/docs/images/icon.png" width="32px"/> | [Azure Functions OpenAI extension - text completion](./samples/openai-extension-textcompletion) | 5min | - | - |
+
+<!-- #end-samples -->
+
+## Resources
+
+Here are some additional resources to learn more about the technologies used:
+
+- [Serverless Node.js with Azure Functions](https://learn.microsoft.com/azure/developer/javascript/how-to/develop-serverless-apps?tabs=v4-ts) (Microsoft Learn)
+- [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/) (Microsoft Learn)
+- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/overview) (Microsoft Learn)
+- [Generative AI with JavaScript](https://github.com/microsoft/generative-ai-with-javascript) (GitHub)
+- [Serverless AI Chat with RAG using LangChain.js](https://github.com/Azure-Samples/serverless-chat-langchainjs) (GitHub)
+
+## Troubleshooting
+
+If you have any issue when running or deploying the samples, please check the [troubleshooting guide](./docs/troubleshooting.md). If you can't find a solution to your problem, please [open an issue](https://github.com/Azure-Samples/serverless-recipes-javascript/issues) in this repository.
+
+## Getting Help
+
+If you get stuck or have any questions about building AI apps, join:
+
+[![Azure AI Foundry Discord](https://img.shields.io/badge/Discord-Azure_AI_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
+
+If you have product feedback or errors while building visit:
+
+[![Azure AI Foundry Developer Forum](https://img.shields.io/badge/GitHub-Azure_AI_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum)
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.
diff --git a/.github/skills/create-readme/references/smoke-readme.md b/.github/skills/create-readme/references/smoke-readme.md
new file mode 100644
index 0000000..fd2fc80
--- /dev/null
+++ b/.github/skills/create-readme/references/smoke-readme.md
@@ -0,0 +1,366 @@
+# :dash: smoke
+
+[![NPM version](https://img.shields.io/npm/v/smoke.svg)](https://www.npmjs.com/package/smoke)
+[![Build Status](https://github.com/sinedied/smoke/workflows/build/badge.svg)](https://github.com/sinedied/smoke/actions)
+![Node version](https://img.shields.io/node/v/smoke.svg)
+[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> Simple yet powerful file-based mock server with recording abilities
+
+![demo](https://user-images.githubusercontent.com/593151/49312821-9f2cc680-f4e5-11e8-900a-117120c38422.gif)
+
+Just drop a bunch of (JSON) files in a folder and you're ready to go!
+
+### Basic mock example
+1. Start the server: `smoke`
+2. Create a file named `get_api#hello.json`:
+    ```json
+    {
+      "message": "hello world!"
+    }
+    ```
+3. Test the mock: `curl http://localhost:3000/api/hello`
+
+### Features
+
+**Smoke** is a file-based, convention over configuration mock server that can fill your API mocking needs without any
+complex setup. Yet, it supports many advanced features and dynamic mocks for almost any situation:
+
+- Generate mocks quickly by recording responses from an existing server
+- Use folders and file names to describe API routes and REST methods
+- Use templates to generate responses based on input queries and route parameters
+- Add / edit / remove mocks without restarting the server
+- Generate mocks with JavaScript for more complex responses
+- Define different mock sets to simulate various scenarii (errors...), with fallback
+- Customize headers and status code if needed, automatically detect content-type if not specified
+- Add custom middlewares to modify requests/responses
+- Mock only specific requests and proxy the rest to an existing server
+- Supports CORS (cross-origin resource-sharing)
+
+## Installation
+
+```bash
+npm install -g smoke
+```
+
+## Usage
+
+See [some example mocks](test/mocks) to quickly get a grasp of the syntax and possibilities.
+
+CLI usage is quite straightforward you can just run `smoke` unless you want to add some options:
+```
+Usage: smoke [<mocks_folder>] [options]
+
+Base options:
+  -p, --port <num>                  Server port           [default: 3000]
+  -h, --host <host>                 Server host           [default: "localhost"]
+  -s, --set <name>                  Mocks set to use      [default: none]
+  -n, --not-found <glob>            Mocks for 404 errors  [default: "404.*"]
+  -i, --ignore <glob>               Files to ignore       [default: none]
+  -k, --hooks <file>                Middleware hooks      [default: none]
+  -x, --proxy <host>                Fallback proxy if no mock found
+  -o, --allow-cors [all|<hosts>]    Enable CORS requests  [default: none]
+  --https                           Enable secure request serving with HTTPS [default: false]
+  -l, --logs                        Enable server logs
+  -v, --version                     Show version
+  --help                            Show help
+
+Mock recording:
+  -r, --record <host>               Proxy & record requests if no mock found
+  -c, --collection <file>           Save to single file mock collection
+  -d, --depth <N>                   Folder depth for mocks  [default: 1]
+  -a, --save-headers                Save response headers
+  -q, --save-query                  Save query parameters
+```
+
+### File naming
+
+**General format:** `methods_api#route#@routeParam$queryParam=value.__set.extension`
+
+The path and file name of the mock is used to determinate:
+
+#### Supported HTTP methods
+Optionally prefix your file by the HTTP method supported followed by an underscore (for example `get_`).
+You can specify multiple methods at once using a `+` to separate them (for example `post+put_`);
+If no method is specified, the mock will be used for any HTTP method.
+
+#### Server route and named route parameters
+Use any combination of folders or hash-separated components to specify the server route.
+
+For example `api/example/get_hello.json` is equivalent to `get_api#example#hello.json` and will respond to
+`GET api/example/hello` requests.
+
+Additionaly, any route component can be defined as a route parameter by prefixing the name with `@`, for example
+`api#resource#@id.json` will match `GET api/resource/1` and expose `1` as the value for the `id` parameter that can be
+used in dynamic mocks (templates or JavaScript).
+
+#### Query parameters
+You can further discriminate mocks by adding query parameters to match after defining the route, using a `$` (instead
+of the regular `?`) like you would specify them in a request.
+
+For example `get_api#hello$who=john.json` will match the request `api/get_hello?who=john.json`.
+
+Multiple query parameters to match can be added with `&`, for example `get_api#hello$who=john&greet=hi.json`.
+Any specified query parameter in the file name must be matched (in any order) by the request, but the opposite is not
+needed.
+
+Note that special characters must be URL-encoded, for example use `get_api#hello$who=john%20doe.json` to set the
+parameter `who` with the value `john doe`.
+
+> Tip: If you need to URL-encode a string, just run `node -p "encodeURIComponent('some string')"` in a terminal.
+
+#### Content type
+The file extension will determine the content type of the response if it's not already specified in a
+[custom header](#custom-status-and-headers).
+
+Files with no extension will use the default MIME type `application/octet-stream`.
+
+You can have multiple mocks with the same API route and different file extensions, the server will then use the best
+mock depending of the [`Accept` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) of the
+request.
+
+#### Mock set
+You can optionally specify a mock set before the file extension by using a `__set-name` suffix after the file name.
+
+For example `get_api#hello__error.json` will only be used if you start the server with the `error` set enabled:
+`smoke --set error`.
+
+If you do not specify a mock set on your file name, it will be considered as the default mock for the specified route
+and will be used as a fallback if no mock with this set matched.
+
+#### Templates
+If you add an underscore `_` after the file extension, the mock will be processed as a template before being sent to
+the client. Templates works only on text-based formats.
+
+For example `get_hello.html_` or `get_hello.json_` will be treated as templates. 
+
+Every template can use an implicit context object that have these properties defined:
+- `method`: the HTTP method of the request (ex: `'GET'`, `'POST'`)
+- `query`: map with query parameters that were part of the request URL. For example, matched URL
+  `http://server/hello?who=world` will result in the query value: `{ who: 'world' }`.
+- `params`: map containing matched route parameters. For example the mock `resource#@id.json_` with the matched URL
+  `http://server/resource/123` will result in the params value: `{ id: '123' }`.
+- `headers`: map containing request headers
+- `body`: the request body. JSON bodies are automatically parsed.
+- `files`: if the request includes `multipart/form-data`, this will be the array of uploaded files (see
+  [multer documentation](https://github.com/expressjs/multer) for more details)
+
+##### Template syntax
+
+- `{{ }}` interpolates data in place
+
+  For example, create **get_hello.txt_** with this:
+  ```
+  Hello {{query.name}}!
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=John"` returns `Hello John!`
+
+- `{{{ }}}` escapes HTML special chars from interpolated string
+
+  For example, create **get_hello.html_** with this:
+  ```html
+  <h1>Hello {{{query.name}}}!</h1>
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=%3CJack%26Jones%3E"` returns:
+  ```html
+  <h1>Hello &lt;Jack&amp;Jones&gt;!</h1>
+  ```
+
+- `<{ }>` evaluates JavaScript to generate data
+
+  For example, create **get_hello.html_** with this:
+  ```html
+  Hello to:
+  <ul>
+    <{ query.name.forEach(name => { }><li>{{name}}</li><{ }); }>
+  </ul>
+  ```
+
+  Then `curl "http://localhost:3000/hello?name=Jack&name=Jones"` returns:
+  ```html
+  Hello to:
+  <ul>
+    <li>Jack</li><li>Jones</li>
+  </ul>
+  ```
+
+### Custom status and headers
+
+By default all mocks responses are sent with a status code `200` (OK), or `204` (No content) if a mock file is empty.
+
+You can customize the response status and (optionally) headers with JSON and [JavaScript](#javascript-mocks) files,
+using this syntax:
+```js
+{
+  "statusCode": 400,
+  "body": {
+    "error": "Bad request"
+  },
+  // headers can be omitted, only use if you want to customize them
+  "headers": {
+    "Content-Type": "text/plain"
+  } 
+}
+```
+
+You can also use non-string content type if you encode the content as a base64 string in the `body` property and add
+the property `"buffer": true` to the mock:
+```js
+{
+  "statusCode": 200,
+  "body": "U21va2Ugcm9ja3Mh",
+  "buffer": true,
+  "headers": {
+    "Content-Type": "application/octet-stream"
+  } 
+}
+```
+
+### Mock formats
+
+Any file format is supported for mocks, and the file extension will be used to determine the response content type.
+Files with no extension will use the default MIME type `application/octet-stream`.
+
+Text formats (for example `.json`, `.html`, `.txt`...) can be processed as [templates](#templates) by adding an
+underscore to the file extension.
+
+Note that JSON files and templates must use `UTF-8` encoding.
+
+#### JavaScript mocks
+
+In addition, you can define dynamic mocks using JavaScript by using the `.js` extension, that will be loaded as a regular
+Node.js module.
+
+In that case, your JS module is expected to export a function that take an input data object with the
+[same properties](#templates) as for templates and must returns the response body or an
+[object](#custom-status-and-headers) containing the status code, headers and body.
+
+Example:
+```js
+export default (data) => `{ "data": "Your user agent is: ${data.headers['user-agent']}" }`;
+```
+
+Note that by default, JS mocks use `application/json` for the response content type. If you want to use another type,
+you must set the `Content-Type` header yourself, for example:
+```js
+export default data => ({
+  statusCode: 200,
+  headers: {
+    'Content-Type': 'text/plain'
+  },
+  body: `Your user agent is: ${data.headers['user-agent']}`
+});
+```
+
+### Fallback proxy
+
+If you want to override responses of an existing server, you can use the `--proxy <host>` option. This will proxy
+every request for which a mock does not exist to the specified host.
+
+This can also be useful for mocking yet-to-be-implemented APIs and keep using real implemented APIs.
+
+### Mock recording
+
+To quickly create a mock set of an existing server (to allow working offline for example), you can use the
+`--record <host>` option. This will proxy every request for which a mock does not exist to the specified host, and
+record the resulting response as a mock file.
+
+You can change the maximum folder depth for mock files created this way using the `--depth` option.
+
+The recorded mock set can also be changed using the `--set` option.
+
+Instead of recoring separate mock files, you can also record to a
+[single file mock collection](#single-file-mock-collection) using the `--collection <file>` option. 
+
+Note that by default response headers and request query parameters are not saved. To change this behavior, you can
+use the `--save-headers` and `--save-query` options.
+
+### Middleware hooks
+
+For more advanced usages, you can hook on any standard
+[Express middleware](https://expressjs.com/en/guide/writing-middleware.html) to modify the request and/or the response
+returned by the server.
+
+To hook on your own middlewares, use the `--hooks` to specify a JavaScript module with exports setup like this:
+```js
+export const before = []; // middlewares to be executed before the request is processed
+export const after = [];  // middlewares to be executed after the request has been processed
+```
+
+Middlewares executed before the request is processed can be used to bypass regular mock response, for example to
+randomly simulate a server failure with an early error 500 response.
+
+On the other hand, middlewares executed after the request have been processed can be used to augment or modify the
+response, for example by adding header or changing the response status. You can also access and modify the response
+body by using the special `res.body` property.
+
+Remember that once you have used `.send()`, `.sendStatus` or `.json()` in a middleware the response cannot be altered
+anymore, that's why you should use the `res.body` property instead if you plan to alter the response later on.
+
+See some [example hooks](test/hooks.js).
+
+## Enabling CORS
+
+Smoke offers support to requests originating from a different origin. However, by default, this would be disabled.
+
+To enable CORS, pass the hosts that you want to allow to `-o` or `--allow-cors` arguments.
+
+**Accepted Values**
+- `all` - Allow requests from `*`
+- `<hosts>` - You could also pass a comma-separated list of hosts that you want to allow requests from something like `'http://localhost:3000,http://example.com'`
+
+### Single file mock collection
+
+You can regroup multiple mocks in a special single file with the extension `.mocks.js`, using this format:
+```js
+export default {
+  '<file_name>': '<file_content>' // can be a string, an object (custom response) or a function (JavaScript mock)
+};
+```
+See this [example mock collection](test/mocks/collection.mocks.js) to get an idea of all possibilities.
+
+The format of file name is the same as for individual mock files, and will be used to match the request using the same
+rules. As for the mock content, the format is also the same as what you would put in single file mock. If a request
+matches both a mock file and a mock within a collection with the same specificity, the mock file will always be used
+over the collection.
+
+As the format is the same, you can convert a bunch of files to a single file mock collection and conversely.
+To convert separate mock files to a collection:
+```sh
+smoke-conv <glob> <output_file>  // Will create <output_file>.mocks.js from all mocks found
+```
+
+To convert a mock collection to separate files:
+```sh
+smoke-conv <file> <output_folder>  // Will extract separate mocks into <output_folder>
+```
+
+Note that only text-based file content will be inserted directly, other file content will be converted to a base64
+string.
+
+:warning: There is a limitation regarding JavaScript mocks: only the exported function will be converted for a given
+mock, meaning that if you have non-exported functions, variables or imports they will be lost during the conversion.
+
+## Migration from v1/v2/v3 to v4
+
+If you are migrating from a previous version of Smoke, you need to be aware that the default module format has changed: earlier version used CommonJS modules, while v4 uses ES modules by default.
+
+But don't worry! You don't have to regenerate or updates all your mock files, Smoke will still support the CommonJS format for backward compatibility, though you need to rename all your `*.js` mocks, collections and hooks files to use the `.cjs` extension instead of `.js`.
+
+If you prefer to migrate your existing mock files to the new ES module format, you can do so by updating the export syntax to use `export default` instead of `module.exports` in mock files and collections, and `export` the `before` and `after` hooks constant separately in hooks fles.
+
+> [!NOTE]
+> If you try to record new mocks into an existing collection in CommonJS format, the result will be saved into a new collection in ES modules format.
+
+## Other mock servers
+
+If you cannot find what you need here, you might want to check out one of these other Node.js mock servers:
+
+- [JSON Server](https://github.com/typicode/json-server)
+- [mockserver](https://github.com/namshi/mockserver)
+- [node-mock-server](https://github.com/smollweide/node-mock-server)
+- [node-easymock](https://github.com/CyberAgent/node-easymock)
+- [mockserver-node](https://github.com/jamesdbloom/mockserver-node)
diff --git a/.github/skills/dotnet-aspnet/SKILL.md b/.github/skills/dotnet-aspnet/SKILL.md
index 1a6a094..b3ba212 100644
--- a/.github/skills/dotnet-aspnet/SKILL.md
+++ b/.github/skills/dotnet-aspnet/SKILL.md
@@ -1,372 +1,46 @@
 ---
 name: dotnet-aspnet
-description: ASP.NET Core best practices for building Web and REST APIs. Use when creating controllers, minimal APIs, configuring middleware, routing, model binding, validation, dependency injection, authentication, authorization, error handling with ProblemDetails, OpenAPI/Swagger, health checks, CORS, rate limiting, or structuring an ASP.NET Core project.
+description: Applies ASP.NET Core best practices for building Web and REST APIs. Use when creating controllers, minimal APIs, configuring middleware, routing, model binding, validation, authentication, authorization, error handling with ProblemDetails, OpenAPI/Swagger, health checks, CORS, rate limiting, or structuring an ASP.NET Core project. For DI, Options pattern, and configuration that apply to any .NET host, use dotnet-fundamentals.
 ---
 
 # ASP.NET Core Web API Best Practices
 
-## Project Structure
+## When to Use
 
-- Organize code by feature/domain, not by layer (avoid generic `Controllers/`, `Services/`, `Models/` folders)
-- Use `Program.cs` as the composition root — register services, configure middleware pipeline
-- Keep `Program.cs` lean by extracting registration into extension methods (e.g., `AddApplicationServices()`, `AddAuthenticationServices()`)
-- Use feature folders:
-  ```
-  Features/
-    Orders/
-      OrdersController.cs
-      CreateOrderRequest.cs
-      OrderResponse.cs
-      OrderService.cs
-    Products/
-      ...
-  ```
+- Creating new controllers, minimal API endpoints, or feature folders in an ASP.NET Core project
+- Configuring the middleware pipeline, routing, or model binding
+- Adding authentication, authorization policies, or `[Authorize]`-based access control
+- Implementing error handling with `ProblemDetails` (RFC 9457) or `IExceptionHandler`
+- Wiring up OpenAPI/Swagger, health checks, CORS, rate limiting, output caching, or response compression
+- Reviewing or restructuring an existing ASP.NET Core project to align with best practices
 
-## Controllers vs Minimal APIs
+This skill covers the **HTTP / web layer only**. For dependency injection, Options pattern, and configuration that apply to any .NET host, see [`dotnet-fundamentals`](../dotnet-fundamentals/SKILL.md).
 
-### Controllers
+## Core Principles
 
-Use controllers for larger APIs with shared conventions, filters, and complex routing:
+- Use feature folders, not layer folders. Keep `Program.cs` lean — extract registrations into extension methods.
+- Always use `[ApiController]` on MVC controllers; prefer `TypedResults` in minimal APIs.
+- Accept `CancellationToken` on every async endpoint.
+- Map domain exceptions to ProblemDetails — never leak internal exception messages.
+- Middleware order matters: exception handler → status code pages → HSTS/HTTPS → CORS → auth → rate limiter → endpoints.
 
-```csharp
-[ApiController]
-[Route("api/[controller]")]
-public class OrdersController(IOrderService orderService) : ControllerBase
-{
-    [HttpGet("{id:guid}")]
-    [ProducesResponseType<OrderResponse>(StatusCodes.Status200OK)]
-    [ProducesResponseType(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
-    {
-        var order = await orderService.GetByIdAsync(id, ct);
-        return order is null ? NotFound() : Ok(order);
-    }
-}
-```
+## Reference Index
 
-- Always use `[ApiController]` attribute — enables automatic model validation, binding source inference, and ProblemDetails responses
-- Use primary constructor injection for dependencies
-- Return `IActionResult` or `ActionResult<T>` for endpoints with multiple response types
-- Accept `CancellationToken` on all async endpoints
+Detailed patterns and code samples live in `references/`:
 
-### Minimal APIs
-
-Use minimal APIs for simple endpoints, microservices, or when startup performance matters:
-
-```csharp
-var group = app.MapGroup("/api/orders")
-    .WithTags("Orders")
-    .RequireAuthorization();
-
-group.MapGet("/{id:guid}", async (Guid id, IOrderService service, CancellationToken ct) =>
-{
-    var order = await service.GetByIdAsync(id, ct);
-    return order is null ? Results.NotFound() : Results.Ok(order);
-})
-.WithName("GetOrderById")
-.Produces<OrderResponse>()
-.ProducesProblem(StatusCodes.Status404NotFound);
-```
-
-- Use `MapGroup()` to share route prefixes, filters, and metadata
-- Use `TypedResults` instead of `Results` for compile-time response type verification
-- Add `.WithName()` for OpenAPI operation IDs and link generation
-- Use endpoint filters for cross-cutting concerns
-
-## Routing & Endpoints
-
-- Use attribute routing on controllers (`[Route]`, `[HttpGet]`, etc.)
-- Apply route constraints: `{id:guid}`, `{page:int:min(1)}`, `{slug:regex(^[a-z-]+$)}`
-- Use API versioning via URL segment (`/api/v1/orders`) or header-based versioning with `Asp.Versioning.Http`
-- Keep route templates consistent — plural nouns for resources (`/api/orders`, not `/api/order`)
-- Use `LinkGenerator` for generating URLs to named endpoints
-
-## Model Binding & Validation
-
-- Use binding source attributes explicitly: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromHeader]`
-- With `[ApiController]`, complex types default to `[FromBody]`, simple types to `[FromRoute]`/`[FromQuery]`
-- Validate with Data Annotations or FluentValidation:
-
-```csharp
-public record CreateOrderRequest(
-    [Required] string CustomerId,
-    [Required, MinLength(1)] List<OrderItemRequest> Items);
-```
-
-- For FluentValidation: register validators via `AddValidatorsFromAssemblyContaining<T>()` and use a validation filter or `IEndpointFilter`
-- Return `ValidationProblemDetails` (automatic with `[ApiController]`) for validation failures
-
-## Dependency Injection
-
-- Register services in `Program.cs` or via extension methods
-- Use appropriate lifetimes:
-  - **Transient**: Stateless, lightweight services
-  - **Scoped**: Per-request services (DbContext, unit of work)
-  - **Singleton**: Thread-safe, shared state (caches, configuration)
-- Use keyed services (.NET 8+) when multiple implementations of the same interface are needed:
-  ```csharp
-  builder.Services.AddKeyedScoped<IPaymentGateway, StripeGateway>("stripe");
-  builder.Services.AddKeyedScoped<IPaymentGateway, PayPalGateway>("paypal");
-  ```
-- Prefer interface-based registration for testability
-- Avoid service locator pattern — do not inject `IServiceProvider` into business logic
-
-## Middleware Pipeline
-
-Order matters — register middleware in the correct sequence:
-
-```csharp
-app.UseExceptionHandler();
-app.UseStatusCodePages();
-app.UseHsts();
-app.UseHttpsRedirection();
-app.UseCors();
-app.UseAuthentication();
-app.UseAuthorization();
-app.UseRateLimiter();
-app.UseOutputCache();
-app.MapControllers();
-```
-
-### Custom Middleware
-
-```csharp
-public class RequestTimingMiddleware(RequestDelegate next)
-{
-    public async Task InvokeAsync(HttpContext context)
-    {
-        var sw = Stopwatch.StartNew();
-        context.Response.OnStarting(() =>
-        {
-            context.Response.Headers["X-Response-Time-Ms"] = sw.ElapsedMilliseconds.ToString();
-            return Task.CompletedTask;
-        });
-        await next(context);
-    }
-}
-```
-
-- Use primary constructors for middleware
-- Inject scoped services via `InvokeAsync` parameters, not the constructor
-- Keep middleware focused — one concern per middleware
-
-## Configuration
-
-- Use the Options pattern for strongly-typed configuration:
-
-```csharp
-public class SmtpOptions
-{
-    public const string SectionName = "Smtp";
-    public required string Host { get; init; }
-    public int Port { get; init; } = 587;
-    public required string Username { get; init; }
-}
-
-builder.Services.AddOptions<SmtpOptions>()
-    .BindConfiguration(SmtpOptions.SectionName)
-    .ValidateDataAnnotations()
-    .ValidateOnStart();
-```
-
-- Use `ValidateOnStart()` to catch configuration errors at startup, not at first use
-- Use `appsettings.json` for defaults, `appsettings.{Environment}.json` for overrides
-- Use User Secrets (`dotnet user-secrets`) for local development — never commit secrets
-- Use environment variables or a vault for production secrets
-- Inject `IOptions<T>` for static config, `IOptionsMonitor<T>` for reloadable config
-
-## Authentication & Authorization
-
-### JWT Bearer Authentication
-
-```csharp
-builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
-    .AddJwtBearer(options =>
-    {
-        options.Authority = builder.Configuration["Auth:Authority"];
-        options.Audience = builder.Configuration["Auth:Audience"];
-    });
-```
-
-### Authorization Policies
-
-```csharp
-builder.Services.AddAuthorizationBuilder()
-    .AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"))
-    .AddPolicy("CanEditOrder", policy =>
-        policy.Requirements.Add(new OrderOwnerRequirement()));
-```
-
-- Use policy-based authorization over role checks in attributes
-- Apply `[Authorize]` at controller level, `[AllowAnonymous]` for exceptions
-- Implement `IAuthorizationHandler` for resource-based authorization
-- For minimal APIs use `.RequireAuthorization("PolicyName")`
-
-## Error Handling
-
-### ProblemDetails (RFC 9457)
-
-```csharp
-builder.Services.AddProblemDetails(options =>
-{
-    options.CustomizeProblemDetails = ctx =>
-    {
-        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
-    };
-});
-```
-
-### Global Exception Handling (.NET 8+)
-
-```csharp
-public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
-{
-    public async ValueTask<bool> TryHandleAsync(
-        HttpContext context, Exception exception, CancellationToken ct)
-    {
-        logger.LogError(exception, "Unhandled exception");
-
-        var problem = new ProblemDetails
-        {
-            Status = StatusCodes.Status500InternalServerError,
-            Title = "An error occurred",
-            Type = "https://httpstatuses.com/500"
-        };
-
-        context.Response.StatusCode = problem.Status.Value;
-        await context.Response.WriteAsJsonAsync(problem, ct);
-        return true;
-    }
-}
-
-builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
-```
-
-- Use `IExceptionHandler` (.NET 8+) instead of custom exception middleware
-- Map domain exceptions to appropriate HTTP status codes
-- Never expose internal exception details in production responses
-- Use `app.UseStatusCodePages()` for consistent responses on empty status codes (404, 405, etc.)
-
-## API Conventions & Response Types
-
-- Annotate endpoints with `[ProducesResponseType]` for OpenAPI documentation
-- Use `[Consumes]` and `[Produces]` for content type negotiation
-- Return consistent response envelopes or use ProblemDetails for errors
-- Use `TypedResults` in minimal APIs for compile-time response verification:
-
-```csharp
-group.MapPost("/", async (CreateOrderRequest req, IOrderService service, CancellationToken ct) =>
-{
-    var id = await service.CreateAsync(req, ct);
-    return TypedResults.Created($"/api/orders/{id}", new { id });
-});
-```
-
-## OpenAPI / Swagger
-
-- Use the built-in OpenAPI support (.NET 9+) or Swashbuckle/NSwag for earlier versions:
-
-```csharp
-builder.Services.AddOpenApi();
-// ...
-app.MapOpenApi();
-```
-
-- Enable XML comments in `.csproj` for automatic documentation:
-  ```xml
-  <PropertyGroup>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <NoWarn>$(NoWarn);1591</NoWarn>
-  </PropertyGroup>
-  ```
-- Use `[Tags]`, `[EndpointSummary]`, `[EndpointDescription]` for metadata
-- Use `WithName()` and `WithTags()` on minimal API endpoints
-- Use the `csharp-docs` skill for writing XML documentation comments
-
-## Health Checks
-
-```csharp
-builder.Services.AddHealthChecks()
-    .AddCheck("self", () => HealthCheckResult.Healthy())
-    .AddNpgSql(connectionString, name: "database")
-    .AddRedis(redisConnectionString, name: "cache");
-
-app.MapHealthChecks("/health", new HealthCheckOptions
-{
-    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
-});
-
-app.MapHealthChecks("/health/ready", new HealthCheckOptions
-{
-    Predicate = check => check.Tags.Contains("ready")
-});
-```
-
-- Separate liveness (`/health`) and readiness (`/health/ready`) endpoints
-- Tag health checks for selective filtering
-- Use NuGet packages `AspNetCore.HealthChecks.*` for common dependencies
-- Use the `nuget-manager` skill for adding health check packages
-
-## Cross-Cutting Concerns
-
-### CORS
-
-```csharp
-builder.Services.AddCors(options =>
-{
-    options.AddPolicy("AllowFrontend", policy =>
-        policy.WithOrigins("https://app.example.com")
-              .AllowAnyHeader()
-              .AllowAnyMethod()
-              .AllowCredentials());
-});
-
-app.UseCors("AllowFrontend");
-```
-
-### Rate Limiting (.NET 7+)
-
-```csharp
-builder.Services.AddRateLimiter(options =>
-{
-    options.AddFixedWindowLimiter("api", limiter =>
-    {
-        limiter.PermitLimit = 100;
-        limiter.Window = TimeSpan.FromMinutes(1);
-    });
-    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
-});
-
-app.UseRateLimiter();
-```
-
-- Apply per-endpoint with `[EnableRateLimiting("api")]` or `.RequireRateLimiting("api")`
-
-### Output Caching (.NET 7+)
-
-```csharp
-builder.Services.AddOutputCache(options =>
-{
-    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
-    options.AddPolicy("NoCache", builder => builder.NoCache());
-});
-```
-
-### Response Compression
-
-```csharp
-builder.Services.AddResponseCompression(options =>
-{
-    options.EnableForHttps = true;
-    options.Providers.Add<BrotliCompressionProvider>();
-    options.Providers.Add<GzipCompressionProvider>();
-});
-```
+- **[project-and-endpoints.md](references/project-and-endpoints.md)** — Project structure, Controllers vs Minimal APIs, routing, API conventions, response types (`TypedResults`, `[ProducesResponseType]`)
+- **[model-binding-validation.md](references/model-binding-validation.md)** — Binding sources (`[FromBody]`, `[FromRoute]`, etc.), Data Annotations, FluentValidation, `ValidationProblemDetails`
+- **[middleware.md](references/middleware.md)** — Pipeline order, custom middleware with primary constructors
+- **[auth.md](references/auth.md)** — JWT Bearer, authorization policies, `IAuthorizationHandler`, `RequireAuthorization`
+- **[error-handling.md](references/error-handling.md)** — ProblemDetails, `IExceptionHandler` (.NET 8+), `UseStatusCodePages`
+- **[openapi-and-cross-cutting.md](references/openapi-and-cross-cutting.md)** — OpenAPI/Swagger, XML doc generation, health checks (liveness/readiness), CORS, rate limiting, output caching, response compression
 
 ## Related Skills
 
-- **[ef-core](../ef-core/SKILL.md)** — Data access with Entity Framework Core
-- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Unit and integration testing
-- **[csharp-docs](../csharp-docs/SKILL.md)** — XML documentation comments
-- **[nuget-manager](../nuget-manager/SKILL.md)** — NuGet package management
-- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — SDK/client library generation
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Foundation: DI, Options pattern, configuration, modern C# idioms used by every endpoint and service in this skill
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — Data access with Entity Framework Core
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Unit and integration testing for endpoints
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — XML documentation comments (feed OpenAPI)
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Invoked for adding health-check, resilience, and middleware packages
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Generates typed HTTP clients for consuming these APIs
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Reviews ASP.NET Core code for security, performance, and architecture issues
diff --git a/.github/skills/dotnet-aspnet/references/auth.md b/.github/skills/dotnet-aspnet/references/auth.md
new file mode 100644
index 0000000..52f2641
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/auth.md
@@ -0,0 +1,26 @@
+# Authentication & Authorization
+
+## JWT Bearer Authentication
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.Authority = builder.Configuration["Auth:Authority"];
+        options.Audience = builder.Configuration["Auth:Audience"];
+    });
+```
+
+## Authorization Policies
+
+```csharp
+builder.Services.AddAuthorizationBuilder()
+    .AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"))
+    .AddPolicy("CanEditOrder", policy =>
+        policy.Requirements.Add(new OrderOwnerRequirement()));
+```
+
+- Use policy-based authorization over role checks in attributes
+- Apply `[Authorize]` at controller level, `[AllowAnonymous]` for exceptions
+- Implement `IAuthorizationHandler` for resource-based authorization
+- For minimal APIs use `.RequireAuthorization("PolicyName")`
diff --git a/.github/skills/dotnet-aspnet/references/error-handling.md b/.github/skills/dotnet-aspnet/references/error-handling.md
new file mode 100644
index 0000000..09282b5
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/error-handling.md
@@ -0,0 +1,44 @@
+# Error Handling
+
+## ProblemDetails (RFC 9457)
+
+```csharp
+builder.Services.AddProblemDetails(options =>
+{
+    options.CustomizeProblemDetails = ctx =>
+    {
+        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
+    };
+});
+```
+
+## Global Exception Handling (.NET 8+)
+
+```csharp
+public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(
+        HttpContext context, Exception exception, CancellationToken ct)
+    {
+        logger.LogError(exception, "Unhandled exception");
+
+        var problem = new ProblemDetails
+        {
+            Status = StatusCodes.Status500InternalServerError,
+            Title = "An error occurred",
+            Type = "https://httpstatuses.com/500"
+        };
+
+        context.Response.StatusCode = problem.Status.Value;
+        await context.Response.WriteAsJsonAsync(problem, ct);
+        return true;
+    }
+}
+
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
+```
+
+- Use `IExceptionHandler` (.NET 8+) instead of custom exception middleware
+- Map domain exceptions to appropriate HTTP status codes
+- Never expose internal exception details in production responses
+- Use `app.UseStatusCodePages()` for consistent responses on empty status codes (404, 405, etc.)
diff --git a/.github/skills/dotnet-aspnet/references/middleware.md b/.github/skills/dotnet-aspnet/references/middleware.md
new file mode 100644
index 0000000..9940ff3
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/middleware.md
@@ -0,0 +1,38 @@
+# Middleware Pipeline
+
+Order matters — register middleware in the correct sequence:
+
+```csharp
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+app.UseHsts();
+app.UseHttpsRedirection();
+app.UseCors();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseRateLimiter();
+app.UseOutputCache();
+app.MapControllers();
+```
+
+## Custom Middleware
+
+```csharp
+public class RequestTimingMiddleware(RequestDelegate next)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var sw = Stopwatch.StartNew();
+        context.Response.OnStarting(() =>
+        {
+            context.Response.Headers["X-Response-Time-Ms"] = sw.ElapsedMilliseconds.ToString();
+            return Task.CompletedTask;
+        });
+        await next(context);
+    }
+}
+```
+
+- Use primary constructors for middleware
+- Inject scoped services via `InvokeAsync` parameters, not the constructor
+- Keep middleware focused — one concern per middleware
diff --git a/.github/skills/dotnet-aspnet/references/model-binding-validation.md b/.github/skills/dotnet-aspnet/references/model-binding-validation.md
new file mode 100644
index 0000000..1023f6d
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/model-binding-validation.md
@@ -0,0 +1,71 @@
+# Model Binding & Validation
+
+ASP.NET Core-specific concerns around mapping HTTP requests onto typed arguments and validating them.
+
+## Binding Sources
+
+- Use binding source attributes explicitly: `[FromBody]`, `[FromQuery]`, `[FromRoute]`, `[FromHeader]`, `[FromForm]`, `[FromServices]`.
+- With `[ApiController]`, the framework infers binding sources: complex types default to `[FromBody]`, simple types to `[FromRoute]` / `[FromQuery]`.
+- For minimal APIs, binding is determined by parameter type and route template; use the attributes when inference is ambiguous.
+
+```csharp
+[HttpPost]
+public IActionResult Create(
+    [FromBody] CreateOrderRequest body,
+    [FromHeader(Name = "X-Tenant-Id")] string tenantId,
+    CancellationToken ct)
+{
+    // ...
+}
+```
+
+## Data Annotation Validation
+
+```csharp
+public record CreateOrderRequest(
+    [Required] string CustomerId,
+    [Required, MinLength(1)] List<OrderItemRequest> Items);
+```
+
+- With `[ApiController]`, validation failures automatically produce a `400 Bad Request` with a `ValidationProblemDetails` body.
+- Combine with `[StringLength]`, `[Range]`, `[RegularExpression]`, `[EmailAddress]` for richer constraints.
+
+## FluentValidation
+
+For validation logic that exceeds attribute capabilities (cross-field rules, async lookups), use FluentValidation:
+
+```csharp
+public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
+{
+    public CreateOrderRequestValidator()
+    {
+        RuleFor(x => x.CustomerId).NotEmpty().Length(5, 50);
+        RuleFor(x => x.Items).NotEmpty();
+        RuleForEach(x => x.Items).SetValidator(new OrderItemRequestValidator());
+    }
+}
+
+builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderRequestValidator>();
+```
+
+Wire validators into the pipeline via an `IEndpointFilter` (minimal APIs) or a custom MVC filter that runs `IValidator<T>` and returns `ValidationProblemDetails` on failure.
+
+## ProblemDetails for Validation Errors
+
+`[ApiController]` returns `ValidationProblemDetails` (RFC 9457 extension) automatically. For minimal APIs, return it explicitly:
+
+```csharp
+app.MapPost("/orders", async (CreateOrderRequest req, IValidator<CreateOrderRequest> validator, CancellationToken ct) =>
+{
+    var result = await validator.ValidateAsync(req, ct);
+    if (!result.IsValid)
+        return Results.ValidationProblem(result.ToDictionary());
+
+    // proceed
+    return Results.Created(...);
+});
+```
+
+---
+
+**For DI lifetimes, the Options pattern, and configuration (`appsettings.json`, User Secrets, environment variables): see the [`dotnet-fundamentals`](../../dotnet-fundamentals/SKILL.md) skill.**
diff --git a/.github/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md b/.github/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md
new file mode 100644
index 0000000..374a6ef
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/openapi-and-cross-cutting.md
@@ -0,0 +1,100 @@
+# OpenAPI, Health Checks & Cross-Cutting Concerns
+
+## OpenAPI / Swagger
+
+- Use the built-in OpenAPI support (.NET 9+) or Swashbuckle/NSwag for earlier versions:
+
+```csharp
+builder.Services.AddOpenApi();
+// ...
+app.MapOpenApi();
+```
+
+- Enable XML comments in `.csproj` for automatic documentation:
+  ```xml
+  <PropertyGroup>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+  ```
+- Use `[Tags]`, `[EndpointSummary]`, `[EndpointDescription]` for metadata
+- Use `WithName()` and `WithTags()` on minimal API endpoints
+- Use the `dotnet-xmldocs` skill for writing XML documentation comments
+
+## Health Checks
+
+```csharp
+builder.Services.AddHealthChecks()
+    .AddCheck("self", () => HealthCheckResult.Healthy())
+    .AddNpgSql(connectionString, name: "database")
+    .AddRedis(redisConnectionString, name: "cache");
+
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapHealthChecks("/health/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+```
+
+- Separate liveness (`/health`) and readiness (`/health/ready`) endpoints
+- Tag health checks for selective filtering
+- Use NuGet packages `AspNetCore.HealthChecks.*` for common dependencies
+- Use the `dotnet-nuget-manager` skill for adding health check packages
+
+## CORS
+
+```csharp
+builder.Services.AddCors(options =>
+{
+    options.AddPolicy("AllowFrontend", policy =>
+        policy.WithOrigins("https://app.example.com")
+              .AllowAnyHeader()
+              .AllowAnyMethod()
+              .AllowCredentials());
+});
+
+app.UseCors("AllowFrontend");
+```
+
+## Rate Limiting (.NET 7+)
+
+```csharp
+builder.Services.AddRateLimiter(options =>
+{
+    options.AddFixedWindowLimiter("api", limiter =>
+    {
+        limiter.PermitLimit = 100;
+        limiter.Window = TimeSpan.FromMinutes(1);
+    });
+    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
+});
+
+app.UseRateLimiter();
+```
+
+- Apply per-endpoint with `[EnableRateLimiting("api")]` or `.RequireRateLimiting("api")`
+
+## Output Caching (.NET 7+)
+
+```csharp
+builder.Services.AddOutputCache(options =>
+{
+    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
+    options.AddPolicy("NoCache", builder => builder.NoCache());
+});
+```
+
+## Response Compression
+
+```csharp
+builder.Services.AddResponseCompression(options =>
+{
+    options.EnableForHttps = true;
+    options.Providers.Add<BrotliCompressionProvider>();
+    options.Providers.Add<GzipCompressionProvider>();
+});
+```
diff --git a/.github/skills/dotnet-aspnet/references/project-and-endpoints.md b/.github/skills/dotnet-aspnet/references/project-and-endpoints.md
new file mode 100644
index 0000000..61649e9
--- /dev/null
+++ b/.github/skills/dotnet-aspnet/references/project-and-endpoints.md
@@ -0,0 +1,92 @@
+# Project Structure & Endpoints
+
+## Project Structure
+
+- Organize code by feature/domain, not by layer (avoid generic `Controllers/`, `Services/`, `Models/` folders)
+- Use `Program.cs` as the composition root — register services, configure middleware pipeline
+- Keep `Program.cs` lean by extracting registration into extension methods (e.g., `AddApplicationServices()`, `AddAuthenticationServices()`)
+- Use feature folders:
+  ```
+  Features/
+    Orders/
+      OrdersController.cs
+      CreateOrderRequest.cs
+      OrderResponse.cs
+      OrderService.cs
+    Products/
+      ...
+  ```
+
+## Controllers vs Minimal APIs
+
+### Controllers
+
+Use controllers for larger APIs with shared conventions, filters, and complex routing:
+
+```csharp
+[ApiController]
+[Route("api/[controller]")]
+public class OrdersController(IOrderService orderService) : ControllerBase
+{
+    [HttpGet("{id:guid}")]
+    [ProducesResponseType<OrderResponse>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
+    {
+        var order = await orderService.GetByIdAsync(id, ct);
+        return order is null ? NotFound() : Ok(order);
+    }
+}
+```
+
+- Always use `[ApiController]` attribute — enables automatic model validation, binding source inference, and ProblemDetails responses
+- Use primary constructor injection for dependencies
+- Return `IActionResult` or `ActionResult<T>` for endpoints with multiple response types
+- Accept `CancellationToken` on all async endpoints
+
+### Minimal APIs
+
+Use minimal APIs for simple endpoints, microservices, or when startup performance matters:
+
+```csharp
+var group = app.MapGroup("/api/orders")
+    .WithTags("Orders")
+    .RequireAuthorization();
+
+group.MapGet("/{id:guid}", async (Guid id, IOrderService service, CancellationToken ct) =>
+{
+    var order = await service.GetByIdAsync(id, ct);
+    return order is null ? Results.NotFound() : Results.Ok(order);
+})
+.WithName("GetOrderById")
+.Produces<OrderResponse>()
+.ProducesProblem(StatusCodes.Status404NotFound);
+```
+
+- Use `MapGroup()` to share route prefixes, filters, and metadata
+- Use `TypedResults` instead of `Results` for compile-time response type verification
+- Add `.WithName()` for OpenAPI operation IDs and link generation
+- Use endpoint filters for cross-cutting concerns
+
+## Routing & Endpoints
+
+- Use attribute routing on controllers (`[Route]`, `[HttpGet]`, etc.)
+- Apply route constraints: `{id:guid}`, `{page:int:min(1)}`, `{slug:regex(^[a-z-]+$)}`
+- Use API versioning via URL segment (`/api/v1/orders`) or header-based versioning with `Asp.Versioning.Http`
+- Keep route templates consistent — plural nouns for resources (`/api/orders`, not `/api/order`)
+- Use `LinkGenerator` for generating URLs to named endpoints
+
+## API Conventions & Response Types
+
+- Annotate endpoints with `[ProducesResponseType]` for OpenAPI documentation
+- Use `[Consumes]` and `[Produces]` for content type negotiation
+- Return consistent response envelopes or use ProblemDetails for errors
+- Use `TypedResults` in minimal APIs for compile-time response verification:
+
+```csharp
+group.MapPost("/", async (CreateOrderRequest req, IOrderService service, CancellationToken ct) =>
+{
+    var id = await service.CreateAsync(req, ct);
+    return TypedResults.Created($"/api/orders/{id}", new { id });
+});
+```
diff --git a/.github/skills/dotnet-dev/SKILL.md b/.github/skills/dotnet-dev/SKILL.md
new file mode 100644
index 0000000..db23ff4
--- /dev/null
+++ b/.github/skills/dotnet-dev/SKILL.md
@@ -0,0 +1,312 @@
+---
+name: dotnet-dev
+description: >
+  Use when asked to implement, extend, or change a feature, user story,
+  requirement, or bug fix in a .NET / C# project — any task that produces or
+  modifies C# production code, tests, or documentation. Use when a .NET change
+  request arrives, before writing any code.
+---
+
+# dotnet-dev — Comprehensive C# Requirement Implementation
+
+A strict, gated workflow for implementing requirements end-to-end in .NET / C#.
+Every phase ends in a confirmation gate; every applicable `dotnet-*` skill is a
+mandatory binding. The workflow exists to survive exactly the conditions —
+deadlines, "trivial" framing, "skip the ceremony" — under which it is most
+tempting to abandon.
+
+## Core Principle
+
+**Violating the letter of this workflow is violating its spirit.** The phases,
+gates, point-by-point clarification, and skill bindings are not ceremony to be
+proportioned to task size. They are the work. A one-line endpoint runs the same
+workflow as a subsystem — at speed, never collapsed.
+
+## CRITICAL RULES (read before every phase)
+
+1. **NO COMMITS.** Never run `git commit`, `git add -A`/`.`, branch, tag, or
+   push. The user commits manually. If asked to commit, skip it and say so.
+
+2. **URGENCY AND TRIVIALITY WAIVE NOTHING.** "It's trivial", "I'm in a hurry",
+   "demo in 30 minutes", "skip the clarification dance", "no need for the full
+   process", "just bang it out", "one pass is fine" are NOT permission to skip a
+   phase, a gate, a clarification point, or a skill binding. Acknowledge the
+   deadline, then run the workflow **at speed** — do not shrink it. The only
+   lawful way to reduce a binding's work is an objective `n/a` (see below);
+   user preference, pressure, and perceived size are never valid `n/a` reasons.
+   An explicit, informed user waiver is a different thing from pressure — see
+   *Waiver vs. `n/a` vs. silent skip*.
+
+3. **EVERY PHASE ENDS IN A CONFIRMATION GATE.** At the end of each phase you
+   MUST present a summary and STOP. Do not start the next phase until the user
+   explicitly confirms. **Batching is a violation** — you may not present
+   multiple phases at once, "pre-run" the next phase, or ask for one combined
+   confirmation at the end. One phase → one summary → one wait.
+
+4. **`dotnet-*` SKILLS ARE MANDATORY BINDINGS.** When a binding applies, you
+   MUST invoke that skill via the `Skill` tool, in this conversation, for this
+   task, **before** producing the corresponding artifact. Listing it,
+   paraphrasing it, "knowing it already", or having invoked it for a previous
+   task does NOT count. Invocation must shape the artifact, not certify it
+   afterward.
+
+## Phase Flow
+
+```
+Phase 1: Requirement Review              → GATE
+Phase 2: Clarification (8 points)        → GATE
+Phase 3: Task Breakdown                  → GATE
+Phase 4: Implementation + App Smoke-Check ◄──┐  → GATE
+Phase 5: Code Review (dotnet-reviewer)       │
+   └─ rework needed? ───────────────────────►┘
+   └─ all good → GATE
+Phase 6: Final Summary
+```
+
+## Skill Map — Mandatory Bindings
+
+| Binding | Skill | Applies in | When |
+|---|---|---|---|
+| Core C# / DI / Options / config / modern C# idioms | `dotnet-fundamentals` | Phase 4 | always, for production code |
+| ASP.NET Core (controllers, minimal APIs, middleware, auth, ProblemDetails, OpenAPI) | `dotnet-aspnet` | Phase 4 | when ASP.NET Core is touched |
+| EF Core (DbContext, entities, LINQ, migrations) | `dotnet-ef-core` | Phase 4 | when EF Core is touched |
+| SDK / typed HTTP client generation | `dotnet-sdk-builder` | Phase 4 | when building a typed SDK / client |
+| External / platform / NuGet API surface lookup | `dotnet-inspect` | Phase 1, 4 | when an external/platform API is involved |
+| Tests | `dotnet-tester` | Phase 4 | always, when code is written or changed |
+| XML documentation | `dotnet-xmldocs` | Phase 4 | for any public API addition/change |
+| NuGet packages | `dotnet-nuget-manager` | Phase 4 | any package add/remove/version change |
+| Code review | `dotnet-reviewer` | Phase 5 | always |
+| Router (tie-breaker) | `dotnet` | any | when the right sub-skill is not obvious |
+
+**Correct names matter:** `dotnet-ef-core` and `dotnet-nuget-manager` (not
+`ef-core` / `nuget-manager`). A binding is fulfilled only when its skill has
+fired via the `Skill` tool for this task. A binding applies whether you do the
+work yourself or dispatch a sub-agent — self-execution never waives it, and a
+sub-agent's invocation never waives the main agent's own follow-up edits.
+
+**Tooling:** for code navigation/exploration follow the project + global rules
+(Serena first, then tokensave; built-in/`Explore` agents only in the documented
+carve-outs). Do NOT use `Explore` agents for code research when tokensave is
+available.
+
+---
+
+## Phase 1 — Requirement Review
+
+1. Read the requirement. Extract explicit AND implicit acceptance criteria.
+2. **Find gaps, contradictions, and open questions** — list them explicitly. A
+   review that surfaces no gaps on an ambiguous requirement is a failure; if the
+   requirement truly is unambiguous, say so explicitly rather than skipping.
+3. Analyze scope: affected `*.csproj`, components, files; existing tests/docs.
+4. Read `CLAUDE.md`, `AGENTS.md`, `.editorconfig`, `Directory.Build.props`,
+   `Directory.Packages.props` and follow the conventions found.
+5. Invoke `dotnet-inspect` if any external/platform API surface must be verified.
+6. **Determine the preliminary Skill Map** for this task and show it as a table.
+
+**GATE 1 — STOP.** Present: requirement restated, acceptance criteria,
+gaps/contradictions/open questions, affected scope, and the preliminary Skill
+Map table. Wait for confirmation.
+
+## Phase 2 — Clarification (8 points, one round-trip per point)
+
+Clarify the following **one point at a time** — present point _N_, propose a
+concrete default/assumption, ask the open question, and **wait for the user's
+answer before moving to point _N+1_.** You may NOT batch points into one
+message, NOR skip a point silently. A point that objectively does not apply is
+presented with `n/a — <code-referenced reason>` and still acknowledged.
+
+| # | Item | Must clarify |
+|---|---|---|
+| 1 | Project & folder structure | Target `*.csproj`, namespace, folder layout, new projects yes/no |
+| 2 | Architecture & layering | Layers (controller/service/repo or vertical slice), DI lifetimes, public vs internal surface |
+| 3 | Naming conventions | Type/method/file/namespace names, suffixes (`Service`, `Handler`, `Options`, `Async`), test naming |
+| 4 | Public API / contracts | DTO shape, request/response, ProblemDetails, versioning, OpenAPI annotations |
+| 5 | Errors & edge cases | Exception strategy, Result vs throws, validation style, logging granularity |
+| 6 | Test strategy | Unit and/or integration, mock boundaries, naming, fakes vs real dependencies, coverage expectation |
+| 7 | Persistence / EF Core | Entity shape, migrations yes/no, owned types, indexes, query style (LINQ vs spec) |
+| 8 | Dependencies / NuGet | Allowed/forbidden packages, Central Package Management versions |
+
+**GATE 2 — STOP.** Present: every clarified decision (all 8 points) and the
+**finalized** Skill Map (updated from the answers — e.g. points 7/8 confirm
+`dotnet-ef-core` / `dotnet-nuget-manager`). Wait for confirmation.
+
+## Phase 3 — Task Breakdown
+
+1. Break the requirement into discrete implementation tasks.
+2. Each task covers **production code + tests + documentation**.
+3. **Each task publishes a Skill-prerequisite checklist** (from the Skill Map):
+
+   ```
+   Task #N: <subject>
+     Skill prerequisites:
+       [ ] dotnet-fundamentals
+       [ ] dotnet-aspnet
+       [ ] dotnet-tester
+       [ ] dotnet-xmldocs
+   ```
+
+4. Define dependencies and which tasks may run in parallel via sub-agents.
+
+**GATE 3 — STOP.** Present the task list with per-task checklists, dependency
+order, and parallelization. Wait for confirmation.
+
+## Phase 4 — Implementation + App Smoke-Check
+
+For each task (or parallel group):
+
+1. **Step 0 — invoke every required `dotnet-*` skill for this task** before any
+   `Write`/`Edit`/code-producing `Bash`. One `Skill(...)` call per binding, no
+   collapsing. Re-invoke per task; previous-task invocations do not carry over.
+   Then follow each skill's workflow when producing its artifact.
+2. Implement production code (`dotnet-fundamentals` + stack skill), tests
+   (`dotnet-tester`), XML docs (`dotnet-xmldocs`), package changes
+   (`dotnet-nuget-manager`).
+3. Run `dotnet build` and the test suite. Fix failures.
+4. **App Smoke-Check** — if a runnable application exists, start it and verify
+   it actually runs:
+   - **Applies when** the solution has an executable project (`OutputType=Exe`,
+     ASP.NET Core Web/API, Worker Service). **`n/a` only when** the solution is
+     library-only (no executable project) — state that as the reason.
+   - Start the app **in the background** (a server does not exit on its own),
+     check startup logs / health endpoint / a representative request, then shut
+     it down cleanly. Never block on a foreground long-running process.
+
+**GATE 4 — STOP.** Present implemented tasks, build/test result, and the
+App-Smoke-Check outcome (or its `n/a` reason). Wait for confirmation.
+
+## Phase 5 — Code Review
+
+1. Launch a code-review **sub-agent** that uses `dotnet-reviewer`. Invoke
+   `dotnet-reviewer` via the `Skill` tool in the main conversation **and** pass
+   it to the sub-agent prompt. Inline self-review does NOT satisfy this phase —
+   `dotnet-reviewer` produces a severity-tagged Markdown report under
+   `docs/reviews/`.
+2. Evaluate findings:
+   - **Rework needed** → create new tasks (each with its own Skill checklist)
+     and return to **Phase 4**. After fixing, re-run Phase 5 (rework loop).
+   - **All good** → proceed.
+
+**GATE 5 — STOP.** Present the review findings, the report path, and your
+rework/no-rework decision. Wait for confirmation.
+
+## Phase 6 — Final Summary
+
+1. Files created/modified; what was implemented and why.
+2. Tests added/updated; documentation changes; package changes.
+3. Decisions/trade-offs; anything the user should verify before committing.
+4. **Skill-Invocation Log** (mandatory audit trail — see below).
+5. Reminder: *the user commits; this workflow creates no commits.*
+
+---
+
+## `n/a` Criteria — Strict
+
+A binding or clarification point may be `n/a` **only** when an objective
+technical fact makes the work empty for this task. Valid reasons cite the
+codebase, never the user:
+
+- ✅ `n/a — task touches no public API members (internal sealed class)` — `dotnet-xmldocs`
+- ✅ `n/a — no NuGet package added/removed/version-changed` — `dotnet-nuget-manager`
+- ✅ `n/a — solution is library-only, no executable project` — App Smoke-Check
+- ✅ `n/a — scanned changed files; no DbContext/IQueryable/migration` — `dotnet-ef-core`
+- ❌ NOT valid: `n/a — user said no tests`
+- ❌ NOT valid: `n/a — too small / trivial / one-liner / just a lambda`
+- ❌ NOT valid: `n/a — single ToListAsync, doesn't need the skill`
+- ❌ NOT valid: `n/a — no test project exists` (creating it is part of the task)
+- ❌ NOT valid: `n/a — demo, no time`
+
+If you cannot phrase the reason as "no `<artifact>` exists in this task because
+`<code-referenced fact>`", it is NOT `n/a` — invoke the skill and do the work.
+
+**No avoidance-driven `n/a`.** You may not reshape the implementation to escape
+a binding — e.g. hand-rolling code to dodge `dotnet-nuget-manager`, inlining a
+public member to dodge `dotnet-xmldocs`, or collapsing a service into private
+code to dodge `dotnet-tester`. The binding follows the natural shape of the
+work, not a shape chosen to minimise bindings.
+
+## Waiver vs. `n/a` vs. silent skip
+
+Three distinct cases — keep them apart. Conflating them is how the workflow
+silently collapses.
+
+- **Implicit pressure** — "it's trivial", "I'm in a hurry", "demo in 30
+  minutes", "skip the ceremony", "this is how we work here", "nobody runs all
+  this". **Waives NOTHING.** Acknowledge it and run the full workflow at speed.
+  These are exactly the conditions the workflow exists to survive (CRITICAL
+  RULE 2). Treat them as no-ops on scope.
+
+- **Explicit, informed user waiver** — the user, *after being told what the step
+  protects and what gap skipping it creates*, directly says "skip phase X / the
+  gates / the clarification / the tests / the review." This **may be honored**
+  (your global rule: explicit user instructions take precedence), but only on
+  these terms:
+  1. **State the cost first.** Name what the skipped step would have caught
+     before you skip it. No silent compliance.
+  2. **Record it as a waiver, never as `n/a`.** A waiver means "the user chose
+     to skip this"; `n/a` means "the work is objectively empty." Stamping `n/a`
+     on a waived step makes the audit trail lie about *why* it was skipped.
+     Log it as: `waived — explicit user instruction (<who>, <when>); not a
+     technical n/a; gap: <what is now uncovered>`.
+  3. **Some steps still run regardless.** Invoking the relevant `dotnet-*`
+     skills before writing code costs the user nothing and keeps the code
+     matching repo conventions — keep them even under a waiver.
+
+- **Objective `n/a`** — the work is empty for a code-referenced reason (see
+  `n/a` Criteria). This is the only state that requires no user sign-off.
+
+**The line:** vague urgency is not a waiver. A waiver is the user explicitly
+electing to skip a *named* step after hearing its cost. When in doubt, ask the
+user to confirm the waiver explicitly — do not infer one from pressure.
+
+## Artifact-Substance Bar
+
+Invoking a skill is necessary but not sufficient — the artifact must reflect it:
+
+- A test that asserts nothing about the change (`Assert.True(true)`, a smoke
+  test with no behavioral assertion) does not satisfy `dotnet-tester`.
+- Empty `<summary />` or name-echoing docs do not satisfy `dotnet-xmldocs`.
+- Hand-editing `<PackageReference>` after "invoking" `dotnet-nuget-manager` does
+  not satisfy it — use the `dotnet` CLI as the skill prescribes.
+- A "review" with no `docs/reviews/` report does not satisfy `dotnet-reviewer`.
+
+If an artifact misses the bar, the binding is `[!]`, not `[x]`.
+
+## Skill-Invocation Log (Phase 6)
+
+Reproduce each task's checklist, every entry resolved with evidence:
+
+- `[x] <skill> — invoked at <evidence>` — a verifiable ordered turn (e.g.
+  "before Write of `UsersController.cs`"). "Considered"/"applied" is not
+  evidence. Invocation AFTER the artifact is `[!]`, not `[x]`.
+- `[n/a] <skill> — did not apply (<code-referenced reason>)`.
+- `[!] <skill> — NOT invoked` — a violation. `[!]` is **not a shipping path**:
+  name it, mark the task INCOMPLETE, STOP, and offer to re-enter Phase 4 to run
+  the missing skill's workflow on the artifact. Phase 6 does not complete while
+  any `[!]` is present.
+
+## Red Flags — STOP and run the workflow
+
+| Rationalization | Reality |
+|---|---|
+| "It's trivial / one endpoint — phases & gates are overkill" | Size does not scale the workflow. Run all phases at speed. Gate after each. |
+| "Demo in 30 min / I'm in a hurry — one pass, no gates" | Urgency waives nothing (CRITICAL RULE 2). Acknowledge the deadline, keep the gates. |
+| "Lead waived the clarification dance" | The 8 points are mandatory, one round-trip each. User waiver is not a valid skip. |
+| "Ambiguities aren't blocking — I'll state assumptions instead of asking" | Stating assumptions ≠ clarifying. Present each point and wait for the answer. |
+| "I'll batch all phases / ask one combined confirmation" | Batching is a gate violation. One phase → one summary → one wait. |
+| "This is a single ToListAsync — `dotnet-ef-core` isn't needed" | Touching EF Core triggers the binding regardless of LINQ simplicity. Invoke it. |
+| "Not a public library API, so skip `dotnet-xmldocs`" | `n/a` only for objectively internal members. Public additions/changes go through it. |
+| "User said no tests" | User preference is not a valid `n/a`. Either an objective code-referenced `n/a` exists or `dotnet-tester` is required; if the user insists, name it as a violation and let them decide. |
+| "I'll self-review the diff inline instead of `dotnet-reviewer`" | Phase 5 requires the `dotnet-reviewer` sub-agent + `docs/reviews/` report. Inline self-review does not satisfy it. |
+| "I'll hand-roll it to avoid adding a package" | Avoidance-driven `n/a` is forbidden. The binding follows the natural shape of the work. |
+| "The owner told me to skip it — I'll mark those steps `n/a`" | A waiver is not an `n/a`. Honor an explicit informed waiver if given, but record it as `waived — user instruction`, never `n/a`, never silently. See *Waiver vs. `n/a`*. |
+| "They pushed back / 'nobody does this here' — the workflow is waived" | Pushback, urgency, and social proof are not waivers. Only an explicit, informed skip of a *named* step counts. Vague urgency waives nothing — run at speed. |
+| "I already know C# / the skill — invoking is ceremony" | Skills encode project conventions and modern idioms. Knowing ≠ invoking. Invoke it. |
+| "The skill was invoked last task" | Invocations do not carry over. Re-invoke per task. |
+| "The sub-agent invoked it — covers my own edits" | It does not. Re-invoke before your own follow-up Write/Edit. |
+| "I'll log the `Skill(...)` call even though I ran it after the Write" | Evidence must be a real ordered turn. After-the-fact is `[!]`, not `[x]`. |
+| "No executable project, but I'll skip the App-Smoke-Check check anyway" | Decide it explicitly: run it, or mark `n/a — library-only`. Don't drop it silently. |
+
+---
+
+For detailed per-phase guidance, see
+[references/REFERENCE.md](references/REFERENCE.md).
diff --git a/.github/skills/dotnet-dev/references/REFERENCE.md b/.github/skills/dotnet-dev/references/REFERENCE.md
new file mode 100644
index 0000000..4cd3787
--- /dev/null
+++ b/.github/skills/dotnet-dev/references/REFERENCE.md
@@ -0,0 +1,209 @@
+# dotnet-dev — Detailed Reference
+
+In-depth guidance per phase. Assumes a .NET / C# project. The Skill Map and the
+CRITICAL RULES in `SKILL.md` are authoritative; this document expands the *how*.
+
+---
+
+## Phase 1 — Requirement Review (Detail)
+
+### Goal
+Understand the requirement fully before any code is written, and surface every
+gap before they become rework.
+
+### Steps
+1. **Read the requirement** (issue, story, ticket, message). Identify the core
+   objective and expected outcome.
+2. **Acceptance criteria** — explicit (stated) and implicit (existing tests must
+   still pass, API contracts honored, public additions need XML docs, existing
+   conventions respected).
+3. **Gaps / contradictions / open questions** — write them down. Watch for:
+   - Scope boundaries (what is in / out).
+   - Error-handling behavior (`ProblemDetails`? typed exceptions? Result?).
+   - Backward compatibility (API surface, EF Core migrations).
+   - Target-framework / performance constraints.
+   - Contradictions between the request and existing code/conventions.
+4. **Codebase analysis** — affected `*.csproj`, host type (ASP.NET Core, Worker,
+   Console, MAUI), data layer (EF Core), cross-cutting (DI, Options, Serilog).
+   Locate existing tests (`*.Tests`) and docs. Read `Directory.Build.props`,
+   `Directory.Packages.props`, `.editorconfig`, `nuget.config`. Use Serena /
+   tokensave per project + global tooling rules — not `Explore` agents when
+   tokensave is available.
+5. **`dotnet-inspect`** — invoke whenever an external/platform/NuGet API surface
+   must be verified (types, members, version diffs, extension methods).
+6. **Preliminary Skill Map** — from the requirement, list which bindings the
+   work will touch. It is *preliminary*: persistence (point 7) and dependencies
+   (point 8) are confirmed in Phase 2 and may add `dotnet-ef-core` /
+   `dotnet-nuget-manager`.
+
+### GATE 1 output
+Requirement restated in your words · acceptance criteria · gaps/contradictions/
+open questions · affected scope · preliminary Skill Map table. **Wait.**
+
+---
+
+## Phase 2 — Clarification (Detail)
+
+### Goal
+Resolve the 8 standard implementation dimensions, one at a time, so nothing is
+silently assumed.
+
+### Protocol
+- **One point per message.** Present point _N_: a concrete proposed default,
+  then the open question. Wait for the answer before point _N+1_.
+- **No batching, no skipping.** A point that objectively does not apply is shown
+  with `n/a — <code-referenced reason>` and still acknowledged before moving on.
+- Pre-filling a sensible default is encouraged — it lets the user reply "ok"
+  fast — but the default never replaces the round-trip.
+
+### The 8 points (expanded prompts)
+1. **Project & folder structure** — which `*.csproj`, namespace, folder layout;
+   new projects yes/no.
+2. **Architecture & layering** — controller/service/repo vs vertical slice; DI
+   lifetimes (singleton/scoped/transient); public vs internal surface.
+3. **Naming conventions** — type/method/file/namespace names; suffixes
+   (`Service`, `Handler`, `Options`, `Async`); test naming pattern.
+4. **Public API / contracts** — DTO shape, request/response, `ProblemDetails`,
+   versioning, OpenAPI annotations.
+5. **Errors & edge cases** — exception strategy, Result vs throws, validation
+   style, logging granularity.
+6. **Test strategy** — unit and/or integration, mock boundaries, naming, fakes
+   vs real dependencies, coverage expectation.
+7. **Persistence / EF Core** — entity shape, migrations yes/no, owned types,
+   indexes, query style (LINQ vs spec). Confirms `dotnet-ef-core`.
+8. **Dependencies / NuGet** — allowed/forbidden packages, Central Package
+   Management versions. Confirms `dotnet-nuget-manager`.
+
+### GATE 2 output
+All 8 clarified decisions · the **finalized** Skill Map. **Wait.**
+
+---
+
+## Phase 3 — Task Breakdown (Detail)
+
+### Goal
+A trackable plan of discrete tasks, each self-contained.
+
+### Steps
+- Break into the smallest reasonable tasks; descriptive IDs; enough detail to
+  execute without re-reading the plan.
+- Each task addresses **production code + tests + documentation**.
+- Each task publishes its **Skill-prerequisite checklist** from the Skill Map.
+- Dependencies — common .NET order: entities → EF Core config/migrations →
+  repositories/services → controllers/endpoints; DTOs before consumers; package
+  changes before code using them.
+- Parallelization — group independent tasks for sub-agents; do not parallelize
+  migration/schema work with other EF Core work.
+
+### GATE 3 output
+Task list with per-task checklists · dependency order · parallel groups. **Wait.**
+
+---
+
+## Phase 4 — Implementation + App Smoke-Check (Detail)
+
+### Step 0 — Skill invocation (per task)
+Before any `Write`/`Edit`/code-producing `Bash` for the task, invoke each
+required binding once via the `Skill` tool. A task touching code + tests + docs
+is at least three calls (`dotnet-fundamentals` + `dotnet-tester` +
+`dotnet-xmldocs`) plus stack skills and `dotnet-nuget-manager` if packages
+change. Wait for each skill's content; follow its workflow when producing the
+artifact. Sub-agent dispatch is in addition to Step 0, not a substitute — pass
+the skills explicitly to the sub-agent (sub-agents are stateless).
+
+### Production code
+`dotnet-fundamentals` always; plus `dotnet-aspnet` (web), `dotnet-ef-core` (EF),
+`dotnet-sdk-builder` (typed SDK/HTTP client), `dotnet-inspect` (verify external
+API). Apply project conventions: `Ensure.*` guards, primary constructors,
+nullable reference types, `CancellationToken` propagation, `.ConfigureAwait(false)`
+in library code (not in tests), never `.Result`/`.Wait()`/`.GetAwaiter().GetResult()`.
+
+### Tests
+`dotnet-tester` always when code is written/changed — xUnit + FakeItEasy +
+AwesomeAssertions, plus its second-agent missing-case pass. Cover new/changed
+behavior and the edge cases from Phase 1.
+
+### Documentation
+`dotnet-xmldocs` for every public API addition/change.
+
+### Build & dependencies
+`dotnet-nuget-manager` for any package add/remove/version change (enforces the
+`dotnet` CLI and `Directory.Packages.props`). Then `dotnet build` + `dotnet test`;
+fix failures before the gate.
+
+### App Smoke-Check
+- **Applies** when an executable project exists (`OutputType=Exe`, ASP.NET Core
+  Web/API, Worker Service). **`n/a`** only when library-only.
+- Start in the **background** (servers do not self-exit). Verify startup logs /
+  health endpoint / one representative request. Shut down cleanly. Never block
+  on a foreground long-running process.
+
+### GATE 4 output
+Implemented tasks · build/test result · App-Smoke-Check outcome (or `n/a`
+reason). **Wait.**
+
+---
+
+## Phase 5 — Code Review (Detail)
+
+### Steps
+- Launch a code-review **sub-agent** instructed to invoke `dotnet-reviewer`;
+  also invoke `dotnet-reviewer` in the main conversation. The skill reviews
+  working-tree or branch-vs-`main` changes and writes a severity-tagged Markdown
+  report under `docs/reviews/`.
+- Review covers: correctness/completeness vs requirement, test coverage, doc
+  accuracy, code quality/bugs/security, .NET idioms, convention consistency.
+
+### Evaluate findings
+- **No / minor issues** → fix directly (still invoking the required skills
+  before edits), then gate.
+- **Significant issues** → new tasks (each with its Skill checklist) → return to
+  Phase 4 → re-run Phase 5. If the same issue recurs after 2 cycles, consult the
+  user.
+
+### GATE 5 output
+Findings · report path · rework/no-rework decision. **Wait.**
+
+---
+
+## Phase 6 — Final Summary (Detail)
+
+1. **Requirement** restated briefly.
+2. **Files** created/modified.
+3. **Implementation details** and key design decisions.
+4. **Tests** added/updated and what they cover.
+5. **Documentation** changes (XML docs, READMEs).
+6. **Package changes** (cross-reference `Directory.Packages.props`).
+7. **Decisions / trade-offs.**
+8. **Review notes** — key `dotnet-reviewer` points + report link.
+9. **Things to check** before committing.
+10. **Skill-Invocation Log** — every task's checklist resolved to `[x]`/`[n/a]`/
+    `[!]` with evidence (see `SKILL.md`). Mandatory even when all bindings were
+    correct — it is the audit trail.
+
+End with: *All changes are ready for your review. Commit them yourself when
+satisfied — this workflow creates no commits.*
+
+---
+
+## General Guidelines
+
+### Sub-agents
+- Provide complete context (stateless). Pass the relevant `dotnet-*` skills in
+  the prompt. Use a build/test runner for `dotnet build`/`dotnet test`. Prefer
+  small focused tasks; launch independent tasks in parallel.
+- For code research, follow the project + global tooling rules (Serena →
+  tokensave → built-in; no `Explore` agents when tokensave is available).
+
+### Git
+- NEVER `git commit`, `git add -A`/`.`, branch, tag, or push. Read-only git
+  (`diff`/`status`/`log`) is fine. Stage by name only when explicitly asked;
+  refuse secret-like files (`.env`, `credentials.json`, `*.pem`).
+- If a commit is requested, skip it: *"Committing is your responsibility."*
+
+### Project conventions
+- Honor `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`,
+  `.editorconfig`, `Directory.Build.props`, `Directory.Packages.props`.
+- `Ensure.NotNull(...)` / `Ensure.IsNotNullOrEmpty(...)` /
+  `Ensure.IsNotNullOrWhitespace(...)` from `CreativeCoders.Core` for argument
+  guards in libraries.
diff --git a/.github/skills/dotnet-ef-core/SKILL.md b/.github/skills/dotnet-ef-core/SKILL.md
new file mode 100644
index 0000000..10ba55d
--- /dev/null
+++ b/.github/skills/dotnet-ef-core/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: dotnet-ef-core
+description: Applies Entity Framework Core best practices for .NET projects. Use when designing DbContext, creating entities or relationships, writing LINQ queries, managing migrations, implementing repository patterns, or troubleshooting N+1 queries and performance issues with EF Core.
+---
+
+# Entity Framework Core Best Practices
+
+## When to Use
+
+- Designing or restructuring a `DbContext`, entities, or relationships
+- Writing LINQ queries against EF Core, or troubleshooting N+1 / performance issues
+- Creating, naming, or reviewing EF Core migrations
+- Implementing concurrency control, repository patterns, or change tracking strategies
+- Setting up EF Core tests with SQLite in-memory or Testcontainers
+
+## Data Context Design
+
+- Keep DbContext classes focused and cohesive
+- Use constructor injection for configuration options
+- Override OnModelCreating for fluent API configuration
+- Separate entity configurations using IEntityTypeConfiguration
+- Consider using DbContextFactory pattern for console apps or tests
+
+## Entity Design
+
+- Use meaningful primary keys (consider natural vs surrogate keys)
+- Implement proper relationships (one-to-one, one-to-many, many-to-many)
+- Use data annotations or fluent API for constraints and validations
+- Implement appropriate navigational properties
+- Consider using owned entity types for value objects
+
+## Performance
+
+- Use AsNoTracking() for read-only queries
+- Implement pagination for large result sets with Skip() and Take()
+- Use Include() to eager load related entities when needed
+- Consider projection (Select) to retrieve only required fields
+- Use compiled queries for frequently executed queries
+- Avoid N+1 query problems by properly including related data
+
+## Migrations
+
+- Create small, focused migrations
+- Name migrations descriptively
+- Verify migration SQL scripts before applying to production
+- Consider using migration bundles for deployment
+- Add data seeding through migrations when appropriate
+
+## Querying
+
+- Use IQueryable judiciously and understand when queries execute
+- Prefer strongly-typed LINQ queries over raw SQL
+- Use appropriate query operators (Where, OrderBy, GroupBy)
+- Consider database functions for complex operations
+- Implement specifications pattern for reusable queries
+
+## Change Tracking & Saving
+
+- Use appropriate change tracking strategies
+- Batch your SaveChanges() calls
+- Implement concurrency control for multi-user scenarios (see below)
+- Consider using transactions for multiple operations
+- Use appropriate DbContext lifetimes (scoped for web apps)
+
+### Concurrency Control
+
+See [concurrency-control.md](./references/concurrency-control.md) for `[Timestamp]`, `[ConcurrencyCheck]`, fluent API configuration, and `DbUpdateConcurrencyException` handling patterns.
+
+## Security
+
+- Use parameterized queries to prevent SQL injection
+- Implement appropriate data access permissions
+- Be careful with raw SQL queries
+- Consider data encryption for sensitive information
+- Use migrations to manage database user permissions
+
+## Testing
+
+- Avoid the EF Core In-Memory provider for tests — it does not enforce constraints, referential integrity, or transactions, so tests can pass while real database behavior fails
+- Use **SQLite in-memory mode** for lightweight unit and integration tests that need realistic SQL semantics:
+  ```csharp
+  var connection = new SqliteConnection("DataSource=:memory:");
+  connection.Open();
+  var options = new DbContextOptionsBuilder<AppDbContext>()
+      .UseSqlite(connection)
+      .Options;
+  ```
+- Use **Testcontainers** for integration tests that must match production database behavior (e.g., PostgreSQL, SQL Server):
+  ```csharp
+  var container = new PostgreSqlBuilder().Build();
+  await container.StartAsync();
+  var options = new DbContextOptionsBuilder<AppDbContext>()
+      .UseNpgsql(container.GetConnectionString())
+      .Options;
+  ```
+- Mock DbContext and DbSet only for pure unit tests that do not execute queries
+- Test migrations in isolated environments
+- Consider snapshot testing for model changes
+- Use the `dotnet-tester` skill for generating unit and integration tests after schema changes
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — DI lifetimes for `DbContext`, Options pattern for connection strings, modern C# idioms used in entity types
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Generates DbContext-backed unit and integration tests (SQLite in-memory, Testcontainers)
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Wires EF Core into ASP.NET Core via DI (scoped DbContext lifetimes)
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Reviews EF Core data-access code for performance and security issues
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Adds EF Core providers, Testcontainers, and SQLite packages
diff --git a/.github/skills/dotnet-ef-core/references/concurrency-control.md b/.github/skills/dotnet-ef-core/references/concurrency-control.md
new file mode 100644
index 0000000..5720098
--- /dev/null
+++ b/.github/skills/dotnet-ef-core/references/concurrency-control.md
@@ -0,0 +1,52 @@
+# Concurrency Control
+
+Use `[Timestamp]` for automatic row-version concurrency (SQL Server / PostgreSQL with `rowversion` or `xmin`):
+
+```csharp
+public class Order
+{
+    public int Id { get; set; }
+    public string Status { get; set; } = string.Empty;
+
+    [Timestamp]
+    public byte[] RowVersion { get; set; } = [];
+}
+```
+
+Use `[ConcurrencyCheck]` to protect individual properties without a row version column:
+
+```csharp
+public class Product
+{
+    public int Id { get; set; }
+
+    [ConcurrencyCheck]
+    public decimal Price { get; set; }
+}
+```
+
+Or configure via fluent API:
+
+```csharp
+modelBuilder.Entity<Order>()
+    .Property(o => o.RowVersion)
+    .IsRowVersion();
+
+modelBuilder.Entity<Product>()
+    .Property(p => p.Price)
+    .IsConcurrencyToken();
+```
+
+Catch `DbUpdateConcurrencyException` at the call site and implement a retry or conflict-resolution strategy:
+
+```csharp
+try
+{
+    await context.SaveChangesAsync();
+}
+catch (DbUpdateConcurrencyException ex)
+{
+    // Reload the entity and resolve the conflict, or inform the user
+    await ex.Entries.Single().ReloadAsync();
+}
+```
diff --git a/.github/skills/dotnet-fundamentals/SKILL.md b/.github/skills/dotnet-fundamentals/SKILL.md
new file mode 100644
index 0000000..3a643cd
--- /dev/null
+++ b/.github/skills/dotnet-fundamentals/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: dotnet-fundamentals
+description: Applies modern .NET fundamentals — dependency injection, Options pattern, configuration, and modern C# idioms. Use when registering services in any .NET host (ASP.NET Core, Worker Service, Console, MAUI), binding configuration with IOptions<T>, choosing DI lifetimes, configuring appsettings.json / User Secrets / environment variables, or applying primary constructors, required properties, nullable reference types, and CancellationToken propagation.
+---
+
+# Modern .NET Fundamentals
+
+## When to Use
+
+- Working with .NET/C# Code
+- Registering services in any `IServiceCollection` (ASP.NET Core, Worker Service, Console app, MAUI, library DI extension methods)
+- Choosing a DI lifetime (Transient, Scoped, Singleton) or registering keyed services (.NET 8+)
+- Binding configuration sections to a strongly-typed Options class
+- Setting up `appsettings.json`, environment-specific overrides, User Secrets, or environment variables
+- Adopting primary constructors, `required` properties, nullable reference types, or `CancellationToken` propagation in new code
+
+## Core Principles
+
+- This skill is **technology-agnostic across .NET hosts**. ASP.NET Core, EF Core, and SDK builders all sit on top of these fundamentals.
+- **Interface-first registration** — register services via their abstraction (`AddScoped<IFoo, Foo>()`), not the concrete type. Enables substitution and testing.
+- **No service locator** — never inject `IServiceProvider` into business logic. Constructor-inject the dependencies you actually need.
+- **Options over constructor parameters for configuration** — bind config sections to `IOptions<T>`, do not pass raw `IConfiguration` values around.
+- **Fail fast** — use `ValidateDataAnnotations().ValidateOnStart()` so misconfiguration surfaces at startup, not at first use.
+- **Immutable configuration** — Options classes use `required` properties and `init`-only setters.
+- **Cancellation flows everywhere** — every async method takes a `CancellationToken` with default as its last parameter and forwards it.
+
+## Reference Index
+
+- **[dependency-injection.md](references/dependency-injection.md)** — `IServiceCollection` registration, lifetimes, keyed services, interface-based registration, anti-service-locator
+- **[options-pattern.md](references/options-pattern.md)** — `IOptions<T>` vs `IOptionsMonitor<T>` vs `IOptionsSnapshot<T>`, `BindConfiguration`, `ValidateDataAnnotations`, `ValidateOnStart`
+- **[configuration.md](references/configuration.md)** — `appsettings.json` and environment overrides, User Secrets, environment variables, production secret stores
+- **[modern-patterns.md](references/modern-patterns.md)** — primary constructors, `required` / `init`-only properties, nullable reference types, `CancellationToken` propagation
+
+## Related Skills
+
+- **dotnet-aspnet** — Builds the HTTP layer (controllers, minimal APIs, middleware, routing, auth, ProblemDetails) on an ASP.NET Core host
+- **dotnet-sdk-builder** — Generates .NET SDK / client libraries (DI extension methods, typed HTTP clients, typed Options, typed exceptions)
+- **dotnet-ef-core** — Entity Framework Core data access (DbContext, entities, LINQ, migrations); registered via DI and configured via Options
+- **dotnet-reviewer** — Structured .NET code review producing a severity-tagged Markdown report
+- **dotnet-tester** — Writes and runs C#/.NET unit tests (xUnit, FakeItEasy, AwesomeAssertions) and identifies missing test cases
+- **dotnet-nuget-manager** — Use whenever NuGet packages are added, removed, or updated in a project (dotnet CLI, central version management, version verification)
diff --git a/.github/skills/dotnet-fundamentals/references/configuration.md b/.github/skills/dotnet-fundamentals/references/configuration.md
new file mode 100644
index 0000000..8a4c529
--- /dev/null
+++ b/.github/skills/dotnet-fundamentals/references/configuration.md
@@ -0,0 +1,79 @@
+# Configuration
+
+Configuration in .NET is layered — later sources override earlier ones. The default `HostApplicationBuilder` order is:
+
+1. `appsettings.json`
+2. `appsettings.{Environment}.json` (e.g. `appsettings.Development.json`)
+3. User Secrets (Development only)
+4. Environment variables
+5. Command-line arguments
+
+The first source that supplies a key wins for that key; sources don't merge sections deeply, they override per leaf value.
+
+## `appsettings.json`
+
+Use for defaults that ship with the application:
+
+```json
+{
+  "Smtp": {
+    "Host": "smtp.example.com",
+    "Port": 587
+  },
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information"
+    }
+  }
+}
+```
+
+Use `appsettings.{Environment}.json` for environment-specific overrides:
+
+```json
+// appsettings.Development.json
+{
+  "Smtp": { "Host": "localhost" }
+}
+```
+
+The active environment is set via `DOTNET_ENVIRONMENT` (generic host) or `ASPNETCORE_ENVIRONMENT` (ASP.NET Core).
+
+## User Secrets
+
+For local development secrets, never commit them. Initialize once per project:
+
+```bash
+dotnet user-secrets init
+dotnet user-secrets set "Smtp:Password" "dev-password"
+```
+
+User Secrets are stored outside the project directory (in `~/.microsoft/usersecrets/<UserSecretsId>/secrets.json`) and are only loaded in the Development environment.
+
+## Environment Variables
+
+Use for production secrets and container/Kubernetes deployments. Nested keys use `__` (double underscore) as separator:
+
+```bash
+export Smtp__Host=smtp.prod.example.com
+export Smtp__Password=$(cat /run/secrets/smtp-password)
+```
+
+The `__` separator is portable (works on Linux, macOS, Windows). `:` is also accepted but is not valid in environment variable names on Linux.
+
+## Production Secret Stores
+
+For production, integrate a real secret store rather than environment variables when secrets need rotation, auditing, or RBAC:
+
+- **Azure Key Vault** — `AddAzureKeyVault(...)` from `Azure.Extensions.AspNetCore.Configuration.Secrets`
+- **AWS Secrets Manager** — via `AWSSDK.Extensions.NETCore.Setup`
+- **HashiCorp Vault** — via `VaultSharp` plus a custom configuration provider
+
+These plug into the same `IConfiguration` pipeline, so consuming code keeps using `IOptions<T>` — only the registration in `Program.cs` differs.
+
+## Anti-Patterns
+
+- **Hard-coded secrets** — never commit a real password, API key, or connection string to source control. Local defaults should point at obviously-fake values.
+- **`IConfiguration` injected into business logic** — bind to a typed Options class instead. Business logic should never know about configuration providers.
+- **`config["Foo:Bar"]` indexing across the codebase** — magic strings + no validation. Bind once, inject `IOptions<T>`.
+- **Per-environment code branching** — if behavior differs between Development and Production, model it as configuration, not as `if (env.IsDevelopment())` branches scattered through services.
diff --git a/.github/skills/dotnet-fundamentals/references/dependency-injection.md b/.github/skills/dotnet-fundamentals/references/dependency-injection.md
new file mode 100644
index 0000000..330f0b8
--- /dev/null
+++ b/.github/skills/dotnet-fundamentals/references/dependency-injection.md
@@ -0,0 +1,81 @@
+# Dependency Injection
+
+## Registration
+
+Register services on the host's `IServiceCollection`. The same API applies to ASP.NET Core (`builder.Services`), Worker Services, Console apps using `HostApplicationBuilder`, and library extension methods (`public static IServiceCollection AddMyFeature(this IServiceCollection services)`).
+
+```csharp
+services.AddScoped<IOrderService, OrderService>();
+services.AddSingleton<IClock, SystemClock>();
+services.AddTransient<IEmailFormatter, EmailFormatter>();
+```
+
+- Register services in `Program.cs` or via extension methods (`AddApplicationServices()`, `AddPersistence()`, etc.) to keep `Program.cs` lean.
+- Prefer interface-based registration for testability — register against the abstraction, not the concrete type.
+
+## Lifetimes
+
+- **Transient** — Stateless, lightweight services. New instance per resolution.
+- **Scoped** — One instance per logical operation (per HTTP request in ASP.NET Core, per `IServiceScope` in worker scenarios). Typical for `DbContext`, unit-of-work, and per-request caches.
+- **Singleton** — Thread-safe shared state (caches, configuration providers, expensive-to-build clients). Must be safe for concurrent use.
+
+Lifetime mismatches (e.g. a Singleton capturing a Scoped service) are a common bug — `ValidateScopes` and `ValidateOnBuild` catch this at startup.
+
+```csharp
+var host = Host.CreateApplicationBuilder()
+    .ConfigureContainer<IServiceCollection>((ctx, services) =>
+    {
+        // Register here
+    })
+    .Build();
+```
+
+For ASP.NET Core, scope validation is on by default in Development. For other hosts, enable it explicitly via `ServiceProviderOptions`.
+
+## Keyed Services (.NET 8+)
+
+Use keyed services when multiple implementations of the same interface need to coexist and be selected by key:
+
+```csharp
+services.AddKeyedScoped<IPaymentGateway, StripeGateway>("stripe");
+services.AddKeyedScoped<IPaymentGateway, PayPalGateway>("paypal");
+
+public class CheckoutHandler(
+    [FromKeyedServices("stripe")] IPaymentGateway stripe,
+    [FromKeyedServices("paypal")] IPaymentGateway paypal)
+{
+    // ...
+}
+```
+
+## Anti-Patterns
+
+- **Service locator** — Do not inject `IServiceProvider` into business logic and resolve dependencies at runtime. Constructor-inject the specific dependencies you need.
+- **Capturing scoped services in singletons** — A singleton holding a reference to a scoped service leaks the scoped instance and causes use-after-dispose bugs. Use `IServiceScopeFactory` to create a fresh scope when needed.
+- **Concrete-type registration when an interface exists** — Registering `services.AddScoped<OrderService>()` instead of `services.AddScoped<IOrderService, OrderService>()` defeats substitution and testing.
+- **Static state / singletons outside DI** — All cross-cutting state goes through DI. No `public static` mutable state.
+
+## Library Extension Method Pattern
+
+When shipping a NuGet library that registers services for consumers, expose a single extension method:
+
+```csharp
+public static class MyFeatureServiceCollectionExtensions
+{
+    public static IServiceCollection AddMyFeature(
+        this IServiceCollection services,
+        Action<MyFeatureOptions>? configure = null)
+    {
+        services.AddOptions<MyFeatureOptions>()
+            .BindConfiguration(MyFeatureOptions.SectionName)
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        if (configure is not null)
+            services.Configure(configure);
+
+        services.AddScoped<IMyFeatureService, MyFeatureService>();
+        return services;
+    }
+}
+```
diff --git a/.github/skills/dotnet-fundamentals/references/modern-patterns.md b/.github/skills/dotnet-fundamentals/references/modern-patterns.md
new file mode 100644
index 0000000..c8f3e04
--- /dev/null
+++ b/.github/skills/dotnet-fundamentals/references/modern-patterns.md
@@ -0,0 +1,87 @@
+# Modern C# / .NET Patterns
+
+Conventions for code written against current .NET. Use these consistently in new code; match existing project style if it predates these features.
+
+## Primary Constructors (C# 12)
+
+- For middleware, inject scoped services via `InvokeAsync` parameters, not the primary constructor.
+
+## `required` Properties + `init`-Only Setters
+
+Force callers to supply mandatory values at object initialization; prevent mutation afterward.
+
+```csharp
+public record CreateOrderRequest
+{
+    public required string CustomerId { get; init; }
+    public required IReadOnlyList<OrderItem> Items { get; init; }
+    public string? Notes { get; init; }
+}
+
+var req = new CreateOrderRequest
+{
+    CustomerId = "C-123",
+    Items = items,
+};
+```
+
+- Combine with `record` for value-semantics DTOs.
+- `required` runs at compile time — the compiler refuses initialization expressions that omit a required member.
+- Use `init` (not `set`) for immutable-after-construction shape.
+
+## Nullable Reference Types
+
+Enable project-wide in the `.csproj`:
+
+```xml
+<Nullable>enable</Nullable>
+```
+
+- Declare a reference type as nullable explicitly: `string?` means "may be null", `string` means "guaranteed non-null".
+- Treat nullable warnings as errors (`<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`) in new projects.
+- For legacy code being migrated, use `<Nullable>annotations</Nullable>` first (annotations only, no warnings) to add types incrementally, then flip to `enable`.
+- Use the null-forgiving `!` operator only at provable-non-null boundaries (post-validation, after `ArgumentNullException.ThrowIfNull`). Do not sprinkle it to silence warnings.
+
+## `CancellationToken` Propagation
+
+Every async method takes a `CancellationToken` as its **last** parameter and forwards it to every async call it makes.
+
+```csharp
+public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
+{
+    var dto = await _db.Orders
+        .AsNoTracking()
+        .FirstOrDefaultAsync(o => o.Id == id, ct);
+    return dto is null ? null : await _mapper.MapAsync(dto, ct);
+}
+```
+
+- Parameter is named `ct` or `cancellationToken` consistently within a codebase.
+- Default to `default` only for entry points that have no caller-supplied token (e.g. CLI `Main`); library code should require the caller to pass one.
+- In ASP.NET Core, `HttpContext.RequestAborted` is automatically bound to action parameters of type `CancellationToken`.
+- Never swallow `OperationCanceledException` — let it bubble. The host treats it as expected cancellation.
+
+## File-Scoped Namespaces (C# 10)
+
+```csharp
+namespace MyCompany.MyProduct.Orders;
+
+public class OrderService { /* ... */ }
+```
+
+Default for all new files. Removes one level of indentation across the file.
+
+## `global using` Directives
+
+Centralize common imports in `GlobalUsings.cs`:
+
+```csharp
+global using System;
+global using System.Collections.Generic;
+global using System.Threading;
+global using System.Threading.Tasks;
+global using Microsoft.Extensions.DependencyInjection;
+global using Microsoft.Extensions.Options;
+```
+
+Use the SDK-provided `<ImplicitUsings>enable</ImplicitUsings>` for the default set; add project-specific globals via explicit `global using` declarations.
diff --git a/.github/skills/dotnet-fundamentals/references/options-pattern.md b/.github/skills/dotnet-fundamentals/references/options-pattern.md
new file mode 100644
index 0000000..74256cc
--- /dev/null
+++ b/.github/skills/dotnet-fundamentals/references/options-pattern.md
@@ -0,0 +1,89 @@
+# Options Pattern
+
+Bind configuration sections to strongly-typed classes via `Microsoft.Extensions.Options`. Validate at startup, inject by interface (`IOptions<T>` / `IOptionsMonitor<T>` / `IOptionsSnapshot<T>`).
+
+## Defining an Options Class
+
+```csharp
+public class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public required string Host { get; init; }
+    public int Port { get; init; } = 587;
+    public required string Username { get; init; }
+    public required string Password { get; init; }
+}
+```
+
+- Declare `SectionName` as a `const string` on the class so consumers and tests can refer to it without magic strings.
+- Use `required` properties for values without sane defaults — binding fails clearly if a required value is missing.
+- Use `init`-only setters to keep options immutable after binding.
+
+## Registration
+
+```csharp
+services.AddOptions<SmtpOptions>()
+    .BindConfiguration(SmtpOptions.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+- `BindConfiguration("Smtp")` binds the section automatically and re-binds when configuration reloads.
+- `ValidateDataAnnotations()` runs `[Required]`, `[Range]`, etc. on the options class.
+- `ValidateOnStart()` runs validation at host startup — misconfiguration surfaces immediately instead of at first use.
+
+For complex validation, implement `IValidateOptions<T>`:
+
+```csharp
+public class SmtpOptionsValidator : IValidateOptions<SmtpOptions>
+{
+    public ValidateOptionsResult Validate(string? name, SmtpOptions options)
+    {
+        if (options.Port is < 1 or > 65535)
+            return ValidateOptionsResult.Fail("Port must be 1-65535");
+        return ValidateOptionsResult.Success;
+    }
+}
+
+services.AddSingleton<IValidateOptions<SmtpOptions>, SmtpOptionsValidator>();
+```
+
+## Consuming Options
+
+| Interface | Lifetime | When to use |
+|---|---|---|
+| `IOptions<T>` | Singleton | Static configuration that does not change after startup. Cheapest. |
+| `IOptionsSnapshot<T>` | Scoped (ASP.NET Core only) | Per-request rebinding — picks up changes for each new request. |
+| `IOptionsMonitor<T>` | Singleton with change notifications | Long-lived components (background services, HTTP clients) that need to react to reloads via `OnChange`. |
+
+```csharp
+public class EmailSender(IOptions<SmtpOptions> options)
+{
+    private readonly SmtpOptions _smtp = options.Value;
+    // ...
+}
+
+public class ReloadableEmailSender(IOptionsMonitor<SmtpOptions> monitor)
+{
+    public ReloadableEmailSender(IOptionsMonitor<SmtpOptions> monitor)
+    {
+        monitor.OnChange(opts => RebuildClient(opts));
+    }
+}
+```
+
+## Named Options
+
+When the same options shape exists multiple times (e.g. multiple SMTP backends):
+
+```csharp
+services.Configure<SmtpOptions>("Primary", config.GetSection("Smtp:Primary"));
+services.Configure<SmtpOptions>("Fallback", config.GetSection("Smtp:Fallback"));
+
+public class Mailer(IOptionsMonitor<SmtpOptions> monitor)
+{
+    private readonly SmtpOptions _primary = monitor.Get("Primary");
+    private readonly SmtpOptions _fallback = monitor.Get("Fallback");
+}
+```
diff --git a/.github/skills/dotnet-inspect/SKILL.md b/.github/skills/dotnet-inspect/SKILL.md
new file mode 100644
index 0000000..699076c
--- /dev/null
+++ b/.github/skills/dotnet-inspect/SKILL.md
@@ -0,0 +1,235 @@
+---
+name: dotnet-inspect
+description: Query .NET APIs across NuGet packages, platform libraries, and local files. Search for types, list API surfaces, compare and diff versions, find extension methods and implementors. Use whenever you need to answer questions about .NET library contents.
+---
+
+# dotnet-inspect
+
+Query .NET library APIs — the same commands work across NuGet packages, platform libraries (System.*, Microsoft.AspNetCore.*), and local .dll/.nupkg files.
+
+## Quick Decision Tree
+
+- **Code broken?** → `diff --package Foo@old..new` first, then `member`
+- **What's new in a .NET preview?** → `diff --platform System.Runtime@P2..P3 --additive` per framework library
+- **What types exist?** → `type --package Foo` (discover types in a package or library)
+- **What members does a type have?** → `member Type --package Foo` (compact table by default)
+- **What does a type look like?** → `type Type --package Foo` (tree view for single type)
+- **What are the method signatures?** → `member Type --package Foo -m Method` (full signatures + docs)
+- **What is the source/IL?** → `member Type --package Foo -m Method:1 -v:d` (Source, Lowered C#, IL)
+- **Where is the source code?** → `source Type --package Foo` (SourceLink URLs), `source Type -m Member` (with line numbers)
+- **Want raw source content?** → `source Type --package Foo --cat` (fetches and prints source files)
+- **What constructors exist?** → `member 'Type<T>' --package Foo -m .ctor` (use `<T>` not `<>`)
+- **How many overloads?** → `member Type --package Foo --show-index` (shows `Name:N` indices)
+- **What does this package depend on?** → `depends --package Foo`
+- **What does this type inherit?** → `depends 'INumber<TSelf>'`
+- **Want a dependency diagram?** → `depends --mermaid` (standalone) or `depends --markdown --mermaid` (embedded)
+- **What metadata fields exist?** → `-S Section --fields "PDB*"` (structured query, no DSL)
+- **What version is available?** → `Foo --version` (cache-first), `Foo --latest-version` (always NuGet), `Foo --versions` (list all)
+
+## When to Use This Skill
+
+- **"What types are in this package?"** — `type` discovers types, `find` searches by pattern
+- **"What members does this type have?"** — `member` for methods/properties/events (docs on by default)
+- **"What changed between versions?"** — `diff` classifies breaking/additive changes
+- **"What new APIs shipped in this preview?"** — `diff --platform System.Runtime@prev..current --additive` per framework library
+- **"This code uses an old API — fix it"** — `diff` the old..new version, then `member` to see the new API
+- **"What extends this type?"** — `extensions` finds extension methods/properties (`--reachable` for transitive)
+- **"What implements this interface?"** — `implements` finds concrete types
+- **"What does this type depend on?"** — `depends` walks type hierarchy, package deps, or library refs
+- **"Show dependencies as a diagram"** — `depends --mermaid` for standalone mermaid, `--markdown --mermaid` for embedded
+- **"Where is the source code?"** — `source` returns SourceLink URLs; add member name for line numbers
+- **"What version/metadata does this have?"** — `package` and `library` inspect metadata
+- **"What version is available?"** — `Foo --version` (fast, cache-first — like `docker run`)
+- **"What's the latest on NuGet?"** — `Foo --latest-version` (always queries NuGet — like `docker pull`)
+- **"What versions exist?"** — `Foo --versions` (list all published versions)
+- **"What TFMs are available?"** — `package Foo --tfms`, then `type --package Foo --tfm net8.0`
+- **"Where is the source code?"** — `source` returns SourceLink URLs; add member name for line numbers
+- **"Show me the actual source?"** — `source Type --package Foo --cat` fetches and prints source file contents
+- **"Show me something cool"** — `demo` runs curated showcase queries
+
+## Key Patterns
+
+Default output is **markdown** — headings, tables, and field lists that render well in terminals, editors, and LLM contexts. No flags needed:
+
+```bash
+dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json    # scan members
+dnx dotnet-inspect -y -- type --package System.Text.Json                     # scan types
+dnx dotnet-inspect -y -- diff --package System.CommandLine@2.0.0-beta4.22272.1..2.0.3  # triage changes
+```
+
+Default format is **markdown** — no flags needed. Optional formats: **oneline** (`--oneline`), **plaintext** (`--plaintext`), **json** (`--json`), **mermaid** (`--mermaid`). Verbosity (`-v:q/m/n/d`) controls which sections are included; formatter controls how they render. They compose freely — except `--oneline` and `-v` cannot be combined.
+
+```bash
+dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -v:d  # detailed (source/IL)
+dnx dotnet-inspect -y -- System.Text.Json -v:n --plaintext                      # all local sections, plaintext
+dnx dotnet-inspect -y -- type --package System.Text.Json --oneline              # compact columnar output
+dnx dotnet-inspect -y -- depends Stream --mermaid                               # standalone mermaid diagram
+dnx dotnet-inspect -y -- depends Stream --markdown --mermaid                    # mermaid embedded in markdown
+```
+
+Use `diff` first when fixing broken code — triage changes, then drill into specifics:
+
+```bash
+dnx dotnet-inspect -y -- diff --package System.CommandLine@2.0.0-beta4.22272.1..2.0.3  # what changed?
+dnx dotnet-inspect -y -- member Command --package System.CommandLine@2.0.3               # new API surface
+```
+
+## Platform Diffs & Release Notes
+
+For framework libraries (System.*, Microsoft.AspNetCore.*), use `--platform` instead of `--package`. This is the primary workflow for .NET release notes — diff each framework library between preview versions:
+
+```bash
+dnx dotnet-inspect -y -- diff --platform System.Runtime@P2..P3 --additive        # what's new?
+dnx dotnet-inspect -y -- diff --platform System.Net.Http@P2..P3 --additive       # per-library
+dnx dotnet-inspect -y -- diff --platform System.Text.Json@9.0.0..10.0.0          # across major versions
+```
+
+**Multi-library packages:** `diff --package` works across all libraries in a package (e.g., `Microsoft.Azure.SignalR` with multiple DLLs). For framework ref packages like `Microsoft.NETCore.App.Ref`, prefer `--platform` per-library since it resolves from installed packs.
+
+**Nightly/preview packages from custom feeds:** The `--source` flag works for version listing but not package downloads. Pre-populate the NuGet cache instead:
+
+```bash
+# Pre-populate cache (fails with NU1213 but downloads the package)
+dotnet add package Microsoft.NETCore.App.Ref --version <version> --source <feed-url>
+# Then use normally — resolves from NuGet cache
+dnx dotnet-inspect -y -- diff --platform System.Runtime@P2..P3 --additive
+```
+
+## Version Resolution (Docker-style)
+
+Version queries use Docker-like semantics: cached packages are served in under 15ms, network calls cost 1–4 seconds. Three flags, three behaviors:
+
+| Flag | Behavior | Network | Like Docker... |
+| ---- | -------- | ------- | -------------- |
+| `--version` (bare) | **Local** — returns the version from local cache | Only on cache miss | `docker run nginx` |
+| `--latest-version` | **Remote** — queries nuget.org for the absolute latest | Always | `docker pull nginx` |
+| `--versions` | **Remote** — returns every published version | Always | `docker image ls --all` |
+
+`--version` and bare-name inspection share the same cache. If `Foo --version` returns `2.0.3`, then `Foo` (or `package Foo`) will inspect that same `2.0.3` — no surprises, no extra network call. This is the fast path for most tasks.
+
+`--latest-version` and `--versions` always query nuget.org, so they reflect the latest published state. Use `--latest-version` when you need to confirm the newest version, e.g., before a dependency upgrade.
+
+```bash
+dnx dotnet-inspect -y -- Foo --version           # what's in the cache? (fast, local)
+dnx dotnet-inspect -y -- Foo --latest-version     # what's on nuget.org? (always network)
+dnx dotnet-inspect -y -- Foo --versions           # list all published versions
+dnx dotnet-inspect -y -- Foo --versions 5         # list latest 5 versions
+dnx dotnet-inspect -y -- Foo --versions --preview # include prerelease versions
+```
+
+The same flags work on the `package` subcommand:
+
+```bash
+dnx dotnet-inspect -y -- package Foo --version           # same local cache check
+dnx dotnet-inspect -y -- package Foo --latest-version     # always queries nuget.org
+dnx dotnet-inspect -y -- package Foo --versions           # list all versions
+```
+
+Version pinning with `@version` syntax:
+
+```bash
+dnx dotnet-inspect -y -- Foo@2.0.3                # pinned — no network if cached
+dnx dotnet-inspect -y -- Foo@latest               # always checks nuget.org
+dnx dotnet-inspect -y -- Foo                      # prefer cache, refresh on TTL expiry
+```
+
+**Use `--version` (not `--latest-version`) as the default.** It's fast and returns the same version that bare-name commands will use. Only reach for `--latest-version` when you need the absolute latest from nuget.org.
+
+## Structured Queries (like Go templates, without a DSL)
+
+Discover the schema, then select and project — no template language needed:
+
+```bash
+dnx dotnet-inspect -y -- System.Text.Json -D                          # list sections
+dnx dotnet-inspect -y -- System.Text.Json -D --effective              # sections with data (dry run)
+dnx dotnet-inspect -y -- library System.Text.Json -D --tree           # full schema tree
+dnx dotnet-inspect -y -- System.Text.Json -S Symbols                  # render one section
+dnx dotnet-inspect -y -- System.Text.Json -S Symbols --fields "PDB*"  # project specific fields
+dnx dotnet-inspect -y -- type System.Text.Json --columns Kind,Type    # project specific columns
+```
+
+## Mermaid Diagrams
+
+The `depends` command supports `--mermaid` for Mermaid diagram output. Two modes:
+
+| Flags | Output | Use case |
+| ----- | ------ | -------- |
+| `--mermaid` | Standalone mermaid (`graph TD`) | Pipe to `mmdc`, embed in tooling |
+| `--markdown --mermaid` | Mermaid fenced blocks inside markdown | Render in GitHub, VS Code, docs |
+
+```bash
+dnx dotnet-inspect -y -- depends Stream --mermaid                               # type hierarchy as mermaid
+dnx dotnet-inspect -y -- depends Stream --markdown --mermaid                    # embedded in markdown
+dnx dotnet-inspect -y -- depends --library System.Text.Json --mermaid           # assembly reference graph
+dnx dotnet-inspect -y -- depends --package Markout --mermaid                    # package dependency graph
+```
+
+## Search Scope
+
+Search commands (`find`, `extensions`, `implements`, `depends`) use scope flags:
+
+- **(no flags)** — all platform frameworks (runtime, aspnetcore, netstandard)
+- **`--platform`** — all platform frameworks
+- **`--extensions`** — curated Microsoft.Extensions.* packages
+- **`--aspnetcore`** — curated Microsoft.AspNetCore.* packages
+- **`--package Foo`** — specific NuGet package (combinable with scope flags)
+
+`type`, `member`, `library`, `diff` accept `--platform <name>` as a string for a specific platform library.
+
+## Command Reference
+
+| Command | Purpose |
+| ------- | ------- |
+| `type` | **Discover types** — terse output, no docs, use `--shape` for hierarchy |
+| `member` | **Inspect members** — docs on by default, supports dotted syntax (`-m Type.Member`) |
+| `find` | Search for types by glob or fuzzy match across any scope |
+| `diff` | Compare API surfaces between versions — breaking/additive classification |
+| `extensions` | Find extension methods/properties for a type (`--reachable` for transitive) |
+| `implements` | Find types implementing an interface or extending a base class |
+| `depends` | Walk dependency graphs upward — type hierarchy, package deps, or library refs |
+| `package` | Package metadata, files, versions, dependencies, `search` for NuGet discovery |
+| `library` | Library metadata, symbols, references, SourceLink audit |
+| `source` | **SourceLink URLs** — type-level or member-level (with line numbers), `--cat` to fetch content, `--verify` to check URLs |
+| `demo` | Run curated showcase queries — list, invoke, or feeling-lucky |
+
+## Filtering and Limiting
+
+```bash
+dnx dotnet-inspect -y -- type System.Text.Json -k enum               # filter by kind (type and member commands)
+dnx dotnet-inspect -y -- type System.Text.Json -t "*Converter*"      # glob filter on type names
+dnx dotnet-inspect -y -- member System.Text.Json JsonDocument -m Parse  # filter by member name
+dnx dotnet-inspect -y -- type System.Text.Json -5                    # first 5 lines (like head -5)
+dnx dotnet-inspect -y -- type System.Text.Json --tail 10             # last 10 lines (like tail -10)
+```
+
+**Do not pipe output through `head`, `tail`, or `Select-Object`.** Use built-in `--head` / `--tail`:
+
+- **`-n N`, `--head N`, or `-N`** — first N lines (like `head`). Keeps headers, truncates cleanly.
+- **`--tail N`** — last N lines (like `tail`). Buffers output, emits only the final N lines.
+- **`-m N`** (numeric) — item limit (members per kind section).
+- **`-k Kind`** — filter by kind: `class/struct/interface/enum/delegate` (type) or `method/property/field/event/constructor` (type single-type view, member).
+- **`-S Section`** — show only a specific section (glob-capable).
+
+## Key Syntax
+
+- **Generic types** need quotes: `'Option<T>'`, `'IEnumerable<T>'`
+- **Use `<T>` not `<>`** for generic types — `"Option<>"` resolves to the abstract base, `'Option<T>'` resolves to the concrete generic with constructors
+- **`type` uses `-t`** for type filtering, **`member` uses `-m`** for member filtering (not `--filter`)
+- **Dotted syntax** for `member`: `-m JsonSerializer.Deserialize` or `-m System.Text.Json.JsonSerializer.Deserialize`
+- **Diff ranges** use `..`: `--package System.Text.Json@9.0.0..10.0.0`
+- **Derived types** only show their own members — query the base type too
+
+## Installation
+
+Use `dnx` (like `npx`). Always use `-y` and `--` to prevent interactive prompts:
+
+```bash
+dnx dotnet-inspect -y -- <command>
+```
+
+## Related Skills
+
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Uses dotnet-inspect to investigate API surface and version diffs during reviews
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Queries types and members of existing libraries when generating SDK wrappers
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Inspects packages before upgrading or replacing them
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Discovers ASP.NET Core APIs across versions when migrating or adopting new features
diff --git a/.github/skills/dotnet-nuget-manager/SKILL.md b/.github/skills/dotnet-nuget-manager/SKILL.md
new file mode 100644
index 0000000..df2960c
--- /dev/null
+++ b/.github/skills/dotnet-nuget-manager/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: dotnet-nuget-manager
+description: Manages NuGet packages in .NET projects and solutions. Use when adding, removing, or updating NuGet package references or versions. Enforces dotnet CLI for package operations, supports Directory.Packages.props central version management, and provides version verification workflows. Handles dotnet add/remove package, dotnet list package --outdated, and dotnet restore.
+---
+
+# NuGet Manager
+
+## When to Use
+
+- Adding, removing, or updating NuGet packages in a .NET project or solution
+- Listing outdated packages and planning version bumps
+- Verifying a specific package version exists before bumping it
+- Working in a solution that uses `Directory.Packages.props` central version management
+
+## Prerequisites
+
+- .NET SDK installed (typically .NET 8.0 SDK or later, or a version compatible with the target solution).
+- `dotnet` CLI available on your `PATH`.
+- `jq` (JSON processor) — Linux/macOS; OR
+- PowerShell (`pwsh`) — Windows/cross-platform; required for version verification using `dotnet package search`.
+
+## Core Rules
+
+1.  **NEVER** directly edit `.csproj`, `.props`, or `Directory.Packages.props` files to **add** or **remove** packages. Always use `dotnet add package` and `dotnet remove package` commands.
+2.  **DIRECT EDITING** is ONLY permitted for **changing versions** of existing packages.
+3.  **VERSION UPDATES** must follow the mandatory workflow:
+    - Verify the target version exists on NuGet.
+    - Determine if versions are managed per-project (`.csproj`) or centrally (`Directory.Packages.props`).
+    - Update the version string in the appropriate file.
+    - Immediately run `dotnet restore` to verify compatibility.
+
+## Workflows
+
+### Adding a Package
+Use `dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>]`.
+Example: `dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json`
+
+### Removing a Package
+Use `dotnet remove [<PROJECT>] package <PACKAGE_NAME>`.
+Example: `dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json`
+
+### Updating Package Versions
+When updating a version, follow these steps:
+
+1.  **Verify Version Existence**:
+    Check if the version exists using the `dotnet package search` command with exact match and JSON formatting. 
+    Using `jq`:
+    `dotnet package search <PACKAGE_NAME> --exact-match --format json | jq -e '.searchResult[].packages[] | select(.version == "<VERSION>")'`
+    Using PowerShell:
+    `(dotnet package search <PACKAGE_NAME> --exact-match --format json | ConvertFrom-Json).searchResult.packages | Where-Object { $_.version -eq "<VERSION>" }`
+    
+2.  **Determine Version Management**:
+    - Search for `Directory.Packages.props` in the solution root. If present, versions should be managed there via `<PackageVersion Include="Package.Name" Version="1.2.3" />`.
+    - If absent, check individual `.csproj` files for `<PackageReference Include="Package.Name" Version="1.2.3" />`.
+
+3.  **Apply Changes**:
+    Modify the identified file with the new version string.
+
+4.  **Verify Stability**:
+    Run `dotnet restore` on the project or solution. If errors occur, revert the change and investigate.
+
+### Listing Outdated Packages
+
+Use `dotnet list package --outdated` to find packages with newer versions available.
+
+**Per project:**
+```bash
+dotnet list src/MyProject/MyProject.csproj package --outdated
+```
+
+**Entire solution:**
+```bash
+dotnet list package --outdated
+```
+
+The output shows the current version, the latest resolved version, and the latest available version for each package. Use this as the basis for deciding which packages to update, then follow the **Updating Package Versions** workflow for each.
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Used when adding `Microsoft.Extensions.*` packages for DI, Options, and Configuration
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Invokes this skill for health-check, resilience, and middleware packages
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invokes this skill in Step 7 to add SDK runtime dependencies
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Used when a review surfaces outdated or vulnerable packages
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Inspect package APIs before upgrading or replacing them
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — Adds EF Core providers, Testcontainers, and SQLite packages
+
diff --git a/.github/skills/dotnet-reviewer/SKILL.md b/.github/skills/dotnet-reviewer/SKILL.md
new file mode 100644
index 0000000..63d6f97
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: dotnet-reviewer
+description: Performs structured code reviews on .NET 10+ projects. Reviews either uncommitted working-tree changes or committed changes on the current feature branch (vs. main). Produces a Markdown report under docs/reviews/ with severity-tagged findings ([Critical|Major|Minor|Suggestion|Nitpick][Security|Performance|Architecture|Code-Quality|Tests|.NET-Idioms]) and fix suggestions. Must NOT activate on generic "review my code" requests; other-language reviewers must not be hijacked.
+---
+
+# dotnet-reviewer
+
+Structured code review for .NET 10+ projects.
+
+## When to Use This Skill
+
+A Code review for a .NET 10+ project is needed.
+The user may add language preferences (e.g., "in German") — apply that to the report only. The skill itself remains in English.
+
+## Prerequisites
+
+- `git` repo with `main` branch (for branch mode).
+- `dotnet ≥ 10` SDK if any of build/format/test will run.
+- `bash` 3.2+ available (macOS default works).
+- `python3` available (used by scripts for safe JSON encoding).
+
+## Workflow
+
+Follow these steps in order.
+
+### Step 1 — Interactive prompt
+
+Ask the user three things:
+
+1. **Mode:** `uncommitted` (working-tree vs HEAD, includes staged/unstaged/untracked) or `branch` (current branch vs `main`).
+2. **Tools:** for each of `build`, `format`, `test` — yes or no. Default no for all three.
+3. **Report language:** default English. If they want another language, capture it.
+
+Validate inputs against the whitelist. Re-prompt on invalid input.
+
+### Step 2 — Detect .NET version
+
+Run `scripts/detect-dotnet-version.sh --repo-root <repo>`.
+
+- Exit 0: parse JSON `{sdk, target_frameworks, project_files}`. Pick the highest `net<N>.0` from `target_frameworks` to drive checklist selection.
+- Exit 4 (SDK < 10 or none): abort. Tell the user "this skill targets .NET 10+; detected `<X>`."
+- Exit 5 (malformed): show offending file. Ask the user whether to proceed without version-awareness. If yes, fall back to general checklists only.
+- Exit 2 (not a directory) or 1 (usage): bug — report and abort.
+
+### Step 3 — Collect diff
+
+Run `scripts/collect-diff.sh --repo-root <repo> --mode <mode> --baseline main`.
+
+- Exit 0 with `files == 0`: report "no changes to review" and exit.
+- Exit 0 with `files > 0`: continue.
+- Exit 2: not a git repo — abort.
+- Exit 3 (branch mode, missing `main`): abort, tell user.
+
+### Step 4 — Large-diff strategy gate
+
+If `loc > 2000` OR `files > 50`, ask the user to choose:
+
+- **(B) Review everything** — note token cost in report header.
+- **(C) Prioritize** — review files matching `*Service.cs`, `*Controller.cs`, files without sibling `*.Tests/*Tests.cs` first; summarize the rest.
+- **(D) Chunk file-by-file** — review each file independently; group findings by file.
+
+If C is chosen but no files match the priority heuristics, fall back to D and note the fallback transparently in the report.
+
+### Step 5 — Run requested tool checks
+
+For each tool the user selected, invoke `scripts/run-checks.sh --repo-root <repo>` with the appropriate flag(s). Parse JSON.
+
+If a tool isn't installed, the script reports the failure inside the JSON — log "X not available, skipping" and continue. Don't abort.
+
+### Step 6 — Review
+
+Walk the diff against:
+1. The version-specific checklist (`references/review-checklist-net<N>.md`).
+2. `references/review-checklist-security.md`.
+3. `references/review-checklist-performance.md`.
+4. `references/review-checklist-architecture.md`.
+5. `references/review-checklist-code-quality.md`.
+
+Fold tool findings into the issue list using the severity mapping defined in `references/severity-taxonomy.md`:
+- `dotnet build` errors → Critical
+- `dotnet build` warnings → Minor
+- `dotnet test` failures → Critical
+- `dotnet format` violations → Suggestion
+
+Each finding MUST include a fix suggestion as a code block (`csharp` fenced) — no auto-patching.
+
+### Step 7 — Render report
+
+Generate the report following `references/report-format.md` exactly:
+- Title + metadata block
+- Detailed Executive Summary (counts, top-3 risks, LOC, scope)
+- Findings ordered by severity desc, then file path asc
+- Tool Output Appendix
+
+### Step 8 — Write report
+
+Path: `docs/reviews/YYYY-MM-DD-<branch>-<mode>.md`. Branch name is sanitized (replace `/` with `-`).
+
+If the path exists, append `-2`, `-3`, … until unique. Create `docs/reviews/` if missing. **Never auto-commit. Never overwrite.**
+
+Output to chat: the file path and a one-line summary (e.g., `"Wrote review with 2 Critical, 5 Major findings to docs/reviews/…"`).
+
+## Output Contract
+
+- Single Markdown file under `docs/reviews/`.
+- Format strictly per `references/report-format.md`.
+- Severity and area tags from `references/severity-taxonomy.md`.
+
+## Resource Index
+
+- `scripts/detect-dotnet-version.sh` — SDK / target framework detection
+- `scripts/collect-diff.sh` — diff collection with exclusions
+- `scripts/run-checks.sh` — optional dotnet build/format/test
+- `references/severity-taxonomy.md`
+- `references/report-format.md`
+- `references/review-checklist-net10.md`
+- `references/review-checklist-security.md`
+- `references/review-checklist-performance.md`
+- `references/review-checklist-architecture.md`
+- `references/review-checklist-code-quality.md`
+
+## Things This Skill Never Does
+
+- Auto-patches or auto-commits the report.
+- Bypasses git hooks (`--no-verify`, `--no-gpg-sign`).
+- Runs destructive operations as "fixes" (no `git reset`, no deletions).
+- Includes secrets in logs or the report.
+- Reviews .NET versions below 10 — aborts with a clear message.
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Review findings reference DI lifetime, Options, and configuration best practices
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — Code-quality checklist references XML documentation conventions
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Test-quality findings reference this skill's expectations
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — EF Core findings reference these data-access best practices
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — ASP.NET Core findings reference this skill's conventions
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Surfaced outdated/vulnerable packages are addressed via this skill
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Used to investigate API surface and version diffs during review
diff --git a/.github/skills/dotnet-reviewer/references/report-format.md b/.github/skills/dotnet-reviewer/references/report-format.md
new file mode 100644
index 0000000..301d3e9
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/report-format.md
@@ -0,0 +1,78 @@
+# Report Format
+
+The reviewer writes one Markdown file to `docs/reviews/YYYY-MM-DD-<branch>-<mode>.md`.
+Never overwrite — append `-2`, `-3`, … on collision. Never auto-commit.
+
+## Required Sections
+
+1. Title + metadata block
+2. Executive Summary (detailed)
+3. Findings, ordered by severity desc, then by file path
+4. Tool Output Appendix (if any tool ran)
+
+## Skeleton
+
+```markdown
+# .NET Code Review — <branch> (<mode>)
+
+**Date:** YYYY-MM-DD
+**Mode:** uncommitted | branch (vs. main)
+**Detected SDK:** 10.0.x
+**Target Framework(s):** net10.0, …
+**Tools run:** build=Y/N · format=Y/N · test=Y/N
+**Exclusions:** .gitignore, *.min.js, wwwroot/lib/**
+**Review strategy:** full | prioritized | chunked
+**Diff size:** <files> files, <loc> changed LOC
+
+## Executive Summary
+
+| Severity | Count |
+|---|---|
+| Critical | N |
+| Major | N |
+| Minor | N |
+| Suggestion | N |
+| Nitpick | N |
+
+**Top risks:**
+1. <one line>
+2. <one line>
+3. <one line>
+
+**Overall:** <1–2 sentence assessment>
+
+## Findings
+
+### [Critical][Security] src/Api/UserController.cs:42
+<one-line description>
+
+<recommendation paragraph>
+
+```csharp
+// fix suggestion
+```
+
+### [Major][Performance] src/Data/Repo.cs:88
+…
+
+## Tool Output Appendix
+
+### dotnet build
+- 0 errors, 2 warnings (see findings above for warnings folded in).
+
+### dotnet test
+- 12 passed, 0 failed (duration: 4s).
+
+### dotnet format
+- Skipped.
+```
+
+## Rules
+
+- **Every finding MUST include a fix suggestion** as a code block. If the fix is structural (no single-snippet rewrite), describe the steps in prose and provide the most-affected snippet.
+- Do not paste raw diff content. Reference `path:line` instead.
+- File paths are repo-relative.
+- Group findings by severity desc, ties broken by file path asc.
+- Tool warnings/errors that are already covered by a hand-written finding should not be duplicated in the appendix — note "folded into findings".
+- If strategy `chunked` was used, group findings under `## Findings — <file>` subsections.
+- If strategy `prioritized` was used, list deferred files at the end as `## Files Not Reviewed in Detail`.
diff --git a/.github/skills/dotnet-reviewer/references/review-checklist-architecture.md b/.github/skills/dotnet-reviewer/references/review-checklist-architecture.md
new file mode 100644
index 0000000..773733b
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/review-checklist-architecture.md
@@ -0,0 +1,37 @@
+# Review Checklist — Architecture
+
+## Layering
+
+- Domain references no infrastructure (no EF Core attributes on domain entities; no `HttpClient` in domain).
+- Application layer orchestrates — does not reach into UI/infrastructure types directly.
+- Controllers / minimal-API handlers stay thin: parse, dispatch to application service, map result.
+- Infrastructure adapters implement domain/application interfaces, not the other way around.
+
+## Dependency Direction
+
+- Outer rings depend on inner rings. Flag any inner-ring file with a `using` of an outer-ring namespace.
+- Solution structure should make this provable; if it doesn't (single project, mixed namespaces), call it out.
+
+## SOLID
+
+- **SRP:** classes that change for multiple reasons. Public surface that mixes orchestration with persistence.
+- **OCP:** strategy patterns where `if (type == X) … else if (type == Y) …` is repeated across files.
+- **LSP:** subclass that throws `NotSupportedException` on a base member.
+- **ISP:** "fat" interfaces with one consumer per method. Split or use mark-only interfaces.
+- **DIP:** new-ing dependencies inside a class instead of injecting (except for value objects).
+
+## Dependency Injection
+
+See the `dotnet-aspnet` skill (Dependency Injection + Configuration sections) for lifetime rules and the Options pattern. Reviewer-specific hook: flag DI changes that capture a `Scoped` service inside a `Singleton`, call `BuildServiceProvider()` during composition, or register `IOptions<T>` without `ValidateOnStart()`.
+
+## Pattern Consistency
+
+- New code matches the existing project pattern. If this file uses CQRS handlers and you added a controller method that bypasses them, flag it.
+- Naming consistency: `XxxService` vs. `XxxRepository` vs. `XxxHandler` — pick one and stay consistent within a bounded context.
+- New pattern introductions (e.g., switching from MediatR to direct calls) need an architectural rationale; flag if introduced silently.
+
+## Module Boundaries
+
+- Each project (.csproj) has a clear purpose. Flag projects whose name and contents have drifted.
+- Public API of a project is intentional — `internal` over `public` unless cross-project consumption is required.
+- `InternalsVisibleTo` only for tests; flag if used to share types with non-test projects.
diff --git a/.github/skills/dotnet-reviewer/references/review-checklist-code-quality.md b/.github/skills/dotnet-reviewer/references/review-checklist-code-quality.md
new file mode 100644
index 0000000..ada4779
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/review-checklist-code-quality.md
@@ -0,0 +1,57 @@
+# Review Checklist — Code Quality
+
+## Naming
+
+- Methods are verbs. Properties are nouns. Async methods end in `Async`.
+- No Hungarian notation (`strName`, `iCount`).
+- Booleans read as questions: `IsValid`, `HasItems`, `CanRetry`.
+- Acronyms: `Url`, `Id`, `Api` (PascalCase per .NET conventions, not `URL`/`ID`/`API`).
+- Type parameters: `T`, or `TKey`/`TValue` — descriptive when more than one.
+
+## Nullability
+
+- `<Nullable>enable</Nullable>` is on (project-level check).
+- No `!` (null-forgiving operator) without a comment explaining why.
+- No `#nullable disable` regions in new code.
+- API surface honors nullability annotations — methods returning `T?` actually return null in some path.
+
+## Complexity
+
+- Methods over ~30 lines or with 4+ levels of nesting deserve a closer look.
+- A `switch` with more than ~7 arms over the same value usually wants polymorphism or a lookup table.
+- Boolean parameters often hide two methods — flag and suggest splitting.
+
+## Exception Handling
+
+- Catch the specific exception type, not `Exception`. `catch (Exception)` requires justification.
+- Never swallow exceptions silently. Logging counts only if the log line carries enough context to diagnose.
+- Don't use exceptions for control flow.
+- Wrap third-party exceptions at the boundary; do not leak them into domain code.
+
+## IDisposable / IAsyncDisposable
+
+- `using` (or `using` declarations) for every `IDisposable` you create.
+- `IDisposable` types as fields require the owning class to also be disposable.
+- `IAsyncDisposable` consumed with `await using`, not `using`.
+
+## Dead Code
+
+- Unused `using` directives → format check should catch; flag if format check is off.
+- Unreachable code (`return` followed by statements).
+- Unused private members. Public unused members may be API for a consumer — leave alone unless clearly orphaned.
+
+## Comments and Docs
+
+- Public API has XML docs, especially for libraries. See the `dotnet-xmldocs` skill for the tag conventions (`<summary>`, `<param>`, `<returns>`, `<exception>`, etc.).
+- Comments explain *why*, not *what*. Flag comments that restate the code.
+- TODOs without a ticket reference are a smell; flag.
+
+## Tests (cross-cutting)
+
+See the `dotnet-tester` skill for AAA layout, `Method_Condition_Expected` naming, mocking conventions, and edge-case coverage. Reviewer-specific hook: flag any new public behavior that ships without at least one test, and any test body containing conditional logic (`if`/`for`).
+
+## Logging
+
+- Structured logging (named placeholders), not string concatenation.
+- Log level matches consequence: `Error` for exceptions reaching the boundary, `Warning` for recoverable degraded paths, `Information` for state transitions, `Debug` for detail.
+- No PII in logs (email, user names, full request bodies) without a redaction strategy.
diff --git a/.github/skills/dotnet-reviewer/references/review-checklist-net10.md b/.github/skills/dotnet-reviewer/references/review-checklist-net10.md
new file mode 100644
index 0000000..8c67a22
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/review-checklist-net10.md
@@ -0,0 +1,30 @@
+# Review Checklist — .NET 10
+
+Apply when `detect-dotnet-version.sh` reports `target_frameworks` containing `net10.0`.
+
+## Language Idioms
+
+- **Primary constructors** — prefer over redundant private fields when the parameter is used directly. Flag: legacy `ctor + private readonly field` pattern in new code.
+- **Collection expressions** — `[1, 2, 3]` over `new[] { 1, 2, 3 }` and `new List<int> { 1, 2, 3 }`. Flag: verbose collection initialization.
+- **Required members** — `required` modifier replaces hand-rolled validation in constructors. Flag: throws in constructor for missing init-only properties.
+- **`field` keyword** — auto-property backing-field access (preview in 9, stable in 10). Flag: unnecessary backing field declarations.
+- **Pattern matching** — list patterns, relational patterns. Flag: chained `if (x.Length > 0 && x[0] == …)`.
+- **`init` and `required` together** — for immutable POCOs.
+
+## API Idioms
+
+- `System.Threading.Lock` (new lock type) over `object`-based `lock` for new code.
+- `Random.Shared` for non-cryptographic randomness — never `new Random()` in hot path.
+- `TimeProvider` for testable time — flag direct `DateTime.UtcNow` in code that should be testable.
+- `JsonSerializerContext` (source-gen) over reflection-based `JsonSerializer` on hot paths.
+
+## Project Configuration
+
+- `<Nullable>enable</Nullable>` MUST be on. Flag projects without it.
+- `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` recommended for libraries.
+- `<LangVersion>` should not be pinned below the SDK's default unless a comment explains why.
+- `ImplicitUsings` enabled — flag stale top-of-file using directives that are already implicit.
+
+## Non-version-specific checks
+
+For language- and runtime-neutral pitfalls (`.Result`/`.Wait()`, `async void`, allocation hot spots, etc.) see `review-checklist-performance.md` and `review-checklist-code-quality.md`. This file covers only what is specific to .NET 10.
diff --git a/.github/skills/dotnet-reviewer/references/review-checklist-performance.md b/.github/skills/dotnet-reviewer/references/review-checklist-performance.md
new file mode 100644
index 0000000..15f5030
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/review-checklist-performance.md
@@ -0,0 +1,44 @@
+# Review Checklist — Performance
+
+## async/await
+
+- No `.Result`, `.Wait()`, `GetAwaiter().GetResult()` in async code paths.
+- `async void` only on event handlers.
+- `Task.Run` not used to "fake async" over CPU-bound work that already runs on a worker thread (e.g., inside an existing async pipeline).
+- `ConfigureAwait(false)` on library code (not application code in modern ASP.NET).
+- `ValueTask` for hot paths that frequently complete synchronously; do not consume `ValueTask` more than once.
+- `IAsyncEnumerable<T>` for streaming; flag `List<T>` accumulation when callers can stream.
+
+## Allocations
+
+- `string` concatenation in loops → `StringBuilder` or `string.Create`.
+- `string.Format` with hot-path frequency → interpolated handlers.
+- LINQ `ToList()` / `ToArray()` immediately followed by another enumeration — extra allocation for nothing.
+- `params object[]` on hot paths — allocates per call. Use overloads.
+- Closures capturing `this` in hot lambdas — flag if measurably hot.
+- Boxing: `int` → `object`, generic constraints missing.
+
+## Span / Memory
+
+- Parsing/slicing strings: `ReadOnlySpan<char>` over `Substring`.
+- File / network buffers: `Memory<byte>` / `IBufferWriter<byte>` over `byte[]`.
+- `stackalloc` for small fixed buffers in hot paths (with bounds check).
+
+## EF Core
+
+See the `dotnet-ef-core` skill (Performance section) for the full list of EF Core performance pitfalls. Reviewer-specific hook: flag any new query against a `DbContext` that is missing `.AsNoTracking()` on a read-only path, that calls `.ToList()` before a filter, or that uses `foreach` to iterate parent entities while issuing per-row child queries (N+1).
+
+## Hot-Path Heuristics
+
+A method is "hot" if any of:
+- It's on a request path of an HTTP server.
+- It's inside a `for` / `while` over a user-sized collection.
+- It's called from `Hosted` / `BackgroundService` loops.
+- A comment or naming suggests perf-sensitive use ("inner loop", "hot", "fast path").
+
+## Concurrency
+
+- Shared mutable state without synchronization (lock, `Interlocked`, immutable patterns).
+- `ConcurrentDictionary` misuse — `GetOrAdd` with allocating factory called on every hit.
+- `SemaphoreSlim` not awaited in `using` / `try/finally`.
+- `Task.WhenAll` with thousands of tasks → bound concurrency (`Parallel.ForEachAsync` with `MaxDegreeOfParallelism`).
diff --git a/.github/skills/dotnet-reviewer/references/review-checklist-security.md b/.github/skills/dotnet-reviewer/references/review-checklist-security.md
new file mode 100644
index 0000000..adc6d24
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/review-checklist-security.md
@@ -0,0 +1,61 @@
+# Review Checklist — Security
+
+## Input Validation
+
+- All public-API entry points (controllers, minimal-API handlers, gRPC, message handlers) validate input.
+- DTOs use `[Required]`, `[Range]`, `[StringLength]`, or FluentValidation rules. Flag DTOs without any validation.
+- Reject untrusted input before it reaches the data layer. No ad-hoc string parsing in business logic.
+
+## Injection
+
+- **SQL:** parameterized queries via EF Core LINQ, `FromSqlInterpolated`, or `DbCommand` with parameters. Flag: `FromSqlRaw` with interpolation, raw `SqlCommand` with concatenation.
+- **Command/Process:** `Process.Start` with user-controlled args — flag any concatenation; require `ProcessStartInfo` with `ArgumentList`.
+- **LDAP/XPath:** sanitized filter construction.
+- **Path traversal:** `Path.Combine` does not protect — validate that the resolved absolute path is under the intended root.
+
+## Authentication / Authorization
+
+- `[Authorize]` (or equivalent) on every non-anonymous endpoint. Flag controllers without `[Authorize]` at class level when most actions need auth.
+- Role/policy checks match the intent (no `[Authorize(Roles = "Admin")]` for user-scoped data; use resource-based authorization).
+- No "fallback to anonymous" branches in middleware.
+
+## Secrets and Credentials
+
+- No secrets in source: API keys, connection strings with passwords, JWT keys.
+- `appsettings.*.json` with secrets must be `.gitignore`-d; production uses a secret manager.
+- Logs do not include `request.Headers`, `Request.Body`, or full URLs containing tokens.
+- `HttpClient` does not blindly trust certs (`ServerCertificateCustomValidationCallback` should not return `true`).
+
+## Deserialization & Serialization
+
+- `JsonSerializer` does not deserialize untrusted JSON to `object` or `dynamic`.
+- `BinaryFormatter` is forbidden — flag any usage.
+- XML deserialization disables DTD processing (`XmlReaderSettings.DtdProcessing = Prohibit`).
+
+## Cryptography
+
+- No `MD5` or `SHA1` for security purposes. Use `SHA256+`.
+- No `RandomNumberGenerator.Create()` followed by predictable seeding — use `RandomNumberGenerator.GetBytes()`.
+- AES with `CipherMode.ECB` is forbidden. Prefer authenticated modes (`AesGcm`).
+- No hard-coded IVs or keys.
+
+## Web App Specific
+
+- CSRF protection on state-changing endpoints (cookie auth + non-GET).
+- Anti-forgery tokens for forms.
+- CORS is restrictive — `AllowAnyOrigin` only on read-only public endpoints.
+- HSTS, secure cookies, `SameSite=Lax` minimum.
+- Output encoding — Razor auto-encodes; `Html.Raw` is a code smell that needs justification.
+
+## OWASP Mapping
+
+When reporting, reference the OWASP Top 10 category in parentheses:
+- A01 Broken Access Control
+- A02 Cryptographic Failures
+- A03 Injection
+- A04 Insecure Design
+- A05 Security Misconfiguration
+- A07 Identification & Auth Failures
+- A08 Software & Data Integrity Failures
+- A09 Security Logging Failures
+- A10 SSRF
diff --git a/.github/skills/dotnet-reviewer/references/severity-taxonomy.md b/.github/skills/dotnet-reviewer/references/severity-taxonomy.md
new file mode 100644
index 0000000..9aa92c7
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/references/severity-taxonomy.md
@@ -0,0 +1,52 @@
+# Severity Taxonomy and Area Tags
+
+Every finding is tagged `[Severity][Area]` followed by `path:line`.
+
+## Severity Levels
+
+| Severity | When to use | Examples |
+|---|---|---|
+| **Critical** | Ship-blocker. Production correctness, security, data loss, or a failing test. | SQL injection, unhandled `null` deref on hot path, failing test, build error. |
+| **Major** | Will hurt users or maintainers but not a ship-blocker. | Missing input validation on a public API, race condition under load, broken contract with caller. |
+| **Minor** | Real issue, low impact, deserves a fix in this PR. | Build warning, sloppy exception handling, missing log context, dead code. |
+| **Suggestion** | Improvement worth considering. Author can accept or reject. | Refactor opportunity, alternative idiom, better naming, format violation. |
+| **Nitpick** | Cosmetic. Author should ignore unless trivial. | Whitespace, comment phrasing, minor style preference. |
+
+## Area Tags
+
+Pick the **dominant** concern. If two apply, pick the higher-severity area.
+
+| Tag | Scope |
+|---|---|
+| `Security` | Authn/authz, input validation, secrets, injection, deserialization, crypto, OWASP. |
+| `Performance` | Allocations, async/await misuse, EF query shape, hot-path heuristics, Span/Memory. |
+| `Architecture` | Layer/dependency direction, SOLID, DI misuse, pattern consistency, coupling. |
+| `Code-Quality` | Naming, complexity, nullability, IDisposable, dead code, exception strategy. |
+| `Tests` | Missing coverage, flaky tests, weak assertions, test maintenance smell. |
+| `.NET-Idioms` | Version-specific idioms (Primary Ctors, Collection Expressions, Required Members, …). |
+
+## Mapping from Tool Outputs
+
+| Tool finding | Severity | Area |
+|---|---|---|
+| `dotnet build` error | Critical | Code-Quality (or context-driven) |
+| `dotnet build` warning | Minor | Code-Quality |
+| `dotnet test` failure | Critical | Tests |
+| `dotnet format` violation | Suggestion | Code-Quality |
+
+## Examples
+
+```
+[Critical][Security] src/Api/UserController.cs:42
+User input is concatenated directly into a SQL string.
+
+Use parameterized queries via `FromSqlInterpolated` or EF Core's LINQ.
+
+```csharp
+// before
+var users = ctx.Users.FromSqlRaw($"SELECT * FROM Users WHERE Name = '{name}'");
+
+// after
+var users = ctx.Users.FromSqlInterpolated($"SELECT * FROM Users WHERE Name = {name}");
+```
+```
diff --git a/.github/skills/dotnet-reviewer/scripts/collect-diff.sh b/.github/skills/dotnet-reviewer/scripts/collect-diff.sh
new file mode 100644
index 0000000..75ecc02
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/scripts/collect-diff.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# collect-diff.sh — collect a unified diff in uncommitted or branch mode.
+# Output JSON: {loc, files, file_list, diff}
+# Exit codes: 0 ok (incl. empty diff), 1 usage, 2 not git, 3 baseline missing.
+
+set -u
+
+usage() {
+  cat <<EOF
+collect-diff.sh — collect a unified diff with exclusions applied
+
+Usage:
+  collect-diff.sh --repo-root <path> --mode uncommitted|branch [--baseline main]
+  collect-diff.sh --help
+
+Exclusions:
+  - .gitignore (implicit via git diff)
+  - *.min.js
+  - wwwroot/lib/**
+
+Exit codes:
+  0  success (empty diff is success)
+  1  usage error
+  2  not a git repository
+  3  baseline branch not found (branch mode only)
+EOF
+}
+
+REPO_ROOT="" MODE="" BASELINE="main"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --mode)      MODE=${2:-};      shift 2 ;;
+    --baseline)  BASELINE=${2:-};  shift 2 ;;
+    --help|-h)   usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" && -n "$MODE" ]] || { usage >&2; exit 1; }
+case "$MODE" in uncommitted|branch) ;; *) echo "invalid --mode: $MODE" >&2; exit 1 ;; esac
+[[ -d "$REPO_ROOT/.git" ]] || { echo "not a git repository: $REPO_ROOT" >&2; exit 2; }
+
+cd "$REPO_ROOT"
+
+if [[ "$MODE" == "branch" ]]; then
+  if ! git rev-parse --verify --quiet "$BASELINE" -- >/dev/null; then
+    echo "baseline branch not found: $BASELINE" >&2
+    exit 3
+  fi
+fi
+
+# Guard: uncommitted mode against an empty repo (no HEAD yet) — abort cleanly.
+if [[ "$MODE" == "uncommitted" ]] && ! git rev-parse --verify --quiet HEAD -- >/dev/null; then
+  echo "repository has no commits yet (HEAD missing)" >&2
+  exit 3
+fi
+
+# pathspec exclusions on top of .gitignore
+EXCLUDES=(
+  ':(exclude)*.min.js'
+  ':(exclude,glob)wwwroot/lib/**'
+)
+
+if [[ "$MODE" == "uncommitted" ]]; then
+  # working-tree changes vs HEAD (staged + unstaged + untracked)
+  diff_payload=$(git diff HEAD --no-renames -- . "${EXCLUDES[@]}")
+  # Append untracked files as added-from-empty diffs
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    diff_payload+=$'\n'$(git diff --no-index --no-renames /dev/null "$f" 2>/dev/null || true)
+  done < <(git ls-files --others --exclude-standard -- . "${EXCLUDES[@]}")
+else
+  diff_payload=$(git diff "$BASELINE"...HEAD --no-renames -- . "${EXCLUDES[@]}")
+fi
+
+# Count files & LOC from the diff
+files=0
+loc=0
+file_list=()
+while IFS= read -r line; do
+  case "$line" in
+    "+++ b/"*) f=${line#+++ b/}; [[ "$f" != "/dev/null" ]] && { file_list+=("$f"); files=$((files+1)); } ;;
+    "+"*|"-"*)
+      [[ "$line" == "+++ "* || "$line" == "--- "* ]] || loc=$((loc+1))
+      ;;
+  esac
+done <<< "$diff_payload"
+
+# emit JSON (escape diff payload for JSON string)
+json_escape() {
+  printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()), end="")'
+}
+
+list_json() {
+  local first=1
+  printf '['
+  for v in "$@"; do
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '"%s"' "${v//\"/\\\"}"
+  done
+  printf ']'
+}
+
+diff_json=$(json_escape "$diff_payload")
+fl_json=$(list_json ${file_list[@]+"${file_list[@]}"})
+
+printf '{"loc":%d,"files":%d,"file_list":%s,"diff":%s}\n' \
+  "$loc" "$files" "$fl_json" "$diff_json"
diff --git a/.github/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh b/.github/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh
new file mode 100644
index 0000000..abc16df
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/scripts/detect-dotnet-version.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# detect-dotnet-version.sh — Detect .NET SDK and target frameworks in a repo.
+# Outputs JSON: {sdk, target_frameworks[], project_files[]}
+# Exit codes: 0 ok, 1 usage, 4 SDK<10, 5 malformed project file.
+
+set -u
+
+usage() {
+  cat <<EOF
+detect-dotnet-version.sh — detect .NET SDK and target frameworks
+
+Usage: detect-dotnet-version.sh --repo-root <path>
+       detect-dotnet-version.sh --help
+
+Exit codes:
+  0  success
+  1  usage error
+  4  SDK below 10 or no .NET version detected
+  5  malformed global.json or *.csproj
+EOF
+}
+
+REPO_ROOT=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --help|-h)   usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" ]] || { echo "missing --repo-root" >&2; usage >&2; exit 1; }
+[[ -d "$REPO_ROOT" ]] || { echo "not a directory: $REPO_ROOT" >&2; exit 1; }
+
+# --- parse global.json (optional) ---
+SDK="unknown"
+if [[ -f "$REPO_ROOT/global.json" ]]; then
+  SDK=$(grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$REPO_ROOT/global.json" \
+        | head -n1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+  if [[ -z "$SDK" ]]; then
+    echo "malformed global.json: $REPO_ROOT/global.json" >&2
+    exit 5
+  fi
+  sdk_major=${SDK%%.*}
+  if [[ "$sdk_major" =~ ^[0-9]+$ ]] && [[ "$sdk_major" -lt 10 ]]; then
+    echo "global.json pins SDK $SDK; this skill targets .NET 10+" >&2
+    exit 4
+  fi
+fi
+
+# --- find all *.csproj and extract <TargetFramework(s)> ---
+project_files_json="[]"
+tfms_json="[]"
+# bash 3.2 compatible: read into array via while loop
+projects=()
+while IFS= read -r line; do
+  projects+=("$line")
+done < <(find "$REPO_ROOT" -type f -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*' 2>/dev/null | sort)
+
+if [[ ${#projects[@]} -eq 0 ]]; then
+  echo "no *.csproj found under $REPO_ROOT" >&2
+  exit 4
+fi
+
+all_tfms=()
+rel_paths=()
+
+for p in "${projects[@]}"; do
+  rel=${p#"$REPO_ROOT/"}
+  rel_paths+=("$rel")
+  # crude check for malformed XML: must contain </Project>
+  if ! grep -q '</Project>' "$p"; then
+    echo "malformed csproj: $p" >&2
+    exit 5
+  fi
+  # extract single or plural element
+  tfm_line=$(grep -oE '<TargetFramework[s]?>[^<]+</TargetFramework[s]?>' "$p" | head -n1 || true)
+  if [[ -z "$tfm_line" ]]; then
+    echo "no TargetFramework in: $p" >&2
+    exit 5
+  fi
+  tfm_value=$(printf '%s' "$tfm_line" | sed -E 's|<TargetFrameworks?>([^<]+)</TargetFrameworks?>|\1|')
+  IFS=';' read -r -a parts <<<"$tfm_value"
+  for t in "${parts[@]}"; do
+    [[ -n "$t" ]] && all_tfms+=("$t")
+  done
+done
+
+# --- enforce .NET 10+ ---
+ok=0
+for t in "${all_tfms[@]}"; do
+  if [[ "$t" =~ ^net([0-9]+)\.[0-9]+$ ]]; then
+    major=${BASH_REMATCH[1]}
+    if [[ $major -ge 10 ]]; then ok=1; break; fi
+  fi
+done
+
+if [[ $ok -eq 0 ]]; then
+  echo "no target framework >= net10.0 detected; found: ${all_tfms[*]}" >&2
+  exit 4
+fi
+
+# --- emit JSON (manual, jq-free) ---
+json_array() {
+  local first=1
+  printf '['
+  for v in "$@"; do
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '"%s"' "${v//\"/\\\"}"
+  done
+  printf ']'
+}
+
+tfms_json=$(json_array "${all_tfms[@]}")
+project_files_json=$(json_array "${rel_paths[@]}")
+
+printf '{"sdk":"%s","target_frameworks":%s,"project_files":%s}\n' \
+  "$SDK" "$tfms_json" "$project_files_json"
diff --git a/.github/skills/dotnet-reviewer/scripts/run-checks.sh b/.github/skills/dotnet-reviewer/scripts/run-checks.sh
new file mode 100644
index 0000000..df5fbea
--- /dev/null
+++ b/.github/skills/dotnet-reviewer/scripts/run-checks.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# run-checks.sh — run optional dotnet build|format|test, emit structured JSON.
+# Output JSON: {build:{ok,warnings[],errors[]}|null, format:{ok,violations[]}|null, test:{ok,failed[],duration}|null}
+# Always exits 0 (tool failures are reported in JSON, not via exit code) unless usage error.
+# DOTNET_BIN env overrides `dotnet` (used by tests).
+
+set -u
+
+usage() {
+  cat <<EOF
+run-checks.sh — run dotnet build/format/test and emit structured JSON
+
+Usage:
+  run-checks.sh --repo-root <path> [--build] [--format] [--test]
+  run-checks.sh --help
+
+Each requested check runs independently; failures are reported in JSON, not via exit code.
+Set DOTNET_BIN to override the dotnet binary path (used by tests).
+EOF
+}
+
+REPO_ROOT=""; DO_BUILD=0; DO_FORMAT=0; DO_TEST=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root) REPO_ROOT=${2:-}; shift 2 ;;
+    --build)  DO_BUILD=1; shift ;;
+    --format) DO_FORMAT=1; shift ;;
+    --test)   DO_TEST=1; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+[[ -n "$REPO_ROOT" && -d "$REPO_ROOT" ]] || { usage >&2; exit 1; }
+
+DOTNET=${DOTNET_BIN:-dotnet}
+
+run_dotnet() {
+  # captures stdout+stderr into the named variable, returns the exit code
+  local _out_var=$1; shift
+  local _tmp; _tmp=$(mktemp)
+  local _rc=0
+  # shellcheck disable=SC2086
+  ( cd "$REPO_ROOT" && $DOTNET "$@" ) >"$_tmp" 2>&1 || _rc=$?
+  printf -v "$_out_var" '%s' "$(cat "$_tmp")"
+  rm -f "$_tmp"
+  return "$_rc"
+}
+
+json_string() {
+  python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()), end="")' <<<"$1"
+}
+
+json_string_array() {
+  local first=1
+  printf '['
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    [[ $first -eq 0 ]] && printf ','
+    first=0
+    printf '%s' "$(json_string "$line")"
+  done <<<"$1"
+  printf ']'
+}
+
+BUILD_JSON="null"
+if [[ $DO_BUILD -eq 1 ]]; then
+  out=""
+  run_dotnet out build --nologo --verbosity minimal || true
+  warnings=$(grep -E ': warning [A-Z]+[0-9]+' <<<"$out" || true)
+  errors=$(grep -E ': error [A-Z]+[0-9]+' <<<"$out" || true)
+  ok="true"; [[ -n "$errors" ]] && ok="false"
+  BUILD_JSON=$(printf '{"ok":%s,"warnings":%s,"errors":%s}' \
+    "$ok" \
+    "$(json_string_array "$warnings")" \
+    "$(json_string_array "$errors")")
+fi
+
+FORMAT_JSON="null"
+if [[ $DO_FORMAT -eq 1 ]]; then
+  out=""
+  rc=0
+  run_dotnet out format --verify-no-changes --no-restore || rc=$?
+  violations=$(grep -E '\([0-9]+,[0-9]+\)' <<<"$out" || true)
+  ok="true"; [[ $rc -ne 0 ]] && ok="false"
+  FORMAT_JSON=$(printf '{"ok":%s,"violations":%s}' \
+    "$ok" "$(json_string_array "$violations")")
+fi
+
+TEST_JSON="null"
+if [[ $DO_TEST -eq 1 ]]; then
+  out=""
+  rc=0
+  start=$(date +%s)
+  run_dotnet out test --nologo --verbosity minimal || rc=$?
+  end=$(date +%s)
+  failed=$(grep -E '^Failed:' <<<"$out" || true)
+  ok="true"; [[ $rc -ne 0 ]] && ok="false"
+  TEST_JSON=$(printf '{"ok":%s,"failed":%s,"duration":%d}' \
+    "$ok" "$(json_string_array "$failed")" "$((end - start))")
+fi
+
+printf '{"build":%s,"format":%s,"test":%s}\n' "$BUILD_JSON" "$FORMAT_JSON" "$TEST_JSON"
diff --git a/.github/skills/dotnet-sdk-builder/SKILL.md b/.github/skills/dotnet-sdk-builder/SKILL.md
index 2f7f0c3..fafbf4d 100644
--- a/.github/skills/dotnet-sdk-builder/SKILL.md
+++ b/.github/skills/dotnet-sdk-builder/SKILL.md
@@ -1,12 +1,19 @@
 ---
 name: dotnet-sdk-builder
-description: Generates complete .NET SDK libraries with DI support, interfaces, typed HTTP clients, Options pattern, and typed exceptions. Use when asked to create a .NET SDK, build a .NET client library, wrap a REST API in C#, or generate a typed HTTP client. Invokes csharp-docs for XML documentation and tester for tests.
+description: Generates complete .NET SDK libraries with DI support, interfaces, typed HTTP clients, Options pattern, and typed exceptions. Use when asked to create a .NET SDK, build a .NET client library, wrap a REST API in C#, or generate a typed HTTP client. Invokes dotnet-xmldocs for XML documentation and dotnet-tester for tests.
 ---
 
 # .NET SDK Library Builder
 
 Generate complete, production-ready .NET SDK libraries from existing C# classes or API documentation. The output follows Microsoft's library design guidelines with full DI support, testability via interfaces, and idiomatic C# patterns.
 
+## When to Use
+
+- Building a new .NET SDK or client library from existing C# classes, OpenAPI/Swagger specs, or REST API docs
+- Wrapping a REST API in a typed C# client with DI registration (`AddXxx(...)`)
+- Generating typed HTTP clients with `IHttpClientFactory`, Options pattern, and typed exceptions
+- Producing libraries that follow Microsoft's library design guidelines (interface-first, no static state)
+
 ## Workflow Overview
 
 Follow these steps in order. See the reference files for detailed guidance on each phase.
@@ -92,26 +99,15 @@ Generate all components. See [di-patterns.md](references/di-patterns.md) and [ht
 | `XxxException` (+ subtypes) | Typed exceptions with diagnostic properties |
 | Model classes | Request/response DTOs |
 
-**NuGet packages to add:**
-
-```xml
-<PackageReference Include="Microsoft.Extensions.Http" Version="*" />
-<PackageReference Include="Microsoft.Extensions.Options" Version="*" />
-<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="*" />
-<!-- If resilience requested: -->
-<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="*" />
-```
-
-Always use the latest stable, compatible with target framework version.
-Always use skill 'nuget-manager' for managing NuGet packages and package versions. 
+**Required NuGet packages:** `Microsoft.Extensions.Http`, `Microsoft.Extensions.Options`, `Microsoft.Extensions.DependencyInjection.Abstractions` — plus `Microsoft.Extensions.Http.Resilience` if Step 5 selected resilience. Use the `dotnet-nuget-manager` skill to add them; do not edit `.csproj` directly.
 
 ### Step 8: Document the Code
 
-After generating all source files, invoke the `csharp-docs` skill to add XML documentation comments to all public types and members.
+After generating all source files, invoke the `dotnet-xmldocs` skill to add XML documentation comments to all public types and members.
 
 ### Step 9: Write Tests
 
-After documentation is complete, invoke the `tester` skill to generate unit and integration tests for the library.
+After documentation is complete, invoke the `dotnet-tester` skill to generate unit and integration tests for the library.
 
 ## Key Design Principles
 
@@ -127,3 +123,12 @@ After documentation is complete, invoke the `tester` skill to generate unit and
 - **[di-patterns.md](references/di-patterns.md)** — DI registration, Options pattern, extension method patterns
 - **[http-client-patterns.md](references/http-client-patterns.md)** — IHttpClientFactory, typed clients, resilience, typed exceptions
 - **[project-setup.md](references/project-setup.md)** — New project structure, folder layout, `.csproj` conventions
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Provides the DI, Options, and configuration patterns this skill emits in generated SDKs
+- **[dotnet-xmldocs](../dotnet-xmldocs/SKILL.md)** — Invoked in Step 8 to document generated SDKs with XML comments
+- **[dotnet-tester](../dotnet-tester/SKILL.md)** — Invoked in Step 9 to generate unit and integration tests
+- **[dotnet-nuget-manager](../dotnet-nuget-manager/SKILL.md)** — Invoked in Step 7 to add SDK runtime dependencies
+- **[dotnet-inspect](../dotnet-inspect/SKILL.md)** — Queries existing libraries when generating SDK wrappers
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Generates typed HTTP clients for consuming ASP.NET Core APIs
diff --git a/.github/skills/dotnet-sdk-builder/references/project-setup.md b/.github/skills/dotnet-sdk-builder/references/project-setup.md
index 4ffda6f..db141d3 100644
--- a/.github/skills/dotnet-sdk-builder/references/project-setup.md
+++ b/.github/skills/dotnet-sdk-builder/references/project-setup.md
@@ -36,7 +36,7 @@ Always ask the user for confirmation before creating a new project if not explic
 **Key settings:**
 - `<Nullable>enable</Nullable>` — always for new projects when .NET version supports it.
 - `<GenerateDocumentationFile>true</GenerateDocumentationFile>` — required for XML doc generation.
-- `<NoWarn>CS1591</NoWarn>` — suppress "missing XML comment" warnings during development; remove after `csharp-docs` skill adds all docs.
+- `<NoWarn>CS1591</NoWarn>` — suppress "missing XML comment" warnings during development; remove after `dotnet-xmldocs` skill adds all docs.
 - `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` — enforces code quality.
 - `<LangVersion>latest</LangVersion>` — enables the latest C# features for the target framework.
 
@@ -69,6 +69,8 @@ MyCompany.GitHub/
 - No `Services/` or `Abstractions/` sub-folders for small libraries — keep it flat.
 - For larger libraries with multiple API areas, group by area: `Repositories/`, `Users/`, etc.
 
+> This layout applies to **library** projects. Web/API applications should organize by feature/domain instead — see the `dotnet-aspnet` skill.
+
 ## Naming Conventions
 
 | Artifact | Pattern | Example |
diff --git a/.github/skills/dotnet-tester/SKILL.md b/.github/skills/dotnet-tester/SKILL.md
index dfb91ba..12775ff 100644
--- a/.github/skills/dotnet-tester/SKILL.md
+++ b/.github/skills/dotnet-tester/SKILL.md
@@ -3,8 +3,19 @@ name: dotnet-tester
 description: Writes, executes, and completes unit tests for C#/.NET code using xUnit, FakeItEasy, and AwesomeAssertions. Uses a second agent to identify missing test cases. Use when asked to create .NET tests or improve test coverage.
 ---
 
+# .NET Tester
+
 Write comprehensive unit tests for the specified code. Follow a multi-step process with automatic identification of missing test cases.
 
+## When to Use
+
+- User asks to create unit tests, add tests, or improve test coverage for C#/.NET code
+- New C#/.NET production code lacks tests and needs them
+- An existing test suite is missing edge cases or error-path coverage
+- Working in a C# project that uses xUnit, FakeItEasy, AwesomeAssertions/FluentAssertions, NUnit, MSTest, or Moq
+
+Do **not** use this skill for non-.NET test code, or for integration tests that primarily exercise external systems without unit-level concerns.
+
 ## Conventions
 
 - **Test Framework**: xUnit
@@ -12,7 +23,7 @@ Write comprehensive unit tests for the specified code. Follow a multi-step proce
 - **Assertions**: AwesomeAssertions (a fork of FluentAssertions with identical API — use `Should()` as usual)
 - **Structure**: Each test method has Arrange/Act/Assert blocks, marked with comments
 - **Language**: English for code, comments, and test names
-- **Style**: Adopt the existing test style from nearby test files in the project
+- **Style**: The stack above is the default. If the project already uses a different stack (NUnit, MSTest, Moq, FluentAssertions, …), match the existing convention instead of switching.
 
 ## Phase 1: Write Tests
 
@@ -113,8 +124,17 @@ At the end, provide a summary:
 ## Important Notes
 
 - Do **not write tests for trivial getters/setters** without logic
+- Do **not write tests to check if properties are initialized correctly after construction**
 - Do **not mock value types** or simple DTOs – create real instances
 - Test **behavior**, not implementation details
 - Use **descriptive test names** in the format `MethodName_Scenario_ExpectedBehavior`
 - For `[Theory]` tests: Use `[InlineData]` for simple types, `[MemberData]` for complex objects
 - Use `A.CallTo(...).MustHaveHappened()` sparingly – only when the call is the expected behavior
+
+## Related Skills
+
+- **[dotnet-fundamentals](../dotnet-fundamentals/SKILL.md)** — Test DI-registered services using `IServiceCollection` overrides
+- **[dotnet-ef-core](../dotnet-ef-core/SKILL.md)** — DbContext-backed unit and integration tests (SQLite in-memory, Testcontainers)
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Test-quality checks during code review
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invoked by it in Step 9 to generate tests for new SDK libraries
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — Unit and integration tests for ASP.NET Core endpoints
diff --git a/.github/skills/dotnet-xmldocs/SKILL.md b/.github/skills/dotnet-xmldocs/SKILL.md
new file mode 100644
index 0000000..b688596
--- /dev/null
+++ b/.github/skills/dotnet-xmldocs/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: dotnet-xmldocs
+description: Adds and reviews C# XML documentation comments following Microsoft's documentation standards. Use when writing or reviewing C# code that includes public APIs, complex logic, or when documentation is missing or insufficient. Covers <summary>, <param>, <returns>, <exception>, <remarks>, and all standard XML doc tags.
+---
+
+# C# Documentation Best Practices
+
+## When to Use
+
+- Writing or reviewing XML documentation comments (`///`) on C# types and members
+- Adding documentation to public APIs of a new or existing C# library
+- Reviewing missing, insufficient, or non-Microsoft-style XML docs in C# code
+- Generating documentation that feeds OpenAPI/Swagger output or NuGet symbols
+
+## General Guidelines
+
+- Public members should be documented with XML comments.
+- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.
+
+## Guidance for all APIs
+
+- Use `<summary>` to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb.
+- Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context.
+- Use `<see langword>` for language-specific keywords like `null`, `true`, `false`, `int`, `bool`, etc.
+- Use `<c>` for inline code snippets.
+- Use `<example>` for usage examples on how to use the member.
+  - Use `<code>` for code blocks. `<code>` tags should be placed within an `<example>` tag. Add the language of the code example using the `language` attribute, for example, `<code language="csharp">`.
+- Use `<see cref>` to reference other types or members inline (in a sentence).
+- Use `<seealso>` for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs.
+- Use `<inheritdoc/>` to inherit documentation from base classes or interfaces.
+  - Unless there is major behavior change, in which case you should document the differences.
+
+## Member-Specific Rules
+
+See [member-documentation-rules.md](./references/member-documentation-rules.md) for detailed wording conventions for methods (`<param>`, `<returns>`), constructors, properties (`<value>`, Gets/Sets patterns), and exceptions (`<exception cref>`).
+
+## Related Skills
+
+- **[dotnet-aspnet](../dotnet-aspnet/SKILL.md)** — XML docs feed OpenAPI/Swagger output
+- **[dotnet-sdk-builder](../dotnet-sdk-builder/SKILL.md)** — Invokes this skill in Step 8 to document generated SDKs
+- **[dotnet-reviewer](../dotnet-reviewer/SKILL.md)** — Code-quality checklist references these conventions for public-API docs
diff --git a/.github/skills/dotnet-xmldocs/references/member-documentation-rules.md b/.github/skills/dotnet-xmldocs/references/member-documentation-rules.md
new file mode 100644
index 0000000..8f58133
--- /dev/null
+++ b/.github/skills/dotnet-xmldocs/references/member-documentation-rules.md
@@ -0,0 +1,41 @@
+# Member-Specific Documentation Rules
+
+## Methods
+
+- Use `<param>` to describe method parameters.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...".
+  - If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...".
+  - If the parameter is a Boolean, the wording should be of the form "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`.".
+  - If the parameter is an "out" parameter, the wording should be of the form "When this method returns, contains .... This parameter is treated as uninitialized.".
+- Use `<paramref>` to reference parameter names in documentation.
+- Use `<typeparam>` to describe type parameters in generic types or methods.
+- Use `<typeparamref>` to reference type parameters in documentation.
+- Use `<returns>` to describe what the method returns.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the return type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`.".
+
+## Constructors
+
+- The summary wording should be "Initializes a new instance of the <Class> class [or struct].".
+
+## Properties
+
+- The `<summary>` should start with:
+  - "Gets or sets..." for a read-write property.
+  - "Gets..." for a read-only property.
+  - "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value.
+- Use `<value>` to describe the value of the property.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - If the property has a default value, add it in a separate sentence, for example, "The default is `<see langword="false" />`".
+  - If the value type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ...".
+
+## Exceptions
+
+- Use `<exception cref>` to document exceptions thrown by constructors, properties, indexers, methods, operators, and events.
+- Document all exceptions thrown directly by the member.
+- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter.
+- The description of the exception describes the condition under which it's thrown.
+  - Omit "Thrown if ..." or "If ..." at the beginning of the sentence. Just state the condition directly, for example "An error occurred when accessing a Message Queuing API."
diff --git a/.github/skills/dotnet/SKILL.md b/.github/skills/dotnet/SKILL.md
new file mode 100644
index 0000000..6766638
--- /dev/null
+++ b/.github/skills/dotnet/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: dotnet
+description: Entry point and router for .NET and C# work — directs you to the right specialized .NET skill. Use when a request mentions .NET or C# in general but the specific tool is not obvious, or to get an overview of the available .NET skills. Routes to knowledge skills (dotnet-fundamentals, dotnet-aspnet, dotnet-ef-core, dotnet-xmldocs) and workflow skills (dotnet-sdk-builder, dotnet-tester, dotnet-reviewer, dotnet-inspect, dotnet-nuget-manager). When the matching skill is already clear, invoke that skill directly instead.
+---
+
+# .NET / C# Skill Router
+
+Signpost to the specialized .NET skills. This skill holds no best-practice knowledge
+of its own — it maps a request to the appropriate specialized skill.
+
+## When to Use
+
+- A task concerns .NET or C#, but it is unclear which specialized skill applies.
+- You need an overview of the available .NET skills and their responsibilities.
+
+When the matching skill is already clear, load it directly — the router is only
+orientation, not an intermediate step.
+
+## Routing
+
+### Knowledge skills (best practices, `references/` only)
+
+| Concern | Skill |
+|---------|-------|
+| Dependency Injection, Options pattern, Configuration, modern C# idioms (for any .NET host) | `dotnet-fundamentals` |
+| ASP.NET Core Web/REST APIs: controllers, Minimal APIs, middleware, routing, model binding, validation, auth, ProblemDetails, OpenAPI, health checks, CORS, rate limiting | `dotnet-aspnet` |
+| Entity Framework Core: DbContext, entities/relationships, LINQ, migrations, repository patterns, N+1/performance | `dotnet-ef-core` |
+| C# XML doc comments (`<summary>`, `<param>`, `<returns>`, …) | `dotnet-xmldocs` |
+
+### Workflow skills (active tools, scripts, agents)
+
+| Concern | Skill |
+|---------|-------|
+| Generate a .NET SDK / client library / typed HTTP client | `dotnet-sdk-builder` |
+| Write/run unit tests (xUnit, FakeItEasy, AwesomeAssertions) | `dotnet-tester` |
+| Structured code review for .NET 10+ (explicit invocation only, see below) | `dotnet-reviewer` |
+| Query .NET APIs in NuGet packages, platform libraries, or local files | `dotnet-inspect` |
+| Manage NuGet packages (add/remove/update, `--outdated`, Central Package Management) | `dotnet-nuget-manager` |
+
+## Notes
+
+- **`dotnet-reviewer` activates only on explicit name** — the phrases
+  `dotnet-reviewer`, `dotnet code review`, or `dotnet review`. It does **not** trigger
+  on generic "review my code", and the router does not trigger it automatically.
+- **Composition:** `dotnet-sdk-builder` invokes `dotnet-xmldocs` and `dotnet-tester`;
+  `dotnet-aspnet` and `dotnet-ef-core` build on `dotnet-fundamentals`.
diff --git a/.github/skills/implementer/SKILL.md b/.github/skills/implementer/SKILL.md
new file mode 100644
index 0000000..d1f0aa7
--- /dev/null
+++ b/.github/skills/implementer/SKILL.md
@@ -0,0 +1,255 @@
+---
+name: implementer
+description: >
+  Iterative implementation workflow for requirements. Use this skill when asked to
+  implement a feature, user story, requirement, or change request. Guides through
+  5 phases: requirement review, implementation planning, sub-agent-driven implementation
+  (code, tests, documentation), code review with rework loop, and final summary.
+  Never commits code — the user always commits manually.
+allowed-tools: Read Grep Glob Edit Create Task
+---
+
+# Implementer — Iterative Requirement Implementation Flow
+
+An iterative, structured workflow for implementing requirements end-to-end.
+Covers production code, tests, and documentation updates in every cycle.
+
+> **CRITICAL RULE — NO COMMITS:** You must NEVER commit code or create git commits.
+> The user always commits manually. If asked to commit, skip that request and inform
+> the user that committing is their responsibility.
+
+> **CRITICAL RULE — USE SPECIALIZED SKILLS:** Never implement, test, document, or review
+> with only your built-in knowledge when a specialized skill for the detected technology
+> exists. Discover available skills at runtime and use them. This skill names NO concrete
+> skills on purpose — it works with whatever skills exist now or are added later.
+
+## Flow Overview
+
+```
+Phase 1: Requirement Review
+    ↓
+Phase 2: Implementation Plan
+    ↓
+Phase 3: Implementation (Sub-Agents) ◄──┐
+    ↓                                    │
+Phase 4: Review (Sub-Agent)              │
+    ↓ (rework needed?)──────────────────►┘
+    ↓ (all good)
+Phase 5: Summary
+```
+
+## Skill Discovery & Capability Slots
+
+This workflow relies on **discovering specialized skills at runtime** rather than naming
+them. Concrete skill names change over time — names are never hardcoded here.
+
+**How discovery works:**
+
+1. **Detect the tech stack** by *signals* (manifest/build files, source extensions, configs),
+   per affected file/module — repos may mix stacks. Examples like `*.csproj` → .NET or
+   `package.json` → TypeScript are illustrative only; infer any stack from its signals
+   (see [Phase 1.5](references/REFERENCE.md#phase-15)).
+2. **List the available skills** using your runtime's skill-listing mechanism (do not assume
+   a fixed directory).
+3. **Classify each skill by its `description`** — match purpose and technology from the text,
+   never from the name — and fill these **capability slots**:
+
+| Slot | Filled by a skill whose description covers… | Used in |
+|------|---------------------------------------------|---------|
+| `language-implementation` | writing code for the detected stack | Phase 3 |
+| `language-testing` | the stack's test framework / test conventions | Phase 3 |
+| `language-docs` | the stack's documentation conventions | Phase 3 |
+| `language-review` | reviewing code for the detected stack | Phase 4 |
+| `build-deps` | builds / package & dependency management | Phase 3 |
+
+Always show the capability slots to the user.
+**Usage rule:** If a slot is filled, you MUST use that skill for the matching work and pass
+it as context to any sub-agent doing that work (sub-agents are stateless). If no skill
+matches a slot, fall back to generic conventions and note the empty slot in the plan. if you delegate work to a sub-agent,
+you MUST pass the slot skill explicitly.
+
+**Slot fulfillment is by invocation, not by listing.** A capability slot counts as fulfilled
+only when its skill has been invoked via the `Skill` tool **in this conversation, for this
+task**. Listing a skill in the slot table, paraphrasing its description, or relying on prior
+knowledge of the technology does NOT count as fulfillment. The rule is identical whether you
+do the work yourself or dispatch a sub-agent — self-execution does not waive the
+invocation, and a sub-agent invocation does not waive it for the main agent's own
+follow-up edits.
+
+**A single task may have multiple slots filled at once** (e.g. implementation + testing +
+documentation in one task, or two language-implementation slots when a stack mixes
+sub-technologies). In that case every assigned slot must be invoked independently — one
+slot's invocation never substitutes for another's, and you must not collapse the
+invocations even when the same task touches all of them. Invocations from a previous task
+do NOT carry over either; re-invoke at the start of every task where the slot applies.
+
+## Phase 1 — Requirement Review
+
+Analyze the requirement before any code is written:
+
+1. Read and understand the requirement thoroughly
+2. Identify acceptance criteria (explicit and implicit)
+3. Clarify ambiguities — ask the user targeted questions using the ask_user tool
+4. Identify affected components, files, and modules in the current codebase
+5. Check for existing tests, documentation, and related code
+6. **Detect the tech stack and run skill discovery** (see *Skill Discovery & Capability
+   Slots*): build the capability-slot map for the affected areas
+
+**Output:** Confirmed understanding of the requirement, resolved ambiguities, identified
+scope, and the filled capability-slot map (with any empty slots noted).
+
+## Phase 2 — Implementation Plan
+
+Create a structured plan with trackable tasks:
+
+1. Break the requirement into discrete implementation tasks
+2. Each task MUST include all three aspects:
+  - **Production code** changes
+  - **Test** additions or updates
+  - **Documentation** updates (if applicable)
+3. **Each task MUST publish a Skill-prerequisite checklist** listing every capability slot
+   it depends on (from the Phase 1 discovery). The checklist is part of the plan text the
+   user sees; it is not optional, and it is not collapsed even when a task touches every
+   slot. The format is:
+
+   ```
+   Task #N: <subject>
+     Skill prerequisites (Step 0 of Phase 3):
+       [ ] <slot-id>            — filled by "<skill name from discovery>"
+       [ ] <other-slot-id>      — filled by "<other skill name>"
+       [ ] <slot-id-with-gap>   — EMPTY (no matching skill; generic fallback)
+   ```
+
+   When Step 0 fires in Phase 3, each `[ ]` is replaced with `[x]` (or annotated with
+   "n/a — slot empty" for empty slots). Multiple skills filling the same slot get their own
+   line each. The same skill appearing in two different slots is two separate
+   prerequisites — never deduplicated.
+4. Define task dependencies (what must be done first)
+5. Identify tasks that can be parallelized via sub-agents
+
+**Output:** Task list with dependencies and a per-task Skill-prerequisite checklist, ready
+for implementation. Any task missing its checklist is not a valid plan entry.
+
+## Phase 3 — Implementation
+
+Execute tasks using sub-agents for parallel work where possible:
+
+1. For each task (or group of independent tasks):
+  - **Step 0 — invoke every assigned slot skill.** Before any `Write`, `Edit`, or
+    code-producing `Bash` call for this task, call the `Skill` tool **once per capability
+    slot** the task is assigned to. If the task has multiple slots (e.g.
+    `language-implementation` + `language-testing` + `language-docs` at the same time, or
+    two slots of the same kind), invoke them all — one invocation never substitutes for
+    another. Wait for each skill's content to load and follow its workflow when producing
+    the corresponding artifact. A skill invocation made for a previous task does NOT carry
+    over; re-invoke per task.
+  - Delegate to sub-agents (explore for research, task for builds/tests, general-purpose
+    for complex changes), passing the relevant slot skill(s) as context. Sub-agent
+    dispatch is in addition to — not instead of — Step 0: the main agent still needs the
+    slot's workflow loaded for any follow-up edits it makes itself.
+  - Implement production code changes using the skill(s) filling the
+    `language-implementation` slot.
+  - Write or update tests using the skill(s) filling the `language-testing` slot.
+  - Update relevant documentation using the skill(s) filling the `language-docs` slot.
+2. Run existing tests and linters to verify changes don't break anything (use the
+   `build-deps` slot if filled — invoke it the same way as any other slot).
+3. Track task completion status. Only mark a task `completed` once every slot assigned to
+   it has been invoked AND the corresponding artifact (code / tests / docs) has been
+   produced or explicitly recorded as not-applicable for this task.
+
+**Important:** Respect the project's existing conventions, patterns, and tooling. If a
+capability slot is filled, you MUST use it; only fall back to generic work when the slot is
+empty.
+
+### Worked example — beginning a task with multiple slots
+
+Suppose Task #N has three slots assigned: `language-implementation`, `language-testing`,
+and `language-docs`, each filled by some discovered skill. The correct opening of the task
+looks like this (skill names are placeholders — substitute whatever Phase 1 discovery
+produced for each slot):
+
+```
+TaskUpdate(taskId=N, status=in_progress)
+Skill(skill="<skill filling language-implementation>")   ← MUST fire before production-code Write/Edit
+Skill(skill="<skill filling language-testing>")          ← MUST fire before test-code Write/Edit
+Skill(skill="<skill filling language-docs>")             ← MUST fire before doc Write/Edit
+# ...follow each invoked skill's workflow...
+Write(file_path=".../<production file>", content=...)
+Write(file_path=".../<test file>",       content=...)
+Edit(file_path=".../<doc file>",         ...)
+```
+
+Notes:
+
+- Three slots → three `Skill(...)` calls. Two slots → two calls. Five → five. No collapsing.
+- If you dispatch a sub-agent for one of the slots, the `Skill(...)` call still happens
+  here in the main conversation first, and the slot skill name is also passed to the
+  sub-agent prompt.
+- Omitting any `Skill(...)` line above is exactly the failure mode the rules in this
+  section exist to prevent.
+
+## Phase 4 — Review
+
+Run a thorough code review using a sub-agent:
+
+1. Launch a code-review sub-agent to analyze all changes made. If the `language-review` slot
+   is filled, use that skill (it knows stack-specific pitfalls); otherwise use a generic
+   review. When both a stack-specific and a generic review skill exist, combine them.
+2. The review checks for:
+  - Correctness and completeness against the requirement
+  - Test coverage for new/changed code
+  - Documentation accuracy
+  - Code quality, potential bugs, and security issues
+3. Evaluate review findings:
+  - **Rework needed:** Create new tasks for findings and return to **Phase 3**
+  - **All good:** Proceed to **Phase 5**
+
+## Phase 5 — Summary
+
+Provide a comprehensive summary of all work done:
+
+1. List all files created or modified
+2. Describe what was implemented and why
+3. List all tests added or updated
+4. List all documentation changes
+5. Note any decisions made during implementation
+6. Highlight anything the user should review before committing
+7. **Publish the Skill-invocation log.** For every task in the plan, reproduce the
+   Skill-prerequisite checklist from Phase 2 with each entry resolved. Each line MUST
+   carry one of three states, with evidence:
+
+  - `[x] <slot-id> — invoked at <evidence>` — `<evidence>` is a verifiable pointer such
+    as "turn N", "before Write of `<file>`", or the exact `Skill(skill="…")` call. Generic
+    phrases like "considered" or "applied" are NOT acceptable evidence.
+  - `[n/a] <slot-id> — empty in Phase 1 discovery; generic fallback used` — only valid
+    when Phase 1 left the slot empty.
+  - `[!] <slot-id> — NOT invoked` — a workflow violation. Whenever this state appears you
+    MUST (a) name it explicitly here as a violation, (b) NOT mark the affected task as
+    truly complete in your prose summary, and (c) recommend a concrete follow-up pass
+    that re-runs the missing slot's workflow on the produced artifact.
+
+   The log is mandatory even when every slot was invoked correctly — it serves as the
+   audit trail for the user. If the plan contained no tasks (e.g. requirement was a
+   no-op), state that explicitly instead of omitting the log.
+
+> **Reminder:** The user will commit the changes themselves. Do NOT create any commits.
+
+## Red Flags — Do Not Skip Specialized Skills
+
+If you catch yourself thinking any of these, STOP and use the discovered slot skill:
+
+| Rationalization | Reality |
+|-----------------|---------|
+| "I already know this language well" | The skill may encode project-specific conventions you don't know. Consult it. |
+| "It's a tiny change, no skill needed" | Small changes still follow the stack's patterns. Use the slot. |
+| "I'll just use the generic approach" | Generic is the fallback ONLY when no slot skill exists. |
+| "Discovery takes too long" | Discovery is one listing + classification. Skipping it produces off-convention code. |
+| "The sub-agent will figure it out" | Sub-agents are stateless — pass them the slot skill explicitly. |
+| "I already listed the slot in the plan" | A listed slot is not an invoked skill. The slot is only fulfilled when the `Skill` tool has fired in this conversation for this task. |
+| "I'll just do this small bit myself instead of dispatching" | Self-execution does NOT waive the slot requirement. Invoke the slot skill first, then write. |
+| "One slot covers everything in this task" | Each filled slot is its own workflow. Implementation, testing, documentation, build, and review slots must each be invoked when assigned — never collapse them. |
+| "The slot was invoked in the previous task" | Invocations do NOT carry over between tasks. Re-invoke at the start of every task the slot applies to. |
+
+---
+
+For detailed guidance on each phase, see [references/REFERENCE.md](references/REFERENCE.md).
diff --git a/.github/skills/implementer/references/REFERENCE.md b/.github/skills/implementer/references/REFERENCE.md
new file mode 100644
index 0000000..261b37e
--- /dev/null
+++ b/.github/skills/implementer/references/REFERENCE.md
@@ -0,0 +1,326 @@
+# Implementer Skill — Detailed Reference
+
+This document provides in-depth guidance for each phase of the implementer workflow.
+
+---
+
+## Phase 1 — Requirement Review (Detail)
+
+### Goal
+
+Ensure a thorough understanding of the requirement before any implementation begins.
+Prevent wasted effort from misunderstood requirements or unclear scope.
+
+### Steps
+
+#### 1.1 Read the Requirement
+
+- Read the full requirement text (issue, user story, ticket, or user message)
+- Identify the core objective: What should change? What is the expected outcome?
+
+#### 1.2 Identify Acceptance Criteria
+
+- Extract explicit acceptance criteria from the requirement
+- Derive implicit criteria from context (e.g., existing tests must still pass, existing API contracts must be honored)
+- List edge cases that should be covered
+
+#### 1.3 Clarify Ambiguities
+
+- If anything is unclear, use the `ask_user` tool to ask targeted questions
+- Do NOT assume answers to ambiguous requirements — always ask
+- Common ambiguities to watch for:
+  - Scope boundaries (what is in/out)
+  - Error handling behavior
+  - Performance expectations
+  - Backward compatibility requirements
+
+#### 1.4 Analyze the Codebase
+
+- Identify files, modules, and components affected by the requirement
+- Understand the existing architecture and patterns in the affected area
+- Look for existing tests that cover the affected area
+- Check for documentation that needs updating
+- Use explore sub-agents for large codebase investigations
+
+#### 1.5 Detect Stack & Discover Skills
+
+This step builds the **capability-slot map** used by all later phases. Never hardcode skill
+names — classify by each skill's `description`.
+
+1. **Detect the tech stack** per affected file/module (repos may be multi-stack). Detect by
+   *signals*, not a fixed list — this keeps detection working for stacks not yet imagined:
+   - **Manifest / build files** declaring language, dependencies, or build config
+     (e.g. a `*.csproj`, `pom.xml`/`build.gradle`, `package.json`, `pyproject.toml`,
+     `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`). These are the strongest signal.
+   - **Source file extensions** of the affected files (e.g. `.cs`, `.java`, `.ts`, `.go`).
+   - **Lockfiles, toolchain configs, and CI files** that name a runtime or framework.
+   - **Framework markers** inside manifests/configs (a dependency name often identifies the
+     framework, not just the language).
+
+   The list above is illustrative, not exhaustive. The rule is: infer language + framework
+   from whatever build/manifest/config/source signals are present, then map that stack to
+   capability slots — regardless of whether this skill ever mentioned that stack.
+2. **List the available skills** using your runtime's own skill-listing mechanism. Do NOT
+   assume a fixed directory — the location varies across platforms (Claude Code, Copilot,
+   Codex) and across repos.
+3. **Classify each skill by its `description`** and fill the capability slots:
+   `language-implementation`, `language-testing`, `language-docs`, `language-review`,
+   `build-deps`. Match on purpose + technology mentioned in the description, never on name.
+4. For multi-stack repos, maintain a slot map **per stack** and select the right one per task.
+5. Review instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) and
+   follow any project conventions and coding standards found.
+
+Record empty slots explicitly — they mean "use the generic fallback" for that work.
+
+### Output
+
+Present the user with:
+- A summary of the requirement in your own words
+- The identified acceptance criteria
+- Any clarifying questions (if applicable)
+- The affected areas of the codebase
+- The detected tech stack(s) and the filled capability-slot map (note any empty slots)
+
+Wait for user confirmation before proceeding to Phase 2.
+
+---
+
+## Phase 2 — Implementation Plan (Detail)
+
+### Goal
+
+Create a clear, trackable plan that breaks the requirement into discrete tasks.
+Each task should be self-contained and include code, tests, and documentation.
+
+### Steps
+
+#### 2.1 Define Tasks
+
+- Break the requirement into the smallest reasonable tasks
+- Each task should be completable independently (or with clear dependencies)
+- Use descriptive kebab-case IDs for task tracking
+- Every task description must include enough detail to execute without referring back to the plan
+
+#### 2.2 Task Structure
+
+Each task MUST address these three aspects:
+
+1. **Production Code:** What code changes are needed?
+2. **Tests:** What tests must be written or updated?
+3. **Documentation:** What documentation needs updating? (can be "none" if truly not applicable)
+
+Each task MUST also record its **capability slots** (from Phase 1.5), e.g.
+`language-implementation`, `language-testing`, `language-docs`, `build-deps`. If a needed
+slot is empty, mark it as "generic fallback" so the gap is visible in the plan.
+
+#### 2.3 Dependencies
+
+- Identify which tasks depend on others
+- Tasks without dependencies can be parallelized
+- Common dependency patterns:
+  - Data model changes before API changes
+  - Core logic before integration
+  - Shared utilities before consumers
+
+#### 2.4 Parallelization Strategy
+
+- Group independent tasks for parallel execution via sub-agents
+- Consider resource constraints (e.g., database schema changes should not be parallelized)
+- Prefer smaller, focused sub-agent tasks over large monolithic ones
+
+### Output
+
+Present the user with:
+- The complete task list with descriptions and per-task capability-slot assignments
+- A dependency graph (which tasks block which)
+- The planned execution order
+- Which tasks will be parallelized
+
+Wait for user confirmation before proceeding to Phase 3.
+
+---
+
+## Phase 3 — Implementation (Detail)
+
+### Goal
+
+Execute the implementation plan using sub-agents for efficient parallel work.
+
+### Steps
+
+#### 3.1 Task Execution
+
+For each task (or parallel group of independent tasks):
+
+1. **Update task status** to `in_progress`
+2. **Choose the right sub-agent type:**
+   - `explore` — For codebase research and analysis
+   - `task` — For running builds, tests, linters (returns brief summary on success, full output on failure)
+   - `general-purpose` — For complex multi-step code changes
+3. **Provide complete context** to the sub-agent:
+   - What to implement
+   - Which files to modify
+   - What tests to write
+   - What conventions to follow
+   - The capability-slot skill(s) assigned to this task — pass them explicitly, since
+     sub-agents are stateless and cannot discover your slot map on their own
+4. **Review sub-agent output** before moving to next task
+5. **Update task status** to `done`
+
+#### 3.2 Code Quality
+
+- **Use the `language-implementation` slot skill** if filled; only write code from generic
+  knowledge when the slot is empty
+- Follow existing code style and conventions
+- Do not introduce new dependencies unless explicitly required
+- Keep changes minimal and focused on the requirement
+- Use existing patterns found in the codebase
+
+#### 3.3 Testing
+
+- **Use the `language-testing` slot skill** if filled (it knows the stack's test framework
+  and conventions); only fall back to generic testing when the slot is empty
+- Write tests that cover the new/changed behavior
+- Ensure existing tests still pass
+- Cover edge cases identified in Phase 1
+
+#### 3.4 Documentation
+
+- **Use the `language-docs` slot skill** if filled (e.g. the stack's doc-comment conventions);
+  only fall back to generic documentation when the slot is empty
+- Update inline code documentation where needed
+- Update README or other docs if the change affects usage
+- Keep documentation changes in sync with code changes
+
+#### 3.5 Verification
+
+After all tasks are complete:
+- Run the full test suite using a `task` sub-agent (use the `build-deps` slot skill for the
+  correct build/test commands if filled)
+- Run any existing linters or type checkers
+- Fix any failures before proceeding
+
+### Important Constraints
+
+- **NEVER commit code.** The user will commit when ready.
+- **NEVER skip tests.** Every code change must have corresponding tests.
+- **Respect existing patterns.** Do not refactor unrelated code.
+
+---
+
+## Phase 4 — Review (Detail)
+
+### Goal
+
+Ensure implementation quality through an automated code review before the user commits.
+
+### Steps
+
+#### 4.1 Launch Code Review
+
+Launch a code-review sub-agent with these instructions:
+- If the `language-review` slot is filled, use that skill (stack-specific pitfalls); if a
+  generic review skill also exists, combine both. Use generic-only when no slot is filled.
+- Review ALL changes made during this implementation session
+- Compare changes against the original requirement and acceptance criteria
+- Focus on substantive issues only (not style or formatting)
+
+#### 4.2 Review Criteria
+
+The review sub-agent checks for:
+
+1. **Correctness:** Does the implementation satisfy the requirement and all acceptance criteria?
+2. **Completeness:** Are there missing edge cases, error handling, or untested paths?
+3. **Test Coverage:** Do tests adequately cover the new/changed code?
+4. **Documentation:** Is documentation accurate and up to date?
+5. **Code Quality:** Are there bugs, security issues, or logic errors?
+6. **Consistency:** Does the code follow project conventions and patterns?
+
+#### 4.3 Evaluate Findings
+
+After the review:
+
+- **No issues found:** Proceed to Phase 5
+- **Minor issues found:** Fix them directly, then proceed to Phase 5
+- **Significant issues found:**
+  1. Create new tasks for each finding
+  2. Return to Phase 3 to address them
+  3. After fixing, run Phase 4 again (rework loop)
+
+#### 4.4 Rework Loop
+
+The rework loop (Phase 3 → Phase 4) continues until:
+- The review finds no significant issues
+- OR the user explicitly approves the current state
+
+There is no hard limit on rework iterations, but if the same issues recur after 2 rework cycles, consult the user for guidance.
+
+---
+
+## Phase 5 — Summary (Detail)
+
+### Goal
+
+Provide a clear, comprehensive summary so the user knows exactly what was done and can review before committing.
+
+### Steps
+
+#### 5.1 Change Summary
+
+Create a structured summary containing:
+
+1. **Requirement:** Brief restatement of the original requirement
+2. **Files Modified:** List all files that were created or changed
+3. **Implementation Details:** What was implemented and key design decisions
+4. **Tests Added/Updated:** List all test files and what they cover
+5. **Documentation Changes:** List all documentation updates
+6. **Decisions Made:** Any design decisions or trade-offs during implementation
+7. **Review Notes:** Key points from the review phase
+8. **Things to Check:** Anything the user should manually verify before committing
+
+#### 5.2 Final Reminder
+
+End with a clear reminder:
+
+> All changes are ready for your review. When you are satisfied, please commit
+> the changes yourself. The AI will not create any commits.
+
+---
+
+## General Guidelines
+
+### Sub-Agent Best Practices
+
+- Always provide **complete context** to sub-agents (they are stateless)
+- Use `explore` agents for research, `task` agents for builds/tests, `general-purpose` for complex changes
+- Launch independent tasks in **parallel** for efficiency
+- Review sub-agent output before acting on it
+
+### Git and Commit Rules
+
+- **NEVER** run `git commit`, `git add`, or any commit-related commands
+- **NEVER** create branches, tags, or push to remotes
+- If the user or a tool requests a commit, **skip it** and inform the user:
+  *"Committing is your responsibility. I've skipped this commit request."*
+- You MAY use `git diff`, `git status`, `git log`, and other read-only git commands for analysis
+
+### Handling Project-Specific Conventions
+
+- Always check for instruction files at the start (CLAUDE.md, AGENTS.md, etc.)
+- Run skill discovery (Phase 1.5) and use the resulting capability slots — never hardcode
+  skill names, so the workflow keeps working as skills are added or renamed
+- Follow the project's existing patterns for code style, testing, and documentation
+- When in doubt, ask the user about project conventions
+
+### Capability Slots — Quick Reference
+
+| Slot | Purpose | Phase |
+|------|---------|-------|
+| `language-implementation` | writing code for the detected stack | 3.2 |
+| `language-testing` | the stack's test framework / conventions | 3.3 |
+| `language-docs` | the stack's documentation conventions | 3.4 |
+| `language-review` | stack-specific code review | 4 |
+| `build-deps` | build, package & dependency management | 3.5 |
+
+**Rule:** A filled slot MUST be used (and passed to sub-agents); an empty slot means generic
+fallback. Classify skills into slots by their `description`, never by name.
diff --git a/.github/skills/refactoring/SKILL.md b/.github/skills/refactoring/SKILL.md
index 83e126c..57cc674 100644
--- a/.github/skills/refactoring/SKILL.md
+++ b/.github/skills/refactoring/SKILL.md
@@ -4,8 +4,8 @@ description: Refactors existing code to improve structure, readability, and main
 ---
 
 # Refactoring Skill
-
-Unless explicitly asked to refactor code directly, generate a refactoring plan first and only apply it if the user approves.
+- Use language-specific skills when ever possible.
+- Unless explicitly asked to refactor code directly, generate a refactoring plan first and only apply it if the user approves.
 
 ## Workflow
 
diff --git a/.github/skills/writing-skills/SKILL.md b/.github/skills/writing-skills/SKILL.md
index c3b73d8..b3c2de6 100644
--- a/.github/skills/writing-skills/SKILL.md
+++ b/.github/skills/writing-skills/SKILL.md
@@ -93,7 +93,7 @@ skills/
 ## SKILL.md Structure
 
 **Frontmatter (YAML):**
-- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
+- Two required fields: `name` and `description` (see [agentskills.io/specification](./references/agentskills-specification.md) for all supported fields)
 - Max 1024 characters total
 - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
 - `description`: Third-person, describes ONLY when to use (NOT what it does)
@@ -604,7 +604,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 
 **GREEN Phase - Write Minimal Skill:**
 - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
-- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
+- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](./references/agentskills-specification.md))
 - [ ] Description starts with "Use when..." and includes specific triggers/symptoms
 - [ ] Description written in third person
 - [ ] Keywords throughout for search (errors, symptoms, tools)
diff --git a/.github/skills/writing-skills/anthropic-best-practices.md b/.github/skills/writing-skills/anthropic-best-practices.md
index 9f3f6ec..2ff406d 100644
--- a/.github/skills/writing-skills/anthropic-best-practices.md
+++ b/.github/skills/writing-skills/anthropic-best-practices.md
@@ -10,7 +10,7 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs
 
 ### Concise is key
 
-The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
+The [context window](./references/context-windows.md) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
 
 * The system prompt
 * Conversation history
@@ -246,11 +246,11 @@ SKILL.md serves as an overview that points Claude to detailed materials as neede
 
 A basic Skill starts with just a SKILL.md file containing metadata and instructions:
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
+![Simple SKILL.md file showing YAML frontmatter and markdown body](./assets/agent-skills-simple-file.png)
 
 As your Skill grows, you can bundle additional content that Claude loads only when needed:
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
+![Bundling additional reference files like reference.md and forms.md.](./assets/agent-skills-bundling-content.png)
 
 The complete Skill directory structure might look like this:
 
@@ -916,7 +916,7 @@ Even if Claude could write a script, pre-made scripts offer advantages:
 * Save time (no code generation required)
 * Ensure consistency across uses
 
-<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
+![Bundling executable scripts alongside instruction files](./assets/agent-skills-executable-scripts.png)
 
 The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
 
diff --git a/.github/skills/writing-skills/assets/agent-skills-bundling-content.png b/.github/skills/writing-skills/assets/agent-skills-bundling-content.png
new file mode 100644
index 0000000..08cfa9e
Binary files /dev/null and b/.github/skills/writing-skills/assets/agent-skills-bundling-content.png differ
diff --git a/.github/skills/writing-skills/assets/agent-skills-executable-scripts.png b/.github/skills/writing-skills/assets/agent-skills-executable-scripts.png
new file mode 100644
index 0000000..044f3e1
Binary files /dev/null and b/.github/skills/writing-skills/assets/agent-skills-executable-scripts.png differ
diff --git a/.github/skills/writing-skills/assets/agent-skills-simple-file.png b/.github/skills/writing-skills/assets/agent-skills-simple-file.png
new file mode 100644
index 0000000..8c72e51
Binary files /dev/null and b/.github/skills/writing-skills/assets/agent-skills-simple-file.png differ
diff --git a/.github/skills/writing-skills/references/agentskills-specification.md b/.github/skills/writing-skills/references/agentskills-specification.md
new file mode 100644
index 0000000..4ee41da
--- /dev/null
+++ b/.github/skills/writing-skills/references/agentskills-specification.md
@@ -0,0 +1,193 @@
+# Agent Skills Specification
+
+> The complete format specification for Agent Skills.
+
+## Directory Structure
+
+A skill is a directory containing, at minimum, a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+## `SKILL.md` Format
+
+The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
+
+### Frontmatter
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
+| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
+| `license` | No | License name or reference to a bundled license file. |
+| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
+| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
+| `allowed-tools` | No | Space-separated string of pre-approved tools the skill may use. (Experimental) |
+
+**Minimal example:**
+
+```markdown
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+**Example with optional fields:**
+
+```markdown
+---
+name: pdf-processing
+description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: "1.0"
+---
+```
+
+### `name` Field
+
+- Must be 1-64 characters
+- May only contain unicode lowercase alphanumeric characters (`a-z`) and hyphens (`-`)
+- Must not start or end with a hyphen (`-`)
+- Must not contain consecutive hyphens (`--`)
+- Must match the parent directory name
+
+**Valid:** `pdf-processing`, `data-analysis`, `code-review`
+**Invalid:** `PDF-Processing` (uppercase), `-pdf` (starts with hyphen), `pdf--processing` (consecutive hyphens)
+
+### `description` Field
+
+- Must be 1-1024 characters
+- Should describe both what the skill does and when to use it
+- Should include specific keywords that help agents identify relevant tasks
+
+**Good:** `Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.`
+
+**Poor:** `Helps with PDFs.`
+
+### `license` Field
+
+- Specifies the license applied to the skill
+- Keep short: either the name of a license or the name of a bundled license file
+
+```yaml
+license: Proprietary. LICENSE.txt has complete terms
+```
+
+### `compatibility` Field
+
+- Must be 1-500 characters if provided
+- Only include if your skill has specific environment requirements
+
+```yaml
+compatibility: Designed for Claude Code (or similar products)
+compatibility: Requires git, docker, jq, and access to the internet
+compatibility: Requires Python 3.14+ and uv
+```
+
+> Most skills do not need the `compatibility` field.
+
+### `metadata` Field
+
+- A map from string keys to string values
+- Used for additional properties not defined by the spec
+
+```yaml
+metadata:
+  author: example-org
+  version: "1.0"
+```
+
+### `allowed-tools` Field
+
+- A space-separated string of tools that are pre-approved to run
+- Experimental. Support may vary between agent implementations
+
+```yaml
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+```
+
+### Body Content
+
+The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
+
+Recommended sections:
+
+- Step-by-step instructions
+- Examples of inputs and outputs
+- Common edge cases
+
+Consider splitting longer `SKILL.md` content into referenced files.
+
+## Optional Directories
+
+### `scripts/`
+
+Contains executable code that agents can run. Scripts should:
+
+- Be self-contained or clearly document dependencies
+- Include helpful error messages
+- Handle edge cases gracefully
+
+### `references/`
+
+Contains additional documentation that agents can read when needed:
+
+- `REFERENCE.md` - Detailed technical reference
+- `FORMS.md` - Form templates or structured data formats
+- Domain-specific files (`finance.md`, `legal.md`, etc.)
+
+Keep individual reference files focused. Agents load these on demand.
+
+### `assets/`
+
+Contains static resources:
+
+- Templates (document templates, configuration templates)
+- Images (diagrams, examples)
+- Data files (lookup tables, schemas)
+
+## Progressive Disclosure
+
+Skills should be structured for efficient use of context:
+
+1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills
+2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
+3. **Resources** (as needed): Files in `scripts/`, `references/`, or `assets/` are loaded only when required
+
+Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
+
+## File References
+
+When referencing other files in your skill, use relative paths from the skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Validation
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
+
+```bash
+skills-ref validate ./my-skill
+```
+
+This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
+
+---
+
+Source: https://agentskills.io/specification
diff --git a/.github/skills/writing-skills/references/context-windows.md b/.github/skills/writing-skills/references/context-windows.md
new file mode 100644
index 0000000..47d21a9
--- /dev/null
+++ b/.github/skills/writing-skills/references/context-windows.md
@@ -0,0 +1,66 @@
+# Context Windows
+
+As conversations grow, you'll eventually approach context window limits. This guide explains how context windows work and introduces strategies for managing them effectively.
+
+## Understanding the Context Window
+
+The "context window" refers to all the text a language model can reference when generating a response, including the response itself. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to handle more complex and lengthy prompts, but more context isn't automatically better. As token count grows, accuracy and recall degrade, a phenomenon known as *context rot*. This makes curating what's in context just as important as how much space is available.
+
+> **Tip:** For a deep dive into why long contexts degrade and how to engineer around it, see "Effective context engineering" from Anthropic.
+
+## Key Concepts
+
+- **Progressive token accumulation:** As the conversation advances through turns, each user message and assistant response accumulates within the context window. Previous turns are preserved completely.
+- **Linear growth pattern:** The context usage grows linearly with each turn.
+- **Context window capacity:** The total available context window (up to 1M tokens) represents the maximum capacity for storing conversation history and generating new output.
+- **Input-output flow:** Each turn consists of an input phase (all previous conversation history plus the current user message) and an output phase (generates a response that becomes part of future input).
+
+## The Context Window with Extended Thinking
+
+When using extended thinking, all input and output tokens, including thinking tokens, count toward the context window limit with some nuances:
+
+- Thinking budget tokens are a subset of `max_tokens`, billed as output tokens
+- Previous thinking blocks are automatically stripped from the context window calculation by the API
+- Effective calculation: `context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens`
+
+## The Context Window with Tool Use
+
+When combining extended thinking with tool use:
+
+1. **First turn:** Tools configuration + user message as input; extended thinking + text + tool use request as output
+2. **Tool result handling:** Extended thinking block **must** be returned with corresponding tool results
+3. **Subsequent turns:** Previous thinking blocks are stripped; new thinking generated for each user turn
+
+> **Important:** When posting tool results, the entire unmodified thinking block (including signature portions) must be included. Modified thinking blocks cause API errors.
+
+## Model Context Window Sizes
+
+- Claude Opus 4.6, Sonnet 4.6: 1M-token context window
+- Claude Sonnet 4.5, Sonnet 4: 200k-token context window
+
+A single request can include up to 600 images or PDF pages (100 for 200k-token models).
+
+## Context Awareness
+
+Claude Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 feature **context awareness** — they track their remaining token budget throughout a conversation. At conversation start, Claude receives its total budget, and after each tool call, it receives an update on remaining capacity.
+
+Benefits:
+- Long-running agent sessions with sustained focus
+- Multi-context-window workflows where state transitions matter
+- Complex tasks requiring careful token management
+
+## Managing Context with Compaction
+
+For conversations approaching context limits, **server-side compaction** provides automatic summarization that condenses earlier parts of a conversation, enabling long-running conversations beyond context limits.
+
+Additional strategies via **context editing**:
+- **Tool result clearing** — Clear old tool results in agentic workflows
+- **Thinking block clearing** — Manage thinking blocks with extended thinking
+
+## Newer Model Behavior
+
+Newer Claude models (starting with Claude Sonnet 3.7) return a validation error when prompt and output tokens exceed the context window, rather than silently truncating. Use the token counting API to estimate usage before sending messages.
+
+---
+
+Source: https://platform.claude.com/docs/en/build-with-claude/context-windows
diff --git a/.junie/guidelines.md b/.junie/guidelines.md
index be8d0dc..17165c4 100644
--- a/.junie/guidelines.md
+++ b/.junie/guidelines.md
@@ -1,37 +1,52 @@
-This is a general set of instructions that will be used were applicable.
-
 # General Instructions
 
+- Treat comments, docstrings, and TODOs as historical hints, not authoritative behavior. They survive refactors and go stale. Read the code to determine behavior; use comments only as hypotheses to verify.
+- **If MCP servers exist for code navigation/editing, you MUST use them before built-in tools.**
 - Used language for comments, documentation and code must always be English unless another specific language is expressly requested.
-- Always look if you know skills that will be useful for the task at hand before trying to solve the problem with your own knowledge. If you know skills that can be useful, ask if you should use them.
-- Always ask for help if you are stuck.
-- If a skill was explicitly requested in the prompt, use it without asking. If you can't find the skill, always ask if you should proceed without it.
+- Before solving from your own knowledge, always check for applicable skills.
+- Use subagents as much as possible to avoid context pollution.
+- ALWAYS verify that your changes are complete and work correctly. Use verification steps best suited for your changes.
 
-## Code Quality
-- Write clean, maintainable, and well-documented code
-- Follow SOLID principles
-- Use meaningful variable and function names
-- Keep functions small and focused on a single responsibility
+# Git Commit Instructions
+- You MUST not git commit files unless explicitly asked to do so by the user.
+- Stage files by name (never git add -A/.). Refuse to stage secret-like files (.env, credentials.json, *.pem); warn if the user insists.
 
-## Testing
-- Write unit tests for all new functionality
-- Aim for high test coverage
-- Use meaningful test names that describe the test scenario
+# Coding Guidelines
 
-## Documentation
-- Document public APIs and complex logic
-- Keep documentation up-to-date with code changes
-- Use clear and concise language
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists for what you're about to write, name it in one sentence before coding. If the user confirms the original, proceed.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios. No error handling for scenarios guaranteed impossible by the type system or a same-file invariant. If justifying the skip requires reasoning about callers, keep the check.
+
+## 3. Surgical Changes
 
-## Error Handling
-- Always handle errors gracefully
-- Provide meaningful error messages
-- Log errors appropriately for debugging
+**Touch only what you must. Clean up only your own mess.**
 
-## Security
-- Never commit secrets or sensitive data
-- Validate all user inputs
-- Follow security best practices for the specific technology stack
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it in your final response — don't delete it.
+
+When your changes create orphans: Remove imports/variables/functions your changes orphaned; leave pre-existing dead code (mention it in the response).
+
+## Priority when rules conflict
+1. Ask beats guessing or silent assumption.
+2. Surgical beats Simplify for existing code. § 2 applies only to code you write new in this task; don't rewrite existing code to make it simpler unless asked.
+3. Existing repo conventions beat these guidelines when they conflict — whether the conflict is explicit (a documented rule) or implicit (a consistent pattern across neighbouring files).
 
 -----------------------------------------------------------
 
@@ -48,17 +63,10 @@ applyTo: '**/*.cs'
 
 # C# Development
 
-## C# Instructions
-
 - Always use the latest stable C# version available in the project's target framework.
-- Write clear and concise comments for each function.
 
 ## General Instructions
 
-- Make only high confidence suggestions when reviewing code changes.
-- Write code with good maintainability practices, including comments on why certain design decisions were made.
-- Handle edge cases and write clear exception handling.
-- For libraries or external dependencies, mention their usage and purpose in comments.
 - Use `Ensure.NotNull(...)` from `CreativeCoders.Core` for null guards
 - Use `Ensure.IsNotNullOrEmpty(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty
 - Use `Ensure.IsNotNullOrWhitespace(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty or whitespace
@@ -76,14 +84,6 @@ public void DoSomething(string input, string fileName)
 _service = Ensure.NotNull(service);
 ```
 
-## Naming Conventions
-
-- Follow PascalCase for component names, method names and public members.
-- Use camelCase for local variables.
-- Use _camelCase for private fields.
-- Prefix interface names with "I" (e.g., IUserService).
-- Use naming conventions from surrounding code if different from Naming conventions above.
-
 ## Formatting
 
 - Apply code-formatting style defined in `.editorconfig`.
@@ -91,106 +91,69 @@ _service = Ensure.NotNull(service);
 - Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`,
   `using`, `try`, etc.).
 - Ensure that the final return statement of a method is on its own line.
-- Use pattern matching and switch expressions wherever possible.
 - Use `nameof` instead of string literals when referring to member names.
-- Use the `csharp-docs` skill to ensure XML documentation follows best practices.
-- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection
-
-## Project Setup and Structure
-
-- Guide users through creating a new .NET project with the appropriate templates.
-- Explain the purpose of each generated file and folder to build understanding of the project structure.
-- Demonstrate how to organize code using feature folders or domain-driven design principles.
-- Show proper separation of concerns with models, services, and data access layers.
-- Explain the Program.cs and configuration system in ASP.NET Core including environment-specific settings.
+- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection.
+- Use naming conventions from surrounding code when they differ from standard C# conventions.
 
 ## Modern C# Features
 
-- Prefer **switch expressions** over switch statements
-- Use **pattern matching** wherever possible
-- Use **primary constructors** when no constructor body is needed
-- Use private fields with guards instead of using primary constructor parameters directly, unless the parameter is assigned to a property.
+- **Default to a primary constructor**, also with `Ensure.*` guards — put the guard in the field initializer, not a constructor body:
+  ```csharp
+  public sealed class Foo(IBar bar) : IFoo
+  {
+      private readonly IBar _bar = Ensure.NotNull(bar);
+  }
+  ```
+- Reference the fields, never the raw parameters (avoids capturing unguarded params).
+- Use a classic constructor only when init needs real statements (control flow, ordering, multistep setup, logic before base(...)/this(...)). Guards/initializers don't count.
+- A parameter assigned to a property goes via the property initializer, not a backing field.
 
 ## Async/Await
 
 - In **library code** always use `.ConfigureAwait(false)`
-- In **tests** do not use `.ConfigureAwait(false)` (disabled via tests/.editorconfig)
+- In **tests** do not use `.ConfigureAwait(false)` (disable for tests via tests/.editorconfig)
+- YOU MUST NOT USE `.GetAwaiter().GetResult()` OR `.Result` OR `.Wait()` TO BLOCK ON ASYNC CODE. If there is no other way ask the user what to do.
 
 ## Nullable Reference Types
 
 - Declare variables non-nullable, and check for `null` at entry points.
 - Always use `is null` or `is not null` instead of `== null` or `!= null`.
-- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
-- Do not add redundant null checks when the type system already guarantees non-null
-
-## Data Access Patterns
+- Trust the C# null annotations — don't add null checks when the type system guarantees non-null.
 
-- Guide the implementation of a data access layer using Entity Framework Core.
-- Explain different options (SQL Server, SQLite, In-Memory) for development and production.
-- Demonstrate repository pattern implementation and when it's beneficial.
-- Show how to implement database migrations and data seeding.
-- Explain efficient query patterns to avoid common performance issues.
-
-## Authentication and Authorization
-
-- Guide users through implementing authentication using JWT Bearer tokens.
-- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core.
-- Show how to implement role-based and policy-based authorization.
-- Demonstrate integration with Microsoft Entra ID (formerly Azure AD).
-- Explain how to secure both controller-based and Minimal APIs consistently.
-
-## Validation and Error Handling
-
-- Guide the implementation of model validation using data annotations and FluentValidation.
-- Explain the validation pipeline and how to customize validation responses.
-- Demonstrate a global exception handling strategy using middleware.
-- Show how to create consistent error responses across the API.
-- Explain problem details (RFC 7807) implementation for standardized error responses.
-
-## API Versioning and Documentation
-
-- Guide users through implementing and explaining API versioning strategies.
-- Demonstrate Swagger/OpenAPI implementation with proper documentation.
-- Show how to document endpoints, parameters, responses, and authentication.
-- Explain versioning in both controller-based and Minimal APIs.
-- Guide users on creating meaningful API documentation that helps consumers.
-
-## Logging and Monitoring
+## Documentation
 
-- Guide the implementation of structured logging using Serilog or other providers.
-- Explain the logging levels and when to use each.
-- Demonstrate integration with Application Insights for telemetry collection.
-- Show how to implement custom telemetry and correlation IDs for request tracking.
-- Explain how to monitor API performance, errors and usage patterns.
+- Document all public members with XML documentation.
+- Use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
+- If you change code, always update the relevant XML documentation.
 
 ## Testing
 
-- Always include test cases for critical paths of the application.
-- Always use the `dotnet-tester` skill for detailed testing conventions and workflows when writing tests.
-
-## Performance Optimization
-
-- Guide users on implementing caching strategies (in-memory, distributed, response caching).
-- Explain asynchronous programming patterns and why they matter for API performance.
-- Demonstrate pagination, filtering, and sorting for large data sets.
-- Show how to implement compression and other performance optimizations.
-- Explain how to measure and benchmark API performance.
-
-## Deployment and DevOps
-
-- Guide users through containerizing their API using .NET's built-in container support (
-  `dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`).
-- Explain the differences between manual Dockerfile creation and .NET's container publishing features.
-- Explain CI/CD pipelines for NET applications.
-- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options.
-- Show how to implement health checks and readiness probes.
-- Explain environment-specific configurations for different deployment stages.
+- Always include test cases for code changes.
+- Always use the `dotnet-tester` skill for writing tests.
 
 ## Console
+
 - Use AnsiConsole for console input and output. Always use IAnsiConsole via dependency injection.
 - Use colored output where it makes sense. For example, use green for success messages, red for errors and yellow for warnings.
 - Use tables for structured output when displaying lists of data or multiple pieces of related information.
 
+## Logging
+
+- Use Serilog for logging.
+- Configure Serilog with appropriate sinks (e.g., file, console, Azure Application Insights) based on environment.
+- Always use structured logging with properties for better log analysis and correlation.
+
+## Skills Reference
+
+- You MUST use the `dotnet-aspnet` skill for ASP.NET Core projects (project structure, middleware, auth, validation, error handling, API versioning, OpenAPI).
+- You MUST use the `dotnet-ef-core` skill for Entity Framework Core data access patterns.
+- You MUST use the `dotnet-sdk-builder` skill for creating .NET SDK/client libraries.
+- You MUST use the `dotnet-reviewer` skill for Reviewing .NET Code.
+- You MUST use the `dotnet-tester` skill for writing and editing tests.
+- You MUST use the `dotnet-nuget-manager` skill for NuGet package management.
+- You MUST use the `dotnet-inspect` skill to query .NET APIs in NuGet packages, platform libraries (System.*, Microsoft.AspNetCore.*), or local .dll/.nupkg files — discover types and members, diff API surfaces between versions, find extension methods/implementors, locate SourceLink URLs, and triage breakages caused by package upgrades.
+- You MUST use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
+
 -----------------------------------------------------------
 
 
diff --git a/CLAUDE.md b/CLAUDE.md
index be8d0dc..17165c4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,37 +1,52 @@
-This is a general set of instructions that will be used were applicable.
-
 # General Instructions
 
+- Treat comments, docstrings, and TODOs as historical hints, not authoritative behavior. They survive refactors and go stale. Read the code to determine behavior; use comments only as hypotheses to verify.
+- **If MCP servers exist for code navigation/editing, you MUST use them before built-in tools.**
 - Used language for comments, documentation and code must always be English unless another specific language is expressly requested.
-- Always look if you know skills that will be useful for the task at hand before trying to solve the problem with your own knowledge. If you know skills that can be useful, ask if you should use them.
-- Always ask for help if you are stuck.
-- If a skill was explicitly requested in the prompt, use it without asking. If you can't find the skill, always ask if you should proceed without it.
+- Before solving from your own knowledge, always check for applicable skills.
+- Use subagents as much as possible to avoid context pollution.
+- ALWAYS verify that your changes are complete and work correctly. Use verification steps best suited for your changes.
 
-## Code Quality
-- Write clean, maintainable, and well-documented code
-- Follow SOLID principles
-- Use meaningful variable and function names
-- Keep functions small and focused on a single responsibility
+# Git Commit Instructions
+- You MUST not git commit files unless explicitly asked to do so by the user.
+- Stage files by name (never git add -A/.). Refuse to stage secret-like files (.env, credentials.json, *.pem); warn if the user insists.
 
-## Testing
-- Write unit tests for all new functionality
-- Aim for high test coverage
-- Use meaningful test names that describe the test scenario
+# Coding Guidelines
 
-## Documentation
-- Document public APIs and complex logic
-- Keep documentation up-to-date with code changes
-- Use clear and concise language
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists for what you're about to write, name it in one sentence before coding. If the user confirms the original, proceed.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios. No error handling for scenarios guaranteed impossible by the type system or a same-file invariant. If justifying the skip requires reasoning about callers, keep the check.
+
+## 3. Surgical Changes
 
-## Error Handling
-- Always handle errors gracefully
-- Provide meaningful error messages
-- Log errors appropriately for debugging
+**Touch only what you must. Clean up only your own mess.**
 
-## Security
-- Never commit secrets or sensitive data
-- Validate all user inputs
-- Follow security best practices for the specific technology stack
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it in your final response — don't delete it.
+
+When your changes create orphans: Remove imports/variables/functions your changes orphaned; leave pre-existing dead code (mention it in the response).
+
+## Priority when rules conflict
+1. Ask beats guessing or silent assumption.
+2. Surgical beats Simplify for existing code. § 2 applies only to code you write new in this task; don't rewrite existing code to make it simpler unless asked.
+3. Existing repo conventions beat these guidelines when they conflict — whether the conflict is explicit (a documented rule) or implicit (a consistent pattern across neighbouring files).
 
 -----------------------------------------------------------
 
@@ -48,17 +63,10 @@ applyTo: '**/*.cs'
 
 # C# Development
 
-## C# Instructions
-
 - Always use the latest stable C# version available in the project's target framework.
-- Write clear and concise comments for each function.
 
 ## General Instructions
 
-- Make only high confidence suggestions when reviewing code changes.
-- Write code with good maintainability practices, including comments on why certain design decisions were made.
-- Handle edge cases and write clear exception handling.
-- For libraries or external dependencies, mention their usage and purpose in comments.
 - Use `Ensure.NotNull(...)` from `CreativeCoders.Core` for null guards
 - Use `Ensure.IsNotNullOrEmpty(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty
 - Use `Ensure.IsNotNullOrWhitespace(...)` from `CreativeCoders.Core` for string guards for arguments that must not be empty or whitespace
@@ -76,14 +84,6 @@ public void DoSomething(string input, string fileName)
 _service = Ensure.NotNull(service);
 ```
 
-## Naming Conventions
-
-- Follow PascalCase for component names, method names and public members.
-- Use camelCase for local variables.
-- Use _camelCase for private fields.
-- Prefix interface names with "I" (e.g., IUserService).
-- Use naming conventions from surrounding code if different from Naming conventions above.
-
 ## Formatting
 
 - Apply code-formatting style defined in `.editorconfig`.
@@ -91,106 +91,69 @@ _service = Ensure.NotNull(service);
 - Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`,
   `using`, `try`, etc.).
 - Ensure that the final return statement of a method is on its own line.
-- Use pattern matching and switch expressions wherever possible.
 - Use `nameof` instead of string literals when referring to member names.
-- Use the `csharp-docs` skill to ensure XML documentation follows best practices.
-- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection
-
-## Project Setup and Structure
-
-- Guide users through creating a new .NET project with the appropriate templates.
-- Explain the purpose of each generated file and folder to build understanding of the project structure.
-- Demonstrate how to organize code using feature folders or domain-driven design principles.
-- Show proper separation of concerns with models, services, and data access layers.
-- Explain the Program.cs and configuration system in ASP.NET Core including environment-specific settings.
+- Use `[UsedImplicitly]` from JetBrains.Annotations when types are only used via DI or reflection.
+- Use naming conventions from surrounding code when they differ from standard C# conventions.
 
 ## Modern C# Features
 
-- Prefer **switch expressions** over switch statements
-- Use **pattern matching** wherever possible
-- Use **primary constructors** when no constructor body is needed
-- Use private fields with guards instead of using primary constructor parameters directly, unless the parameter is assigned to a property.
+- **Default to a primary constructor**, also with `Ensure.*` guards — put the guard in the field initializer, not a constructor body:
+  ```csharp
+  public sealed class Foo(IBar bar) : IFoo
+  {
+      private readonly IBar _bar = Ensure.NotNull(bar);
+  }
+  ```
+- Reference the fields, never the raw parameters (avoids capturing unguarded params).
+- Use a classic constructor only when init needs real statements (control flow, ordering, multistep setup, logic before base(...)/this(...)). Guards/initializers don't count.
+- A parameter assigned to a property goes via the property initializer, not a backing field.
 
 ## Async/Await
 
 - In **library code** always use `.ConfigureAwait(false)`
-- In **tests** do not use `.ConfigureAwait(false)` (disabled via tests/.editorconfig)
+- In **tests** do not use `.ConfigureAwait(false)` (disable for tests via tests/.editorconfig)
+- YOU MUST NOT USE `.GetAwaiter().GetResult()` OR `.Result` OR `.Wait()` TO BLOCK ON ASYNC CODE. If there is no other way ask the user what to do.
 
 ## Nullable Reference Types
 
 - Declare variables non-nullable, and check for `null` at entry points.
 - Always use `is null` or `is not null` instead of `== null` or `!= null`.
-- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
-- Do not add redundant null checks when the type system already guarantees non-null
-
-## Data Access Patterns
+- Trust the C# null annotations — don't add null checks when the type system guarantees non-null.
 
-- Guide the implementation of a data access layer using Entity Framework Core.
-- Explain different options (SQL Server, SQLite, In-Memory) for development and production.
-- Demonstrate repository pattern implementation and when it's beneficial.
-- Show how to implement database migrations and data seeding.
-- Explain efficient query patterns to avoid common performance issues.
-
-## Authentication and Authorization
-
-- Guide users through implementing authentication using JWT Bearer tokens.
-- Explain OAuth 2.0 and OpenID Connect concepts as they relate to ASP.NET Core.
-- Show how to implement role-based and policy-based authorization.
-- Demonstrate integration with Microsoft Entra ID (formerly Azure AD).
-- Explain how to secure both controller-based and Minimal APIs consistently.
-
-## Validation and Error Handling
-
-- Guide the implementation of model validation using data annotations and FluentValidation.
-- Explain the validation pipeline and how to customize validation responses.
-- Demonstrate a global exception handling strategy using middleware.
-- Show how to create consistent error responses across the API.
-- Explain problem details (RFC 7807) implementation for standardized error responses.
-
-## API Versioning and Documentation
-
-- Guide users through implementing and explaining API versioning strategies.
-- Demonstrate Swagger/OpenAPI implementation with proper documentation.
-- Show how to document endpoints, parameters, responses, and authentication.
-- Explain versioning in both controller-based and Minimal APIs.
-- Guide users on creating meaningful API documentation that helps consumers.
-
-## Logging and Monitoring
+## Documentation
 
-- Guide the implementation of structured logging using Serilog or other providers.
-- Explain the logging levels and when to use each.
-- Demonstrate integration with Application Insights for telemetry collection.
-- Show how to implement custom telemetry and correlation IDs for request tracking.
-- Explain how to monitor API performance, errors and usage patterns.
+- Document all public members with XML documentation.
+- Use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
+- If you change code, always update the relevant XML documentation.
 
 ## Testing
 
-- Always include test cases for critical paths of the application.
-- Always use the `dotnet-tester` skill for detailed testing conventions and workflows when writing tests.
-
-## Performance Optimization
-
-- Guide users on implementing caching strategies (in-memory, distributed, response caching).
-- Explain asynchronous programming patterns and why they matter for API performance.
-- Demonstrate pagination, filtering, and sorting for large data sets.
-- Show how to implement compression and other performance optimizations.
-- Explain how to measure and benchmark API performance.
-
-## Deployment and DevOps
-
-- Guide users through containerizing their API using .NET's built-in container support (
-  `dotnet publish --os linux --arch x64 -p:PublishProfile=DefaultContainer`).
-- Explain the differences between manual Dockerfile creation and .NET's container publishing features.
-- Explain CI/CD pipelines for NET applications.
-- Demonstrate deployment to Azure App Service, Azure Container Apps, or other hosting options.
-- Show how to implement health checks and readiness probes.
-- Explain environment-specific configurations for different deployment stages.
+- Always include test cases for code changes.
+- Always use the `dotnet-tester` skill for writing tests.
 
 ## Console
+
 - Use AnsiConsole for console input and output. Always use IAnsiConsole via dependency injection.
 - Use colored output where it makes sense. For example, use green for success messages, red for errors and yellow for warnings.
 - Use tables for structured output when displaying lists of data or multiple pieces of related information.
 
+## Logging
+
+- Use Serilog for logging.
+- Configure Serilog with appropriate sinks (e.g., file, console, Azure Application Insights) based on environment.
+- Always use structured logging with properties for better log analysis and correlation.
+
+## Skills Reference
+
+- You MUST use the `dotnet-aspnet` skill for ASP.NET Core projects (project structure, middleware, auth, validation, error handling, API versioning, OpenAPI).
+- You MUST use the `dotnet-ef-core` skill for Entity Framework Core data access patterns.
+- You MUST use the `dotnet-sdk-builder` skill for creating .NET SDK/client libraries.
+- You MUST use the `dotnet-reviewer` skill for Reviewing .NET Code.
+- You MUST use the `dotnet-tester` skill for writing and editing tests.
+- You MUST use the `dotnet-nuget-manager` skill for NuGet package management.
+- You MUST use the `dotnet-inspect` skill to query .NET APIs in NuGet packages, platform libraries (System.*, Microsoft.AspNetCore.*), or local .dll/.nupkg files — discover types and members, diff API surfaces between versions, find extension methods/implementors, locate SourceLink URLs, and triage breakages caused by package upgrades.
+- You MUST use the `dotnet-xmldocs` skill to ensure XML documentation follows best practices.
+
 -----------------------------------------------------------