Add Slack/webhook alerting and self-contained HTML report

- WebhookNotifier: optional webhookUrl on the API request and --webhook-url
  CLI flag, auto-detects Slack incoming webhooks, POSTs the full response to
  any other listener (Teams/PagerDuty/custom). Fires only on HIGH/CRITICAL
  findings; network failures never fail the request.
- HtmlReportRenderer: --html CLI flag writes a self-contained report
  (inline CSS, no CDN) for demos and sharing — same visual language as
  JIT-Optimization-Engine's equivalent report.

Both were the most commonly cited gaps against commercial FinOps/architecture
tools (Vantage, CloudZero, Backstage) without pulling in a database or a
served dashboard, which the engine deliberately avoids (see ARCHITECTURE.md).

Author: cloudsealed

README.md

@@ -169,12 +169,52 @@ Response shape:
 ```bash
 dotnet run --project src/CloudSealed.ML.CLI -- examples/inventory.json
 dotnet run --project src/CloudSealed.ML.CLI -- examples/inventory.json --json
+dotnet run --project src/CloudSealed.ML.CLI -- examples/inventory.json --html report.html
 ```
 
+`--html` writes a self-contained report (inline CSS, no CDN) alongside
+whatever other output is requested — open it straight from disk, or attach it
+to an email.
+
 Runs the same analysis without starting a server, printing either a
 human-readable summary or the raw JSON response. [`examples/inventory.json`](examples/inventory.json)
 is a ready-to-run sample with a mix of criticality levels and system types.
 
+## GitHub Action
+
+Run the audit in CI and get the findings as a pull request comment, without
+installing anything locally:
+
+```yaml
+- uses: cloudsealed/Predictive-ML-Core@main
+  with:
+    inventory-json: inventory.json
+    fail-on-severity: CRITICAL   # optional: fail the check on CRITICAL findings
+```
+
+Re-runs on the same PR edit the existing comment instead of piling up new
+ones. See [action.yml](action.yml) for all inputs/outputs and
+[.github/workflows/example-usage.yml](.github/workflows/example-usage.yml)
+for a working example (this repository dogfoods its own action against
+[examples/inventory.json](examples/inventory.json) on every push).
+
+## Alerts
+
+Send the result to Slack (or any generic webhook listener) when a finding
+reaches a severity threshold, without standing up a dashboard:
+
+```bash
+dotnet run --project src/CloudSealed.ML.CLI -- examples/inventory.json --webhook-url "$SLACK_WEBHOOK_URL"
+```
+
+A Slack incoming-webhook URL (`hooks.slack.com`) is auto-detected and
+rendered as a formatted message; any other URL receives the full JSON
+response, so it works as-is with Teams, PagerDuty, or a custom listener.
+Nothing is sent unless a finding is HIGH or CRITICAL. The same behaviour is
+available in the HTTP API via the optional `webhookUrl` field on
+`/v1/predict-architecture`. A failed webhook is logged and never fails the
+request.
+
 ## Development
 
 ```bash

src/CloudSealed.ML.API/Program.cs

@@ -1,4 +1,5 @@
 using CloudSealed.ML.Engine.Models;
+using CloudSealed.ML.Engine.Notifications;
 using CloudSealed.ML.Engine.Scoring;
 using Microsoft.OpenApi.Models;
 
@@ -14,6 +15,7 @@
 });
 
 builder.Services.AddSingleton<ArchitectureAnalyzer>();
+builder.Services.AddHttpClient("webhook");
 builder.Services.AddEndpointsApiExplorer();
 builder.Services.AddSwaggerGen(options =>
 {
@@ -41,10 +43,11 @@
 
 app.MapGet("/health", () => Results.Ok(new { status = "ok" }));
 
-app.MapPost("/v1/predict-architecture", (
+app.MapPost("/v1/predict-architecture", async (
     PredictArchitectureRequest? request,
     HttpRequest httpRequest,
-    ArchitectureAnalyzer analyzer) =>
+    ArchitectureAnalyzer analyzer,
+    IHttpClientFactory httpClientFactory) =>
 {
     var apiKey = Environment.GetEnvironmentVariable("PREDICTIVE_ML_CORE_API_KEY");
     if (!string.IsNullOrEmpty(apiKey))
@@ -62,6 +65,13 @@
     }
 
     var response = analyzer.Analyze(request);
+
+    if (!string.IsNullOrWhiteSpace(request.WebhookUrl))
+    {
+        await WebhookNotifier.NotifyAsync(
+            httpClientFactory.CreateClient("webhook"), request.WebhookUrl, response, request.CompanyName);
+    }
+
     return Results.Ok(response);
 });
 

src/CloudSealed.ML.CLI/Program.cs

@@ -1,5 +1,7 @@
 using System.Text.Json;
 using CloudSealed.ML.Engine.Models;
+using CloudSealed.ML.Engine.Notifications;
+using CloudSealed.ML.Engine.Reporting;
 using CloudSealed.ML.Engine.Scoring;
 
 namespace CloudSealed.ML.CLI;
@@ -15,12 +17,16 @@ internal static class Program
         WriteIndented = true,
     };
 
-    private static int Main(string[] args)
+    private static async Task<int> Main(string[] args)
     {
-        var positional = args.Where(a => a != "--json").ToArray();
+        var webhookUrl = ExtractOptionValue(args, "--webhook-url");
+        var htmlPath = ExtractOptionValue(args, "--html");
+        var consumed = new[] { "--json", webhookUrl, "--webhook-url", htmlPath, "--html" };
+        var positional = args.Where(a => !consumed.Contains(a)).ToArray();
         if (positional.Length != 1)
         {
-            Console.Error.WriteLine("Uso: cloudsealed-predictive-ml <inventory.json> [--json]");
+            Console.Error.WriteLine(
+                "Uso: cloudsealed-predictive-ml <inventory.json> [--json] [--html PATH] [--webhook-url URL]");
             return 1;
         }
 
@@ -51,6 +57,17 @@ private static int Main(string[] args)
 
         var response = new ArchitectureAnalyzer().Analyze(request);
 
+        if (webhookUrl is not null)
+        {
+            using var client = new HttpClient();
+            await WebhookNotifier.NotifyAsync(client, webhookUrl, response, request.CompanyName);
+        }
+
+        if (htmlPath is not null)
+        {
+            await File.WriteAllTextAsync(htmlPath, HtmlReportRenderer.Render(response, request.CompanyName));
+        }
+
         if (args.Contains("--json"))
         {
             Console.WriteLine(JsonSerializer.Serialize(response, JsonOptions));
@@ -61,6 +78,12 @@ private static int Main(string[] args)
         return 0;
     }
 
+    private static string? ExtractOptionValue(string[] args, string optionName)
+    {
+        var index = Array.IndexOf(args, optionName);
+        return index >= 0 && index + 1 < args.Length ? args[index + 1] : null;
+    }
+
     private static void PrintHumanReadable(PredictArchitectureRequest request, PredictArchitectureResponse response)
     {
         Console.WriteLine($"Predictive-ML-Core — {request.CompanyName}");

src/CloudSealed.ML.Engine/Models/ArchitectureContract.cs

@@ -36,6 +36,11 @@ public class PredictArchitectureRequest
     public List<SystemInput> Systems { get; set; } = new();
 
     public HistoricalMetrics? HistoricalMetrics { get; set; }
+
+    // Opcional/aditivo: se definido, o resultado é enviado para esta URL
+    // (Slack incoming webhook ou listener genérico) quando algum finding
+    // atinge HIGH/CRITICAL. Ver WebhookNotifier.
+    public string? WebhookUrl { get; set; }
 }
 
 public class RiskScores

src/CloudSealed.ML.Engine/Notifications/WebhookNotifier.cs

@@ -0,0 +1,85 @@
+using System.Net.Http.Json;
+using System.Text.Json;
+using CloudSealed.ML.Engine.Models;
+
+namespace CloudSealed.ML.Engine.Notifications;
+
+// Efeito colateral, não parte do contrato de análise: uma falha de rede é
+// engolida (nunca propagada), para que um webhook fora do ar não derrube uma
+// resposta que já foi calculada com sucesso. Espelha cloudsealed_jit/notify.py.
+public static class WebhookNotifier
+{
+    private static readonly Dictionary<string, int> SeverityRank = new()
+    {
+        ["LOW"] = 0,
+        ["MEDIUM"] = 1,
+        ["HIGH"] = 2,
+        ["CRITICAL"] = 3,
+    };
+
+    public static bool IsSlackWebhook(string url) => url.Contains("hooks.slack.com");
+
+    public static object BuildSlackPayload(PredictArchitectureResponse response, string companyName)
+    {
+        var lines = new List<string>
+        {
+            $"*🏗️ Predictive-ML-Core — {companyName}*",
+            response.ArchitectureSummary,
+            $"Overall architecture score: *{response.OverallArchitectureScore}/100*",
+        };
+
+        foreach (var prediction in response.Predictions)
+        {
+            foreach (var finding in prediction.Findings.Take(5))
+            {
+                lines.Add($"• `{prediction.SystemName}` *{finding.Severity}* — {finding.Title}");
+            }
+        }
+
+        foreach (var prediction in response.Predictions)
+        {
+            foreach (var recommendation in prediction.Recommendations.Take(3))
+            {
+                lines.Add($"→ *{recommendation.Title}* ({prediction.SystemName}, effort {recommendation.Effort})");
+            }
+        }
+
+        return new { text = string.Join("\n", lines) };
+    }
+
+    private static bool MeetsThreshold(PredictArchitectureResponse response, string minSeverity)
+    {
+        var threshold = SeverityRank.GetValueOrDefault(minSeverity.ToUpperInvariant(), SeverityRank["HIGH"]);
+        return response.Predictions
+            .SelectMany(p => p.Findings)
+            .Any(f => SeverityRank.GetValueOrDefault(f.Severity, 0) >= threshold);
+    }
+
+    // Retorna se o webhook foi enviado (false = abaixo do limiar ou falha de rede).
+    public static async Task<bool> NotifyAsync(
+        HttpClient client,
+        string webhookUrl,
+        PredictArchitectureResponse response,
+        string companyName,
+        string minSeverity = "HIGH")
+    {
+        if (!MeetsThreshold(response, minSeverity))
+        {
+            return false;
+        }
+
+        object payload = IsSlackWebhook(webhookUrl)
+            ? BuildSlackPayload(response, companyName)
+            : response;
+
+        try
+        {
+            using var httpResponse = await client.PostAsJsonAsync(webhookUrl, payload);
+            return true;
+        }
+        catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException or JsonException)
+        {
+            return false;
+        }
+    }
+}

src/CloudSealed.ML.Engine/Reporting/HtmlReportRenderer.cs

@@ -0,0 +1,105 @@
+using System.Text;
+using System.Text.Encodings.Web;
+using System.Text.Unicode;
+using CloudSealed.ML.Engine.Models;
+
+namespace CloudSealed.ML.Engine.Reporting;
+
+// HTML autocontido (CSS inline, sem CDN) para demo/compartilhamento — não é
+// um dashboard servido. Mesma paleta visual do relatório do JIT-Optimization-Engine
+// para consistência de marca entre os dois motores.
+public static class HtmlReportRenderer
+{
+    private static readonly Dictionary<string, string> SeverityColors = new()
+    {
+        ["LOW"] = "#6b7280",
+        ["MEDIUM"] = "#d97706",
+        ["HIGH"] = "#dc2626",
+        ["CRITICAL"] = "#991b1b",
+    };
+
+    private const string Css = """
+        body { font-family: -apple-system, Helvetica, Arial, sans-serif; max-width: 900px;
+               margin: 40px auto; padding: 0 20px; color: #1f2937; background: #fff; }
+        h1 { font-size: 22px; } h2 { font-size: 16px; margin-top: 32px; color: #374151; }
+        .summary { color: #4b5563; }
+        .cards { display: flex; gap: 16px; margin: 20px 0; flex-wrap: wrap; }
+        .card { border: 1px solid #e5e7eb; border-radius: 8px; padding: 12px 16px; min-width: 140px; }
+        .card .label { font-size: 12px; color: #6b7280; text-transform: uppercase; }
+        .card .value { font-size: 22px; font-weight: 600; }
+        table { border-collapse: collapse; width: 100%; margin-top: 8px; }
+        th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid #e5e7eb; font-size: 13px; }
+        th { color: #6b7280; font-weight: 600; }
+        .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; color: #fff; font-size: 11px; font-weight: 600; }
+        footer { margin-top: 40px; color: #9ca3af; font-size: 12px; }
+        """;
+
+    public static string Render(PredictArchitectureResponse response, string companyName)
+    {
+        var title = string.IsNullOrWhiteSpace(companyName)
+            ? "Predictive-ML-Core"
+            : $"Predictive-ML-Core — {companyName}";
+
+        var findingRows = new StringBuilder();
+        var recommendationRows = new StringBuilder();
+        foreach (var prediction in response.Predictions)
+        {
+            foreach (var finding in prediction.Findings)
+            {
+                var color = SeverityColors.GetValueOrDefault(finding.Severity, "#6b7280");
+                findingRows.Append(
+                    $"<tr><td>{Esc(prediction.SystemName)}</td>"
+                    + $"<td><span class='badge' style='background:{color}'>{Esc(finding.Severity)}</span></td>"
+                    + $"<td>{Esc(finding.Title)}</td><td>{Esc(finding.Description)}</td></tr>");
+            }
+            foreach (var recommendation in prediction.Recommendations)
+            {
+                recommendationRows.Append(
+                    $"<tr><td>{Esc(prediction.SystemName)}</td><td>{Esc(recommendation.Title)}</td>"
+                    + $"<td>{Esc(recommendation.Effort)}</td><td>{Esc(recommendation.Description)}</td></tr>");
+            }
+        }
+
+        var findingsBody = findingRows.Length > 0 ? findingRows.ToString() : "<tr><td colspan=\"4\">None found.</td></tr>";
+        var recommendationsBody = recommendationRows.Length > 0 ? recommendationRows.ToString() : "<tr><td colspan=\"4\">None.</td></tr>";
+
+        return $"""
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+            <meta charset="utf-8">
+            <title>{Esc(title)}</title>
+            <style>{Css}</style>
+            </head>
+            <body>
+            <h1>{Esc(title)}</h1>
+            <p class="summary">{Esc(response.ArchitectureSummary)}</p>
+            <div class="cards">
+              <div class="card"><div class="label">Overall score</div><div class="value">{response.OverallArchitectureScore}/100</div></div>
+              <div class="card"><div class="label">Systems</div><div class="value">{response.Predictions.Count}</div></div>
+              <div class="card"><div class="label">Findings</div><div class="value">{response.Predictions.Sum(p => p.Findings.Count)}</div></div>
+            </div>
+            <h2>Findings</h2>
+            <table>
+            <tr><th>System</th><th>Severity</th><th>Title</th><th>Description</th></tr>
+            {findingsBody}
+            </table>
+            <h2>Recommendations</h2>
+            <table>
+            <tr><th>System</th><th>Title</th><th>Effort</th><th>Description</th></tr>
+            {recommendationsBody}
+            </table>
+            <footer>Generated by <a href="https://github.com/cloudsealed/Predictive-ML-Core">Predictive-ML-Core</a>
+            — deterministic, auditable rule scoring.</footer>
+            </body>
+            </html>
+            """;
+    }
+
+    // UnicodeRanges.All keeps accented/UTF-8 text readable in the source
+    // (matching cloudsealed_jit's report.py, which uses Python's html.escape)
+    // while still escaping the characters that matter for XSS: &<>"'.
+    private static readonly HtmlEncoder Encoder = HtmlEncoder.Create(UnicodeRanges.All);
+
+    private static string Esc(string value) => Encoder.Encode(value);
+}