Prom Clinic

Review your Prometheus configuration from your own scripts

Send Prometheus configuration — prometheus.yml, rule files, or both concatenated — and get back one JSON object: a production-readiness posture, the inventory of every scrape job, rule group, alert and recording rule with its role, prioritized findings across correctness, alerting, cardinality, reliability, security, cost and hygiene, each with a corrected YAML fragment, quick wins, and the focus areas to work through first. Everything this app does goes through the SkillSafe App API — plain JSON over HTTPS — so you can hang a review off a pull request that touches monitoring/, a rules directory about to ship, or a pre-merge gate. Every code step below is shown in cURL, Python, JavaScript, Go, Java, Ruby, PHP and C#; pick a language once and the whole page follows.

Basics

Base URL: https://api.skillsafe.ai/v1/app-api, app slug prom-clinic. Every request sends Authorization: Bearer <token> and JSON bodies with Content-Type: application/json. Responses are wrapped in an envelope: {"data": …} on success, {"error": {"code", "message"}} on failure. The review itself is produced by the gpt-terra model. Estimates are free; runs are metered against your credit balance. There is a single run task — one bundle of YAML in, one review out, no follow-up calls and no session state to carry.

Status	Meaning
`401`	Missing or expired token — create a new session.
`402`	Not enough credits — top up at `skillsafe.ai/account/credits`.
`403`	The token isn't allowed to do this (e.g. a guest reviewing a very large configuration).
`404`	Unknown job or record id.
`5xx`	Transient platform error — retry with backoff.

Browsers enforce CORS for this API, so run these examples from a server, script or terminal — not from another website's frontend.

Step 0 — A tiny client

Every task below is a single HTTP call, so start with a short helper that adds the auth header, sends JSON and unwraps the data envelope. The later steps reuse it.

export API="https://api.skillsafe.ai/v1/app-api"
export TOKEN="YOUR_TOKEN"      # see step 1

# every call looks like:
#   curl -s "$API/..." -H "Authorization: Bearer $TOKEN" [-d '{json}']
# jq is used below to pull fields out of the {"data": ...} envelope

import json, requests

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"  # see step 1 — read it from your shell environment in real code

def api(method, path, body=None, **headers):
    res = requests.request(method, API + path, json=body,
                           headers={"Authorization": f"Bearer {TOKEN}", **headers})
    payload = res.json()
    if not res.ok:
        raise RuntimeError(payload.get("error", {}).get("message", res.reason))
    return payload["data"]

// Node 18+ (built-in fetch)
const API = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN"; // see step 1 — read it from your shell environment in real code

async function api(method, path, body, extraHeaders = {}) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", ...extraHeaders },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? res.statusText);
  return json.data;
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const API = "https://api.skillsafe.ai/v1/app-api"

var token = os.Getenv("SKILLSAFE_TOKEN") // see step 1

func call(method, path string, body, out any) error {
	var buf bytes.Buffer
	if body != nil {
		json.NewEncoder(&buf).Encode(body)
	}
	req, _ := http.NewRequest(method, API+path, &buf)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	var env struct {
		Data  json.RawMessage `json:"data"`
		Error *struct{ Message string `json:"message"` } `json:"error"`
	}
	json.NewDecoder(res.Body).Decode(&env)
	if res.StatusCode >= 400 {
		return fmt.Errorf("api %s %s: %s", method, path, env.Error.Message)
	}
	if out == nil {
		return nil
	}
	return json.Unmarshal(env.Data, out)
}

// Java 17+, no dependencies. Pair with your JSON library (Jackson, Gson…)
// to read fields out of the returned envelope.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SkillSafe {
    static final String API = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = System.getenv("SKILLSAFE_TOKEN"); // see step 1
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String api(String method, String path, String jsonBody) throws Exception {
        var req = HttpRequest.newBuilder(URI.create(API + path))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method(method, jsonBody == null
                ? HttpRequest.BodyPublishers.noBody()
                : HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();
        var res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) throw new RuntimeException(res.body());
        return res.body(); // envelope: {"data": …}
    }
}

require "net/http"
require "json"

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = ENV.fetch("SKILLSAFE_TOKEN") # see step 1

def api(method, path, body = nil)
  uri = URI(API + path)
  req = Net::HTTP.const_get(method.capitalize).new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"] = "application/json"
  req.body = body.to_json if body
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
  payload = JSON.parse(res.body)
  raise (payload.dig("error", "message") || res.message) unless res.is_a?(Net::HTTPSuccess)
  payload["data"]
end

<?php
const API = "https://api.skillsafe.ai/v1/app-api";
$TOKEN = getenv("SKILLSAFE_TOKEN"); // see step 1

function api(string $method, string $path, ?array $body = null): mixed {
    global $TOKEN;
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer $TOKEN",
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS     => $body === null ? null : json_encode($body),
    ]);
    $payload = json_decode(curl_exec($ch), true);
    $status  = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($status >= 400) {
        throw new Exception($payload["error"]["message"] ?? "HTTP $status");
    }
    return $payload["data"];
}

// .NET 8+
using System.Net.Http.Json;
using System.Text.Json;

static class SkillSafe
{
    const string Api = "https://api.skillsafe.ai/v1/app-api";
    static readonly HttpClient Http = new();

    static SkillSafe() =>
        Http.DefaultRequestHeaders.Authorization =
            new("Bearer", Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN")); // see step 1

    public static async Task<JsonElement> ApiAsync(HttpMethod method, string path, object? body = null)
    {
        var req = new HttpRequestMessage(method, Api + path);
        if (body != null) req.Content = JsonContent.Create(body);
        var res = await Http.SendAsync(req);
        var json = await res.Content.ReadFromJsonAsync<JsonElement>();
        if (!res.IsSuccessStatusCode)
            throw new Exception(json.GetProperty("error").GetProperty("message").GetString());
        return json.GetProperty("data");
    }
}

Step 1 — Get a token

POST /guest

A guest token lets you check balances and estimate costs for free. For metered review runs billed to your own account, use your personal token: open the token page, sign in with SkillSafe, and press Copy shell export — it puts export SKILLSAFE_TOKEN="…" on your clipboard, which every example below reads. Treat the token like a password: it can spend your credits. For fully headless scripts, POST /guest mints a guest token with no browser involved.

curl -s -X POST "$API/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"prom-clinic"}' | jq -r '.data.token'

token = api("POST", "/guest", {"slug": "prom-clinic"})["token"]

const { token } = await api("POST", "/guest", { slug: "prom-clinic" });

var guest struct{ Token string `json:"token"` }
err := call("POST", "/guest", map[string]string{"slug": "prom-clinic"}, &guest)

String envelope = api("POST", "/guest", """
    {"slug":"prom-clinic"}""");
// token is at data.token in the returned JSON

token = api("POST", "/guest", { slug: "prom-clinic" })["token"]

$token = api("POST", "/guest", ["slug" => "prom-clinic"])["token"];

var guest = await SkillSafe.ApiAsync(HttpMethod.Post, "/guest",
    new { slug = "prom-clinic" });
var token = guest.GetProperty("token").GetString();

The app stores this browser's token under the localStorage key skillsafe_app_token:prom-clinic, on the app's own origin. The token page reads and manages it for you — you never need to open developer tools.

Step 2 — Check who you are and your balance

GET /me

Returns subject_type ("user" or "guest"), subject_id and your credits balance. Check this before reviewing a large bundle.

curl -s "$API/me" -H "Authorization: Bearer $TOKEN" | jq '.data'

me = api("GET", "/me")
print(me["subject_type"], me["credits"])

const me = await api("GET", "/me");
console.log(me.subject_type, me.credits);

var me struct {
	SubjectType string `json:"subject_type"`
	Credits     int64  `json:"credits"`
}
err := call("GET", "/me", nil, &me)

String envelope = api("GET", "/me", null);
// data.subject_type, data.credits

me = api("GET", "/me")
puts "#{me["subject_type"]}: #{me["credits"]} credits"

$me = api("GET", "/me");
echo "{$me['subject_type']}: {$me['credits']} credits\n";

var me = await SkillSafe.ApiAsync(HttpMethod.Get, "/me");
Console.WriteLine($"{me.GetProperty("subject_type")}: {me.GetProperty("credits")} credits");

Step 3 — Estimate the cost

POST /estimate

Send exactly the input you would send to /run; the response's hold_credits is the worst-case cost. Nothing is charged and no job is created, so estimating is free — useful when you are piping a whole rules directory in and want a ceiling before spending credits.

Input field	Type	Notes
`config`	string, required	The Prometheus configuration, exactly as it sits on disk. `prometheus.yml`, one or more rule files, or several files concatenated — a `# filename.yml` comment line between them helps the reviewer name things. This is the model's only evidence — nothing is read from a live server or its TSDB. Configurations longer than 100,000 characters are clipped middle-out, with a `# [... clipped ...]` comment showing where. At least 60 characters are needed for a review.
`setup`	string	`single` \| `ha-pair` \| `kubernetes` \| `federation` \| `agent` \| `unknown` — how this Prometheus is deployed, which sets the reliability idioms the reviewer leans on. If the YAML itself clearly shows the shape, the YAML wins.
`concern`	string	`general` \| `alerting` \| `cardinality` \| `reliability` \| `security` — the review emphasis. It weights the findings and the summary, but it is emphasis and not exclusivity: a high-severity finding from another category is never suppressed.
`context`	string, optional	Extra context: how many targets this scrapes, whether retention and storage flags are set outside the paste (command line, StatefulSet args), what Alertmanager routing already exists, whether this is one replica of an HA pair, and any gap you have already chosen to accept. Clipped at 20,000 characters.
`prescan_facts`	object, optional	What a client-side scanner mechanically matched in the YAML: `{"units": [], "flags": []}`. Each entry is `{id, label}`. Unit ids look like `unit:scrape_job/node-exporter`; flag ids are `<check>:<name>` — `plain-secret:password`, `hot-scrape:scrape_interval-2s`, `no-for:appdown`, `no-severity:appdown`, `no-annotations:appdown`, `rule-naming:request_rate`, `no-ext-labels:set`, `no-rule-files:rules`, `insecure-scheme:set`, `honor-labels:set`, `wide-regex:keep`, `no-retention:set`. Every flag id you send comes back in `coverage_check`. The web UI fills this from its own scan; API callers may omit the field or send the two empty arrays.
`retry_note`	string, optional	Only set by the app's automatic reformat retry when a first reply was not valid JSON. Leave it out.

cat > prometheus.yml <<'YAML'
scrape_configs:
  - job_name: app
    scrape_interval: 2s
    basic_auth:
      username: metrics
      password: hunter2
    static_configs:
      - targets: ["app1.internal:9102"]
YAML

jq -n --rawfile config prometheus.yml \
  '{config: $config,
    setup: "single",
    concern: "general",
    context: "Single Prometheus on a VM watching two app servers; retention flags unset.",
    prescan_facts: {units: [], flags: []}}' > input.json

curl -s -X POST "$API/estimate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @input.json | jq '.data.hold_credits'

CONFIG = """scrape_configs:
  - job_name: app
    scrape_interval: 2s
    basic_auth:
      username: metrics
      password: hunter2
    static_configs:
      - targets: ["app1.internal:9102"]
"""

payload = {
    "config": CONFIG,
    "setup": "single",
    "concern": "general",
    "context": "Single Prometheus on a VM watching two app servers; retention flags unset.",
    "prescan_facts": {"units": [], "flags": []},
}

est = api("POST", "/estimate", payload)
print("worst case:", est.get("hold_credits", est.get("credits")), "credits")

const config = `scrape_configs:
  - job_name: app
    scrape_interval: 2s
    basic_auth:
      username: metrics
      password: hunter2
    static_configs:
      - targets: ["app1.internal:9102"]
`;

const payload = {
  config,
  setup: "single",
  concern: "general",
  context: "Single Prometheus on a VM watching two app servers; retention flags unset.",
  prescan_facts: { units: [], flags: [] },
};

const est = await api("POST", "/estimate", payload);
console.log("worst case:", est.hold_credits ?? est.credits, "credits");

const config = `scrape_configs:
  - job_name: app
    scrape_interval: 2s
    basic_auth:
      username: metrics
      password: hunter2
    static_configs:
      - targets: ["app1.internal:9102"]
`

payload := map[string]any{
	"config": config,
	"setup":  "single",
	"concern":  "general",
	"context":  "Single Prometheus on a VM watching two app servers; retention flags unset.",
	"prescan_facts": map[string]any{
		"units": []any{}, "flags": []any{},
	},
}

var est struct{ HoldCredits int64 `json:"hold_credits"` }
err := call("POST", "/estimate", payload, &est)

String config = """
    scrape_configs:
      - job_name: app
        scrape_interval: 2s
        basic_auth:
          username: metrics
          password: hunter2
        static_configs:
          - targets: ["app1.internal:9102"]
    """;

String jsonPayload = """
    {"config": %s,
     "setup": "single",
     "concern": "general",
     "context": "Single Prometheus on a VM watching two app servers; retention flags unset.",
     "prescan_facts": {"units": [], "flags": []}}
    """.formatted(toJsonString(config));

String envelope = api("POST", "/estimate", jsonPayload);
// worst-case cost is at data.hold_credits

CONFIG = <<~YAML
  scrape_configs:
    - job_name: app
      scrape_interval: 2s
      basic_auth:
        username: metrics
        password: hunter2
      static_configs:
        - targets: ["app1.internal:9102"]
YAML

payload = { config: CONFIG,
            setup: "single",
            concern: "general",
            context: "Single Prometheus on a VM watching two app servers; retention flags unset.",
            prescan_facts: { units: [], flags: [] } }

est = api("POST", "/estimate", payload)
puts "worst case: #{est["hold_credits"] || est["credits"]} credits"

$config = <<<'YAML'
scrape_configs:
  - job_name: app
    scrape_interval: 2s
    basic_auth:
      username: metrics
      password: hunter2
    static_configs:
      - targets: ["app1.internal:9102"]
YAML;

$payload = [
    "config"        => $config,
    "setup"         => "single",
    "concern"       => "general",
    "context"       => "Single Prometheus on a VM watching two app servers; retention flags unset.",
    "prescan_facts" => ["units" => [], "flags" => []],
];

$est = api("POST", "/estimate", $payload);
echo "worst case: " . ($est["hold_credits"] ?? $est["credits"]) . " credits\n";

var config = """
    scrape_configs:
      - job_name: app
        scrape_interval: 2s
        basic_auth:
          username: metrics
          password: hunter2
        static_configs:
          - targets: ["app1.internal:9102"]
    """;

var payload = new {
    config,
    setup = "single",
    concern = "general",
    context = "Single Prometheus on a VM watching two app servers; retention flags unset.",
    prescan_facts = new {
        units = Array.Empty<object>(), flags = Array.Empty<object>(),
    },
};

var est = await SkillSafe.ApiAsync(HttpMethod.Post, "/estimate", payload);
Console.WriteLine($"worst case: {est.GetProperty("hold_credits")} credits");

prescan_facts.flags is how you make the review answer for things you already know about. Send {"units": [{"id": "unit:scrape_job/app", "label": "scrape job \"app\""}], "flags": [{"id": "hot-scrape:scrape_interval-2s", "label": "scrape_interval is 2s"}]} and every flag id comes back in coverage_check — addressed by a finding, or set aside with the reason. Nothing you flag is silently dropped, which makes it the field to assert on in a CI check.

Step 4 — Run the review and wait for the result

POST /run

GET /jobs/{job_id}

/run takes the same input as /estimate, places a credit hold and returns a job_id. Poll /jobs/{job_id} every 1–2 seconds until status is succeeded or failed (a run typically takes 30–90 s, since every finding carries a corrected YAML fragment). Always send an Idempotency-Key header so a network retry can't start a second, double-charged run. The review is in output — usually nested as output.output, and as a JSON string, so parse defensively. The samples below print the posture, the inventory, the prioritized findings and the focus areas, then save the whole object to review.json.

JOB_ID=$(curl -s -X POST "$API/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pc-$(date +%s)" \
  -d @input.json | jq -r '.data.job_id')

while :; do
  JOB=$(curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN")
  STATUS=$(echo "$JOB" | jq -r '.data.status')
  [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done

# unwrap the review once, then read it
echo "$JOB" | jq -r '.data.output.output' > review.json

jq -r '
  "\(.review_name) [\(.posture)]: \(.verdict)",
  "",
  "INVENTORY",
  (.inventory[] | "  \(.kind)/\(.name) in \(.group) - \(.role)"),
  "",
  "FINDINGS",
  (.findings[] | "  [\(.priority)] \(.id) \(.category) \(.resource): \(.problem)"),
  "",
  "QUICK WINS",
  (.quick_wins[] | "  - \(.)"),
  "",
  "FOCUS AREAS",
  (.focus_areas[] | "  \(.area) - \(.why)"),
  "",
  "COVERAGE",
  (.coverage_check[] | "  \(.id): \(if .addressed then "ok" else "SET ASIDE" end) - \(.note)")' \
  review.json

# fail the pipeline on anything critical
jq -e '[.findings[] | select(.priority == "critical")] | length == 0' review.json > /dev/null \
  || { echo "critical findings present"; exit 1; }

import time

job_id = api("POST", "/run", payload,
             **{"Idempotency-Key": "pc-001"})["job_id"]

while True:
    job = api("GET", f"/jobs/{job_id}")
    if job["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.5)

if job["status"] == "failed":
    raise RuntimeError(job.get("error", "run failed"))

raw = job["output"]
if isinstance(raw, dict) and "output" in raw:
    raw = raw["output"]
review = json.loads(raw) if isinstance(raw, str) else raw

print(f'{review["review_name"]} [{review["posture"]}]: {review["verdict"]}')
for r in review["inventory"]:
    print(f'  {r["kind"]}/{r["name"]:<24} grp={r["group"] or "-":<12} {r["role"]}')
for f in review["findings"]:
    print(f'  [{f["priority"]:>8}] {f["id"]} {f["category"]} {f["resource"]}')
    print(f'      L:{f["likelihood"]}/S:{f["severity"]} {f["problem"]}')
    print(f'      fix: {f["fix"]}')
    if f["snippet"]:
        print("      snippet:", f["snippet"].splitlines()[0], "...")
for w in review["quick_wins"]:
    print("  win:", w)
for a in review["focus_areas"]:
    print(f'  focus {a["area"]} {a["finding_ids"]} - {a["why"]}')
for c in review["coverage_check"]:
    print(f'  {c["id"]}: {"ok" if c["addressed"] else "SET ASIDE"} - {c["note"]}')

with open("review.json", "w", encoding="utf-8") as fh:
    json.dump(review, fh, indent=2)

critical = [f for f in review["findings"] if f["priority"] == "critical"]
if critical:
    raise SystemExit(f"{len(critical)} critical finding(s)")

import { writeFileSync } from "node:fs";

const { job_id } = await api("POST", "/run", payload,
  { "Idempotency-Key": crypto.randomUUID() });

let job;
do {
  await new Promise((r) => setTimeout(r, 1500));
  job = await api("GET", `/jobs/${job_id}`);
} while (job.status !== "succeeded" && job.status !== "failed");

if (job.status === "failed") throw new Error(job.error ?? "run failed");

const raw = job.output?.output ?? job.output;
const review = typeof raw === "string" ? JSON.parse(raw) : raw;

console.log(`${review.review_name} [${review.posture}]: ${review.verdict}`);
for (const r of review.inventory) {
  console.log(`  ${r.kind}/${r.name} (${r.group || "-"}): ${r.role}`);
}
for (const f of review.findings) {
  console.log(`  [${f.priority}] ${f.id} ${f.category} ${f.resource}`);
  console.log(`      L:${f.likelihood}/S:${f.severity} - ${f.fix}`);
}
for (const w of review.quick_wins) console.log(`  win: ${w}`);
for (const a of review.focus_areas) {
  console.log(`  focus ${a.area} (${a.finding_ids.join(", ")}): ${a.why}`);
}
for (const c of review.coverage_check) {
  console.log(`  ${c.id}: ${c.addressed ? "ok" : "SET ASIDE"} - ${c.note}`);
}

writeFileSync("review.json", JSON.stringify(review, null, 2));

const critical = review.findings.filter((f) => f.priority === "critical");
if (critical.length) process.exitCode = 1;

var started struct{ JobID string `json:"job_id"` }
if err := call("POST", "/run", payload, &started); err != nil {
	log.Fatal(err)
}

var job struct {
	Status string          `json:"status"`
	Error  string          `json:"error"`
	Output json.RawMessage `json:"output"`
}
for {
	if err := call("GET", "/jobs/"+started.JobID, nil, &job); err != nil {
		log.Fatal(err)
	}
	if job.Status == "succeeded" || job.Status == "failed" {
		break
	}
	time.Sleep(1500 * time.Millisecond)
}

// job.Output is {"output": "<json string>"} — unwrap, then unmarshal:
type Review struct {
	ReviewName string `json:"review_name"`
	Posture    string `json:"posture"`
	Verdict    string `json:"verdict"`
	ExecSummary string `json:"exec_summary"`
	Assumptions   []string `json:"assumptions"`
	OpenQuestions []string `json:"open_questions"`
	Inventory []struct {
		Kind, Name, Group, Role string
	} `json:"inventory"`
	Findings []struct {
		ID, Category, Severity, Likelihood, Priority string
		Resource, Problem, Impact, Fix, Snippet      string
	} `json:"findings"`
	CoverageCheck []struct {
		ID, Note  string
		Addressed bool
	} `json:"coverage_check"`
	QuickWins  []string `json:"quick_wins"`
	FocusAreas []struct {
		Area, Why  string
		FindingIDs []string `json:"finding_ids"`
	} `json:"focus_areas"`
	Summary string `json:"summary"`
}
var wrapper struct{ Output string `json:"output"` }
json.Unmarshal(job.Output, &wrapper)
var review Review
json.Unmarshal([]byte(wrapper.Output), &review)

fmt.Printf("%s [%s]: %s\n", review.ReviewName, review.Posture, review.Verdict)
for _, r := range review.Inventory {
	fmt.Printf("  %s/%s (%s): %s\n", r.Kind, r.Name, r.Group, r.Role)
}
for _, f := range review.Findings {
	fmt.Printf("  [%s] %s %s %s: %s\n", f.Priority, f.ID, f.Category, f.Resource, f.Problem)
}
for _, a := range review.FocusAreas {
	fmt.Printf("  focus %s %v: %s\n", a.Area, a.FindingIDs, a.Why)
}
os.WriteFile("review.json", []byte(wrapper.Output), 0o644)

String envelope = api("POST", "/run", jsonPayload);
String jobId = /* data.job_id via your JSON library */;

while (true) {
    String job = api("GET", "/jobs/" + jobId, null);
    String status = /* data.status */;
    if (status.equals("succeeded") || status.equals("failed")) break;
    Thread.sleep(1500);
}
// The review is at data.output.output as a JSON string — parse it again, then read
// review_name, posture, verdict, exec_summary, assumptions[], open_questions[],
// inventory[] (kind/name/group/role),
// findings[] (id/category/severity/likelihood/priority/resource/problem/impact/fix/snippet),
// coverage_check[] (id/addressed/note), quick_wins[],
// focus_areas[] (area/why/finding_ids[]) and summary.
// Finally keep the review on disk:
//   Files.writeString(Path.of("review.json"), reviewJson);

started = api("POST", "/run", payload)

job = nil
loop do
  job = api("GET", "/jobs/#{started["job_id"]}")
  break if %w[succeeded failed].include?(job["status"])
  sleep 1.5
end
raise (job["error"] || "run failed") if job["status"] == "failed"

raw = job["output"].is_a?(Hash) ? job["output"].fetch("output", job["output"]) : job["output"]
review = raw.is_a?(String) ? JSON.parse(raw) : raw

puts "#{review["review_name"]} [#{review["posture"]}]: #{review["verdict"]}"
review["inventory"].each { |r| puts "  #{r["kind"]}/#{r["name"]} (#{r["group"]}): #{r["role"]}" }
review["findings"].each do |f|
  puts "  [#{f["priority"]}] #{f["id"]} #{f["category"]} #{f["resource"]}"
  puts "      L:#{f["likelihood"]}/S:#{f["severity"]} - #{f["fix"]}"
end
review["quick_wins"].each { |w| puts "  win: #{w}" }
review["focus_areas"].each { |a| puts "  focus #{a["area"]} #{a["finding_ids"].join(", ")}" }
review["coverage_check"].each { |c| puts "  #{c["id"]}: #{c["addressed"] ? "ok" : "SET ASIDE"}" }

File.write("review.json", JSON.pretty_generate(review))
exit 1 if review["findings"].any? { |f| f["priority"] == "critical" }

$started = api("POST", "/run", $payload);

do {
    sleep(2);
    $job = api("GET", "/jobs/" . $started["job_id"]);
} while (!in_array($job["status"], ["succeeded", "failed"]));

if ($job["status"] === "failed") {
    throw new Exception($job["error"] ?? "run failed");
}

$raw = is_array($job["output"]) ? ($job["output"]["output"] ?? $job["output"]) : $job["output"];
$review = is_string($raw) ? json_decode($raw, true) : $raw;

echo "{$review['review_name']} [{$review['posture']}]: {$review['verdict']}\n";
foreach ($review["inventory"] as $r) {
    echo "  {$r['kind']}/{$r['name']} ({$r['group']}): {$r['role']}\n";
}
foreach ($review["findings"] as $f) {
    echo "  [{$f['priority']}] {$f['id']} {$f['category']} {$f['resource']}\n";
    echo "      L:{$f['likelihood']}/S:{$f['severity']} - {$f['fix']}\n";
}
foreach ($review["quick_wins"] as $w) {
    echo "  win: $w\n";
}
foreach ($review["focus_areas"] as $a) {
    echo "  focus {$a['area']}: " . implode(", ", $a["finding_ids"]) . "\n";
}
foreach ($review["coverage_check"] as $c) {
    echo "  {$c['id']}: " . ($c["addressed"] ? "ok" : "SET ASIDE") . "\n";
}

file_put_contents("review.json", json_encode($review, JSON_PRETTY_PRINT));

var started = await SkillSafe.ApiAsync(HttpMethod.Post, "/run", payload);
var jobId = started.GetProperty("job_id").GetString();

JsonElement job;
while (true)
{
    job = await SkillSafe.ApiAsync(HttpMethod.Get, $"/jobs/{jobId}");
    var status = job.GetProperty("status").GetString();
    if (status is "succeeded" or "failed") break;
    await Task.Delay(1500);
}

var rawText = job.GetProperty("output").GetProperty("output").GetString();
using var doc = JsonDocument.Parse(rawText!);
var review = doc.RootElement;

Console.WriteLine($"{review.GetProperty("review_name")} " +
                  $"[{review.GetProperty("posture")}]: {review.GetProperty("verdict")}");
foreach (var r in review.GetProperty("inventory").EnumerateArray())
{
    Console.WriteLine($"  {r.GetProperty("kind")}/{r.GetProperty("name")}: {r.GetProperty("role")}");
}
foreach (var f in review.GetProperty("findings").EnumerateArray())
{
    Console.WriteLine($"  [{f.GetProperty("priority")}] {f.GetProperty("id")} " +
                      $"{f.GetProperty("category")} {f.GetProperty("resource")} " +
                      $"(L:{f.GetProperty("likelihood")}/S:{f.GetProperty("severity")})");
}
foreach (var a in review.GetProperty("focus_areas").EnumerateArray())
{
    Console.WriteLine($"  focus {a.GetProperty("area")}: {a.GetProperty("why")}");
}

await File.WriteAllTextAsync("review.json", rawText!);

The model is asked for one JSON object and nothing else, but a stray code fence or preamble is always possible. Strip a leading ```json fence, take the text between the first { and the last }, and only then parse — that is what the app does before it falls back to a retry_note reformat run.

The review object — output schema

One JSON object, always the same shape. Every array is present, and the review is grounded in the pasted YAML alone: findings cite only jobs and rules that actually appear in config, and something that is simply absent (no external_labels, no for: on an alert, no retention bound) is reported against the closest real unit or against (missing from the configuration). Where the YAML is silent on something that changes the verdict you get an entry in assumptions and, if it would change the ranking, in open_questions. Expect five to fifteen findings on a typical configuration — a well-built setup may honestly yield two or three, and findings is never empty.

Field	Type	Meaning
`review_name`	string	A short title naming the configuration, taken from the YAML's own naming — e.g. `api fleet monitoring — Prometheus review`.
`posture`	string	`production-ready` \| `hardening-recommended` \| `not-production-ready`. See the table below.
`verdict`	string	One sentence justifying the posture and naming the single most important change.
`exec_summary`	string	Two or three paragraphs, separated by blank lines, on the dominant themes across the set.
`assumptions`	string[]	Explicit assumptions filling gaps the YAML left open. Read these first — a wrong assumption invalidates the findings built on it.
`open_questions`	string[]	Questions whose answers would change the ranking.
`inventory`	array	`{kind, name, group, role}` — every unit the review parsed out of the paste and the part it plays. `kind` is the unit type (`scrape_job`, `rule_group`, `alert`, `recording_rule`, `global`, `alerting`, `remote_write`, `other`); `group` is the rule group or `# filename` the unit sits under, or `-`.
`findings`	array	The prioritized findings table — ids `PC-001`, `PC-002`, … in sequence, at least one entry. Columns are listed below.
`coverage_check`	array	`{id, addressed, note}` — one entry per `prescan_facts.flags` id you sent, each appearing exactly once. See the semantics below.
`quick_wins`	string[]	One-line changes worth doing immediately, ahead of any planning. May be empty when nothing here is a one-liner.
`focus_areas`	array	`{area, why, finding_ids}` — what to work through first, one sentence tied to the review, and the finding ids that motivate it. Every id in `finding_ids` exists in `findings`.
`summary`	string	Closing paragraph: what to fix first, and what risk remains after that.

The three posture values:

posture	What it means
`production-ready`	The configuration holds up as written: sane intervals, external_labels, alerts that hold before firing and route on severity, recorded rules named by convention, no literal secrets, bounded storage. Findings still exist, but they are additions and refinements, not blockers. A genuinely well-built setup lands here rather than having severity manufactured for it.
`hardening-recommended`	The shape is right, but named gaps should be closed before this carries the on-call rotation — alerts missing for: or annotations, recording rules off the naming convention, no external_labels, retention unstated.
`not-production-ready`	At least one thing loses pages, leaks a credential or takes the server down as written: rules that never load, alerts with no Alertmanager to reach, a literal password sent over plain HTTP, an interval or cardinality pattern that will fill the disk.

Each entry in findings:

Column	Meaning
`id`	Sequential `PC-001`, `PC-002`, … — the stable handle referenced from `focus_areas[].finding_ids`.
`category`	`correctness` \| `alerting` \| `cardinality` \| `reliability` \| `security` \| `cost` \| `hygiene`. Weighted by the `concern` you sent, but never restricted to it.
`severity`	`low` \| `medium` \| `high` — how bad it is when it bites.
`likelihood`	`low` \| `medium` \| `high` — how likely it is to bite.
`priority`	`critical` \| `high` \| `medium` \| `low` — severity by likelihood. `critical` is reserved for something that loses pages, leaks a credential or fills the disk as written, so sort on this field and work top-down. This is also the field to gate a pipeline on.
`resource`	The unit this is about — e.g. `alert HighErrorRate` or `scrape job node-exporter` — always something that appears in `config`, or the literal `(missing from the configuration)` when the finding is about an absent setting.
`problem`	What is wrong, in this YAML specifically.
`impact`	What happens in production because of it — the missed page, the false page, the exploded series count, the filled disk.
`fix`	The concrete change to make — not "add validation".
`snippet`	A corrected YAML fragment you can paste: the fixed job or rule, correctly indented, not the whole file. Empty string when a snippet would add nothing. Secret values are never echoed — a placeholder appears instead.

coverage_check semantics:

Case	What you get
Every flag id you sent	Each `prescan_facts.flags` id appears in `coverage_check` exactly once. Nothing you flagged is silently dropped, which makes this the field to assert on in a CI check. Ids in `prescan_facts.units` are not reconciled here — they shape the inventory instead.
`addressed: true`	The flag is covered by the review; `note` names the finding id that covers it.
`addressed: false`	The flag was deliberately set aside; `note` gives the reason — a check that fired but is not a real problem for this configuration (retention set on the command line outside the paste, honor_labels on a federation job).
Nothing sent	Omit `prescan_facts`, or send the two empty arrays, and `coverage_check` comes back empty. The rest of the review is unaffected.

A small, realistic result for the hot-interval scrape job above, trimmed for length:

{
  "review_name": "app scrape job — Prometheus review",
  "posture": "not-production-ready",
  "verdict": "A literal basic-auth password sent over plain HTTP and a 2s scrape interval make this
              unshippable as written; move the credential to password_file first.",
  "exec_summary": "Two themes dominate: a credential is written into the configuration and travels
                   in the clear on every scrape, and the 2s interval multiplies ingestion and target
                   load thirtyfold against a 60s baseline for resolution nothing here needs.

                   None of it needs a redesign — the fixes are all one-job edits, and the corrected
                   fragments below can be applied one at a time.",
  "assumptions": [
    "app1.internal is reachable only inside the network, but the scrape still crosses it unencrypted.",
    "Retention and storage flags are set outside this paste, since none appear."
  ],
  "open_questions": [
    "Does anything actually consume sub-15s resolution for this job, or is 2s an accident?",
    "Is there a TLS endpoint on the exporter, or does it need a sidecar?"
  ],
  "inventory": [
    { "kind": "scrape_job", "name": "app", "group": "-",
      "role": "Scrapes the two app servers with basic auth over plain HTTP every 2s." }
  ],
  "findings": [
    { "id": "PC-001", "category": "security",
      "severity": "high", "likelihood": "high", "priority": "critical",
      "resource": "scrape job app",
      "problem": "basic_auth.password is a string literal, and scheme defaults to plain HTTP.",
      "impact": "The credential is in Git history and crosses the network base64-encoded in every
                 scrape; anyone on the path or with repo access owns the metrics endpoint.",
      "fix": "Move the secret to password_file and scrape over TLS.",
      "snippet": "  - job_name: app\n    scheme: https\n    tls_config:\n      ca_file: /etc/prometheus/ca.crt\n    basic_auth:\n      username: metrics\n      password_file: /etc/prometheus/secrets/app-metrics\n    static_configs:\n      - targets: [\"app1.internal:9102\"]" },
    { "id": "PC-002", "category": "cost",
      "severity": "medium", "likelihood": "high", "priority": "high",
      "resource": "scrape job app",
      "problem": "scrape_interval: 2s on an application job.",
      "impact": "Thirty times the samples of a 60s job for the same dashboards; TSDB churn, memory
                 and target CPU all scale with it, for resolution no alert here uses.",
      "fix": "Drop the override and let the job inherit a 15-60s global interval.",
      "snippet": "" }
  ],
  "coverage_check": [
    { "id": "plain-secret:password", "addressed": true, "note": "PC-001." },
    { "id": "hot-scrape:scrape_interval-2s", "addressed": true, "note": "PC-002." },
    { "id": "no-retention:set", "addressed": false,
      "note": "Set aside: the context says retention flags live on the systemd unit outside this
               paste, so nothing is missing from the server config itself." }
  ],
  "quick_wins": [
    "Delete the scrape_interval: 2s override — one line.",
    "Swap password: for password_file: once the secret file is mounted."
  ],
  "focus_areas": [
    { "area": "Credential out of the config and off the wire",
      "why": "A leaked scrape credential outlives every other fix in this review.",
      "finding_ids": ["PC-001"] },
    { "area": "Ingestion budget",
      "why": "The hot interval is the difference between this server coping and paging you about itself.",
      "finding_ids": ["PC-002"] }
  ],
  "summary": "Move the password to a file reference and put TLS on the scrape, then relax the
              interval to the global default. …"
}

This is AI-generated review from YAML text, not a production sign-off: it sees only what you sent, never the live server, its targets or its TSDB. Check assumptions and open_questions before you act on the rankings, validate every snippet with promtool check config and promtool check rules, and keep a human reviewer in the loop.

Step 5 — Stream the review as it is written

POST /run-stream

/run-stream takes exactly the same body as /run but answers with server-sent events, so you can show progress instead of a spinner — useful here because a full findings table with corrected YAML makes for a long reply. This app's own progress panel is this endpoint. Events are separated by a blank line; each has an event: line and a data: line carrying JSON.

Event	Payload	Meaning
`job`	`{job_id, status}`	Sent once, when the job is accepted — show "starting".
`delta`	`{text}`	A chunk of the reply, in order. Append it; the accumulated length is your only progress signal (the total is not known in advance). The app advances its step list by watching for the `"review_name"`, `"inventory"`, `"findings"`, `"coverage_check"` and `"focus_areas"` keys as they arrive.
`done`	`{job_id, status, charged_credits, output}`	The final, authoritative result — read the review from `output.output` rather than trusting concatenated deltas, and the settled price from `charged_credits`.
`error`	`{code, message}`	Replaces `done` when the run fails.

# -N disables buffering so events print as they arrive
curl -N -s -X POST "$API/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pc-$(date +%s)" \
  -d @input.json

# event: job
# data: {"job_id":"job_...","status":"running"}
#
# event: delta
# data: {"text":"{\"review_name\":\"app scrape"}
# ...
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":612,"output":{"output":"{...}"}}

import json, requests

result = None
with requests.post(
    API + "/run-stream",
    headers={"Authorization": f"Bearer {TOKEN}",
             "Idempotency-Key": "pc-001"},
    json=payload,
    stream=True,
) as r:
    r.raise_for_status()
    event = None
    for line in r.iter_lines(decode_unicode=True):
        if not line:
            continue
        if line.startswith("event:"):
            event = line[len("event:"):].strip()
        elif line.startswith("data:"):
            data = json.loads(line[len("data:"):].strip())
            if event == "delta":
                print(".", end="", flush=True)          # live progress
            elif event == "done":
                result = data
            elif event == "error":
                raise RuntimeError(data.get("message", "run failed"))

review = json.loads(result["output"]["output"])          # authoritative
print("charged:", result["charged_credits"], "-", review["review_name"])
print("posture:", review["posture"])
for f in review["findings"]:
    print(f'  [{f["priority"]}] {f["id"]} {f["resource"]}: {f["problem"]}')
with open("review.json", "w", encoding="utf-8") as fh:
    json.dump(review, fh, indent=2)

const res = await fetch(API + "/run-stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify(payload),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = "", done = null;

for (;;) {
  const chunk = await reader.read();
  if (chunk.done) break;
  buf += decoder.decode(chunk.value, { stream: true });
  const frames = buf.split("\n\n");
  buf = frames.pop();
  for (const frame of frames) {
    const name = /^event:\s*(.+)$/m.exec(frame)?.[1];
    const body = /^data:\s*(.+)$/m.exec(frame)?.[1];
    if (!name || !body) continue;
    const data = JSON.parse(body);
    if (name === "delta") process.stdout.write(".");   // live progress
    if (name === "done") done = data;
    if (name === "error") throw new Error(data.message ?? "run failed");
  }
}

const review = JSON.parse(done.output.output);
console.log(`\n${done.charged_credits} credits - ${review.review_name} [${review.posture}]`);
for (const f of review.findings) console.log(`  [${f.priority}] ${f.id} ${f.resource}`);
writeFileSync("review.json", JSON.stringify(review, null, 2));

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", API+"/run-stream", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "pc-001")

res, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()

var event string
var final map[string]any
sc := bufio.NewScanner(res.Body)
sc.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
for sc.Scan() {
	line := sc.Text()
	switch {
	case strings.HasPrefix(line, "event:"):
		event = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
	case strings.HasPrefix(line, "data:"):
		var data map[string]any
		json.Unmarshal([]byte(strings.TrimPrefix(line, "data:")), &data)
		switch event {
		case "delta":
			fmt.Print(".") // live progress
		case "done":
			final = data
		case "error":
			log.Fatal(data["message"])
		}
	}
}
// final["output"].(map[string]any)["output"].(string) is the review JSON —
// unmarshal it into the Review struct from step 4, then write it to review.json.

// Java 17+ — read the stream line by line instead of buffering the body.
var req = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "pc-001")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

var res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());
String event = null, done = null;
for (String line : (Iterable<String>) res.body()::iterator) {
    if (line.startsWith("event:")) {
        event = line.substring(6).trim();
    } else if (line.startsWith("data:")) {
        String data = line.substring(5).trim();
        if ("delta".equals(event)) System.out.print(".");   // live progress
        else if ("done".equals(event)) done = data;
        else if ("error".equals(event)) throw new RuntimeException(data);
    }
}
// parse `done`, then parse data.output.output again — it is a JSON string holding
// review_name, posture, verdict, inventory[], findings[], coverage_check[],
// quick_wins[], focus_areas[] and the rest.

require "net/http"
require "json"

uri = URI(API + "/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "kc-001"
req.body = payload.to_json

event = nil
done = nil
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(req) do |res|
    res.read_body do |chunk|
      chunk.each_line do |line|
        line = line.strip
        if line.start_with?("event:")
          event = line.delete_prefix("event:").strip
        elsif line.start_with?("data:")
          data = JSON.parse(line.delete_prefix("data:").strip)
          case event
          when "delta" then print "."           # live progress
          when "done"  then done = data
          when "error" then raise (data["message"] || "run failed")
          end
        end
      end
    end
  end
end

review = JSON.parse(done["output"]["output"])
puts "\n#{done["charged_credits"]} credits - #{review["review_name"]} [#{review["posture"]}]"
review["findings"].each { |f| puts "  [#{f["priority"]}] #{f["id"]} #{f["resource"]}" }
File.write("review.json", JSON.pretty_generate(review))

$event = null;
$done  = null;

$ch = curl_init(API . "/run-stream");
curl_setopt_array($ch, [
    CURLOPT_POST       => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $TOKEN",
        "Content-Type: application/json",
        "Idempotency-Key: kc-001",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$event, &$done) {
        foreach (explode("\n", $chunk) as $line) {
            $line = trim($line);
            if (str_starts_with($line, "event:")) {
                $event = trim(substr($line, 6));
            } elseif (str_starts_with($line, "data:")) {
                $data = json_decode(trim(substr($line, 5)), true);
                if ($event === "delta") { echo "."; }        // live progress
                elseif ($event === "done") { $done = $data; }
                elseif ($event === "error") { throw new Exception($data["message"] ?? "run failed"); }
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
curl_close($ch);

$review = json_decode($done["output"]["output"], true);
echo "\n{$done['charged_credits']} credits - {$review['review_name']} [{$review['posture']}]\n";
foreach ($review["findings"] as $f) {
    echo "  [{$f['priority']}] {$f['id']} {$f['resource']}\n";
}
file_put_contents("review.json", json_encode($review, JSON_PRETTY_PRINT));

var req = new HttpRequestMessage(HttpMethod.Post, Api + "/run-stream") {
    Content = JsonContent.Create(payload),
};
req.Headers.Add("Idempotency-Key", "pc-001");

using var res = await Http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());

string? evt = null, done = null;
while (await reader.ReadLineAsync() is { } line)
{
    if (line.StartsWith("event:")) evt = line[6..].Trim();
    else if (line.StartsWith("data:"))
    {
        var data = line[5..].Trim();
        if (evt == "delta") Console.Write(".");            // live progress
        else if (evt == "done") done = data;
        else if (evt == "error") throw new Exception(data);
    }
}

using var final = JsonDocument.Parse(done!);
var text = final.RootElement.GetProperty("output").GetProperty("output").GetString();
using var reviewDoc = JsonDocument.Parse(text!);
var review = reviewDoc.RootElement;
Console.WriteLine($"{review.GetProperty("review_name")} [{review.GetProperty("posture")}]");
foreach (var f in review.GetProperty("findings").EnumerateArray())
    Console.WriteLine($"  [{f.GetProperty("priority")}] {f.GetProperty("id")} {f.GetProperty("resource")}");
await File.WriteAllTextAsync("review.json", text!);

In a browser, the native EventSource only speaks GET, and this endpoint is a POST — read the fetch response body incrementally, as the JavaScript sample above does. On an idempotent replay the server may answer with a plain JSON envelope instead of an event stream; check the Content-Type before you start parsing frames.