devoplus · bbesli · May 20, 2026 · May 20, 2026 · May 20, 2026 · May 21, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -9,4 +9,15 @@
 - Follow naming conventions
 
 ## Testing Practices
-- Integration tests should prefer obtaining services like IMilvaLogger directly from the ServiceProvider instead of using stubs or mocks.
+- Integration tests should prefer obtaining services like IMilvaLogger directly from the ServiceProvider instead of using stubs or mocks.
+
+## Commit Messages
+Always generate commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+- Format: `<type>(<scope>): <description>`, optionally followed by a blank line, body, and footer(s).
+- Subject: imperative mood ("add", "fix", "remove"), lower-case, no trailing period, at most 72 characters.
+- Types: `feat`, `fix`, `perf`, `refactor`, `docs`, `style`, `test`, `build`, `ci`, `chore`, `revert`.
+- Scope (optional, lower-case) is the affected area, e.g. `api`, `ui`, `infrastructure`, `application`, `domain`, `sdk`, `mcp`, `settings`, `jobs`, `workflows`, `alerting`, `redis`, `auth`, `db`, `deps`. Omit it when a change spans many areas; never invent a scope not reflected by the changed files.
+- Breaking changes: add `!` after the type/scope and a `BREAKING CHANGE:` footer.
+- Describe intent (what/why), not a file list. Reference issues in the footer when relevant (`Closes #123`).
+- Full rules and examples: [.github/git-commit-instructions.md](git-commit-instructions.md).
diff --git a/.github/git-commit-instructions.md b/.github/git-commit-instructions.md
@@ -0,0 +1,66 @@
+# Commit message instructions (Conventional Commits)
+
+Write every commit message following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+## Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- The **subject** line is `<type>(<scope>): <description>`.
+- Keep the subject in the **imperative mood** ("add", "fix", "remove" — not "added"/"fixes"), lower-case, no trailing period, and **<= 72 characters**.
+- `scope` is optional but preferred; use lower-case.
+- Leave a blank line before the body and before the footer.
+- Wrap the body at ~100 characters. Explain **what** and **why**, not how.
+
+## Allowed types
+
+- `feat` — a new feature
+- `fix` — a bug fix
+- `perf` — a performance improvement
+- `refactor` — a code change that neither fixes a bug nor adds a feature
+- `docs` — documentation only
+- `style` — formatting/whitespace, no code behaviour change
+- `test` — adding or fixing tests
+- `build` — build system, dependencies, packaging
+- `ci` — CI/CD configuration and scripts
+- `chore` — housekeeping that doesn't touch src or tests
+- `revert` — reverts a previous commit
+
+## Suggested scopes (this repo)
+
+Pick the most specific scope that fits: `api`, `ui`, `infrastructure`, `application`, `domain`, `sdk`, `mcp`, `settings`, `jobs`, `workflows`, `occurrences`, `alerting`, `redis`, `auth`, `db`, `deps`, `ci`, `docs`. Omit the scope if a change spans many areas.
+
+## Breaking changes
+
+- Add a `!` after the type/scope **and** a `BREAKING CHANGE:` footer:
+
+```
+feat(api)!: change occurrence list response shape
+
+BREAKING CHANGE: `totalCount` is now an estimate, not an exact count.
+```
+
+## Rules
+
+- One logical change per commit; the subject should describe the whole change.
+- Do not invent a scope that isn't reflected by the changed files.
+- Do not include file lists in the message; summarise the intent.
+
+## Examples
+
+```
+feat(settings): add runtime branding and notification config
+fix(redis): estimate occurrence counts from planner stats to avoid full scans
+perf(ui): format execution total with compact K/M notation
+refactor(infrastructure): qualify SettingsProvider registration to avoid BCL type clash
+docs(mcp): document settings tools
+build(deps): bump Npgsql to 10.0.10
+test(alerting): stub ISettingsProvider in AlertNotifier tests
+chore(ci): silence MCP002 analyzer suggestion
+```
diff --git a/.gitignore b/.gitignore
@@ -362,3 +362,7 @@ MigrationBackup/
 # Fody - auto-generated XML schema
 FodyWeavers.xsd
 /CoverageReport
+
+# Local environment variables
+.env
+.env.local
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,7 @@
+{
+  // GitHub Copilot generates commit messages using the Conventional Commits rules in
+  // .github/git-commit-instructions.md.
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    { "file": ".github/git-commit-instructions.md" }
+  ]
+}
diff --git a/Milvaion.slnx b/Milvaion.slnx
@@ -85,29 +85,9 @@
     <File Path="docs/portaldocs/20-workflows.md" />
     <File Path="docs/portaldocs/21-reporter-worker.md" />
     <File Path="docs/portaldocs/22-reports.md" />
+    <File Path="docs/portaldocs/23-local-job-testing.md" />
   </Folder>
   <Folder Name="/src/">
-    <Project Path="src/MilvaionUI/" Type="Website" DisplayName="MilvaionUI">
-      <BuildType Project="Debug" />
-      <Properties Name="WebsiteProperties">
-        <Property Name="Debug.AspNetCompiler.Debug" Value="&quot;True&quot;" />
-        <Property Name="Debug.AspNetCompiler.FixedNames" Value="&quot;false&quot;" />
-        <Property Name="Debug.AspNetCompiler.ForceOverwrite" Value="&quot;true&quot;" />
-        <Property Name="Debug.AspNetCompiler.PhysicalPath" Value="&quot;src\MilvaionUI\&quot;" />
-        <Property Name="Debug.AspNetCompiler.TargetPath" Value="&quot;PrecompiledWeb\localhost_49627\&quot;" />
-        <Property Name="Debug.AspNetCompiler.Updateable" Value="&quot;true&quot;" />
-        <Property Name="Debug.AspNetCompiler.VirtualPath" Value="&quot;/localhost_49627&quot;" />
-        <Property Name="Release.AspNetCompiler.Debug" Value="&quot;False&quot;" />
-        <Property Name="Release.AspNetCompiler.FixedNames" Value="&quot;false&quot;" />
-        <Property Name="Release.AspNetCompiler.ForceOverwrite" Value="&quot;true&quot;" />
-        <Property Name="Release.AspNetCompiler.PhysicalPath" Value="&quot;src\MilvaionUI\&quot;" />
-        <Property Name="Release.AspNetCompiler.TargetPath" Value="&quot;PrecompiledWeb\localhost_49627\&quot;" />
-        <Property Name="Release.AspNetCompiler.Updateable" Value="&quot;true&quot;" />
-        <Property Name="Release.AspNetCompiler.VirtualPath" Value="&quot;/localhost_49627&quot;" />
-        <Property Name="TargetFrameworkMoniker" Value="&quot;.NETFramework,Version%3Dv4.8&quot;" />
-        <Property Name="VWDPort" Value="&quot;49627&quot;" />
-      </Properties>
-    </Project>
   </Folder>
   <Folder Name="/src/Scheduler/" />
   <Folder Name="/src/Scheduler/Core/">
@@ -130,6 +110,9 @@
     <Project Path="src/Sdk/Milvasoft.Milvaion.Sdk.Worker/Milvasoft.Milvaion.Sdk.Worker.csproj">
       <BuildType Solution="TemplateTest|*" Project="Debug" />
     </Project>
+    <Project Path="src/Sdk/Milvasoft.Milvaion.Sdk.Worker.Testing/Milvasoft.Milvaion.Sdk.Worker.Testing.csproj">
+      <BuildType Solution="TemplateTest|*" Project="Debug" />
+    </Project>
     <Project Path="src/Sdk/Milvasoft.Milvaion.Sdk/Milvasoft.Milvaion.Sdk.csproj" Id="848b918f-4553-4e07-8531-3c9423a9fa5e">
       <BuildType Solution="TemplateTest|*" Project="Debug" />
     </Project>
@@ -165,7 +148,13 @@
       <BuildType Solution="TemplateTest|*" Project="Debug" />
     </Project>
   </Folder>
-  <Folder Name="/tests/" />
+  <Folder Name="/tests/">
+    <Project Path="tests/SampleWorker.Tests/SampleWorker.Tests.csproj">
+      <BuildType Solution="TemplateTest|*" Project="Debug" />
+      <Build Solution="Debug|*" Project="false" />
+      <Build Solution="TemplateTest|*" Project="false" />
+    </Project>
+  </Folder>
   <Folder Name="/tests/IntegrationTests/">
     <Project Path="tests/Milvaion.IntegrationTests/Milvaion.IntegrationTests.csproj">
       <BuildType Solution="TemplateTest|*" Project="Release" />

diff --git a/README.md b/README.md
@@ -8,6 +8,8 @@
 
 <p align="center">
 A distributed job scheduling system built on .NET 10
+<br>
+<sub>Already on <b>Hangfire</b> or <b>Quartz.NET</b>? Keep it — <a href="#already-running-hangfire-or-quartznet">add Milvaion monitoring in two lines</a>.</sub>
 </p>
 
 <div align="center">
@@ -60,12 +62,59 @@ Milvaion solves these problems by **completely separating scheduling from execut
 
 ---
 
+## Already Running Hangfire or Quartz.NET?
+
+**You don't have to migrate to adopt Milvaion.**
+
+Milvaion plugs into the scheduler you already run. Your scheduler keeps owning triggers, storage and cron expressions. Your job code doesn't change. Milvaion adds one real-time dashboard across every service, plus persisted execution history, metrics and alerting.
+
+```csharp
+// Hangfire - your existing setup stays exactly as it is
+builder.Services.AddMilvaionHangfireIntegration(builder.Configuration);
+builder.Services.AddHangfire((sp, config) => config.UseMilvaion(sp));
+
+// Quartz.NET - your existing setup stays exactly as it is
+builder.Services.AddMilvaionQuartzIntegration(builder.Configuration);
+builder.Services.AddQuartz(q => q.UseMilvaion(builder.Services));
+```
+
+That's the whole integration.
+
+### The problem this solves
+
+A typical .NET estate ends up with background jobs scattered across a dozen services — each with its own dashboard behind its own URL and its own auth. Nobody can answer *"which jobs failed last night?"* without opening every one of them, and history vanishes when the retention window rolls over.
+
+| Before | After |
+|--------|-------|
+| One dashboard per service | One dashboard for the whole estate |
+| History limited by Hangfire/Quartz retention | Full execution history in PostgreSQL |
+| Logs only in each app's own sink | Real-time log streaming per execution |
+| Failures noticed when someone complains | Multi-channel alerts on failure and timeout |
+| No cross-service metrics | Success rate, duration and EPM per job |
+
+### The adoption path
+
+1. **Add monitoring** — two lines per application. No migration window, no change to job code.
+2. **Get visibility** — every Hangfire and Quartz.NET job appears in the dashboard, flagged as external.
+3. **Migrate selectively, or never** — when one job outgrows in-process execution, move just that job to a Milvaion worker. Everything else keeps running untouched.
+
+Plenty of teams stop at step 2. That's a perfectly good outcome.
+
+| Scheduler | Package | Status |
+|-----------|---------|--------|
+| **Hangfire** | `Milvasoft.Milvaion.Sdk.Worker.Hangfire` | ✅ Available |
+| **Quartz.NET** | `Milvasoft.Milvaion.Sdk.Worker.Quartz` | ✅ Available |
+
+📖 **[Full Integration Guide →](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers)**
+
+---
+
 ## Features
 
 ![Milvaion Real Time](https://portal.milvasoft.com/assets/images/executions-4b5918b7fca1b603f54be133c7880397.gif)
 
 ### Reliability
-- **At-least-once delivery** via RabbitMQ manual ACK
+- **At-least-once delivery** via RabbitMQ publisher confirms and manual ACK
 - **Automatic retries** with exponential backoff
 - **Dead Letter Queue** for failed jobs after max retries
 - **Zombie detection** recovers stuck jobs
@@ -105,26 +154,28 @@ Milvaion solves these problems by **completely separating scheduling from execut
 - **Maintenance Worker** - Milvaion self data warehouse cleanup and archival
 
 ### External Scheduler Integration
-Already using **Quartz.NET** or **Hangfire**? Keep your existing scheduler and gain Milvaion's monitoring capabilities:
-
-| Scheduler | Package | Status |
-|-----------|---------|--------|
-| **Quartz.NET** | `Milvasoft.Milvaion.Sdk.Worker.Quartz` | ✅ Available |
-| **Hangfire** | `Milvasoft.Milvaion.Sdk.Worker.Hangfire` | ✅ Available |
+Milvaion also monitors jobs running in **Quartz.NET** and **Hangfire** without replacing them — see [Already Running Hangfire or Quartz.NET?](#already-running-hangfire-or-quartznet) above.
 
-```csharp
-// Quartz.NET Integration
-builder.Services.AddMilvaionQuartzIntegration(builder.Configuration);
-builder.Services.AddQuartz(q => q.UseMilvaion(builder.Services));
+### MCP Server
+Point Claude Code, Cursor or GitHub Copilot at Milvaion and ask about your jobs in plain language:
 
-// Hangfire Integration
-builder.Services.AddMilvaionHangfireIntegration(builder.Configuration);
-builder.Services.AddHangfire((sp, config) => config.UseMilvaion(sp));
+```json
+{
+  "mcpServers": {
+    "milvaion": {
+      "type": "http",
+      "url": "https://milvaion.yourcompany.com/mcp",
+      "headers": { "X-ApiKey": "your-api-key" }
+    }
+  }
+}
 ```
 
-External jobs appear in Milvaion dashboard with full monitoring, metrics, and execution history - without changing your existing scheduler setup.
+> *"Which jobs failed last night and why?"*
+
+More than forty tools — reading, triggering, pausing, editing and deleting — each gated by the same permissions used everywhere else. A read-only api key gives an assistant full visibility and no ability to change anything. Milvaion is the data source here; it never calls a language model and stores no model provider keys.
 
-[For more information...](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers)
+📖 **[MCP Server Guide →](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/mcp-server)**
 
 ---
 
@@ -378,6 +429,9 @@ Each workflow can also configure **Max Step Retries** and a **Timeout** (auto-ca
 | Document | Description |
 |----------|-------------|
 | [Introduction](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/introduction) | What is Milvaion, when to use it |
+| [Hangfire & Quartz.NET Integration](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers) | Keep your existing scheduler, add Milvaion monitoring |
+| [Api Keys](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/api-keys) | Credentials for CI pipelines, scripts and MCP clients |
+| [MCP Server](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/mcp-server) | Connect Claude Code, Cursor or Copilot to Milvaion |
 | [Quick Start](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/quick-start) | Get running in under 10 minutes |
 | [Core Concepts](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/core-concepts) | Architecture and key terms |
 | [Your First Worker](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/your-first-worker) | Create a custom worker |
@@ -397,6 +451,7 @@ Each workflow can also configure **Max Step Retries** and a **Timeout** (auto-ca
 | [Architecture](./docs/githubdocs/ARCHITECTURE.md) | Technical architecture deep-dive |
 | [Development](./docs/githubdocs/DEVELOPMENT.md) | Development environment setup |
 | [Worker SDK](./docs/githubdocs/WORKER-SDK.md) | Worker SDK reference |
+| [MCP Server](./docs/githubdocs/MCP-SERVER.md) | MCP server and api key auth internals |
 | [Security](./SECURITY.md) | Security policies |
 
 ---
@@ -493,8 +548,7 @@ dotnet new install Milvasoft.Templates.Milvaion
 # Pull the latest image
 docker pull milvasoft/milvaion-api:latest
 
-# Run with Docker Compose
-cd build
+# Run with Docker Compose, from the repository root
 docker compose up -d
 ```