{
  "openapi": "3.1.0",
  "info": {
    "title": "AWatch-rus DetMir Portal API",
    "version": "2026-06-06.pilot-v1",
    "description": "Stable additive API contract for the Rust server-rendered HTML portal and HTMX-compatible role slices. Dioxus, React, Tauri and Electron are not part of this Pilot v1 contract. Clients must ignore unknown fields and tolerate missing optional fields."
  },
  "servers": [
    {
      "url": "/api",
      "description": "Gateway-relative API base"
    }
  ],
  "tags": [
    {
      "name": "contracts"
    },
    {
      "name": "portal"
    },
    {
      "name": "reports"
    },
    {
      "name": "roles"
    },
    {
      "name": "workforce"
    },
    {
      "name": "security"
    },
    {
      "name": "forensics"
    },
    {
      "name": "ueba"
    },
    {
      "name": "risk"
    },
    {
      "name": "pfsense"
    },
    {
      "name": "incidents"
    },
    {
      "name": "cases"
    },
    {
      "name": "readiness"
    },
    {
      "name": "telemetry"
    }
  ],
  "paths": {
    "/contracts": {
      "get": {
        "tags": [
          "contracts"
        ],
        "summary": "Contract index",
        "responses": {
          "200": {
            "description": "Contract index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContractIndex"
                }
              }
            }
          }
        }
      }
    },
    "/contracts/openapi.json": {
      "get": {
        "tags": [
          "contracts"
        ],
        "summary": "OpenAPI document",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/contracts/typescript.d.ts": {
      "get": {
        "tags": [
          "contracts"
        ],
        "summary": "TypeScript declarations",
        "responses": {
          "200": {
            "description": "TypeScript declaration file",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "portal"
        ],
        "summary": "Light service health",
        "responses": {
          "200": {
            "description": "Health payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/operator": {
      "get": {
        "tags": [
          "portal"
        ],
        "summary": "Operator overview payload",
        "responses": {
          "200": {
            "description": "Operator payload used by the HTML portal",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/manager": {
      "get": {
        "tags": [
          "portal"
        ],
        "summary": "Manager payload",
        "responses": {
          "200": {
            "description": "Manager payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/owner": {
      "get": {
        "tags": [
          "portal"
        ],
        "summary": "Owner/security payload",
        "responses": {
          "200": {
            "description": "Owner payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "reports"
        ],
        "summary": "Management report payload",
        "parameters": [
          {
            "name": "anonymize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Return anonymized values when supported"
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/PortalRole"
            },
            "description": "Role slice. The X-AWatch-Role header is also accepted and is preferred by the portal UI."
          }
        ],
        "responses": {
          "200": {
            "description": "Report payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportPayload"
                }
              }
            }
          }
        }
      }
    },
    "/executive": {
      "get": {
        "tags": [
          "roles"
        ],
        "summary": "Executive role slice",
        "responses": {
          "200": {
            "description": "Executive dashboard and Workforce summary without security detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportPayload"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access executive scope"
          }
        }
      }
    },
    "/workforce": {
      "get": {
        "tags": [
          "workforce"
        ],
        "summary": "Workforce role slice",
        "responses": {
          "200": {
            "description": "Workforce analytics, department comparison, owners, trends and markdown report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportPayload"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access workforce scope"
          }
        }
      }
    },
    "/security": {
      "get": {
        "tags": [
          "security"
        ],
        "summary": "Security role slice",
        "responses": {
          "200": {
            "description": "Security risks, events, candidates and UEBA score without Workforce dashboard",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportPayload"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access security scope"
          }
        }
      }
    },
    "/forensics": {
      "get": {
        "tags": [
          "forensics"
        ],
        "summary": "Forensics role slice",
        "responses": {
          "200": {
            "description": "Investigations, timeline contract and export links",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportPayload"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access forensics scope"
          }
        }
      }
    },
    "/ueba": {
      "get": {
        "tags": [
          "ueba"
        ],
        "summary": "UEBA score v1 rule-based contract",
        "responses": {
          "200": {
            "description": "Transparent rule-based UEBA score",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UebaPayload"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access UEBA scope"
          }
        }
      }
    },
    "/pfsense": {
      "get": {
        "tags": [
          "pfsense"
        ],
        "summary": "pfSense integration readiness contract",
        "responses": {
          "200": {
            "description": "Contract-only pfSense readiness payload with demo fixtures",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PfsenseReadiness"
                }
              }
            }
          },
          "403": {
            "description": "Role is not allowed to access pfSense scope"
          }
        }
      }
    },
    "/workforce/policy/explain": {
      "get": {
        "tags": [
          "reports"
        ],
        "summary": "Workforce scoring policy explanation",
        "parameters": [
          {
            "name": "anonymize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy explanation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/incidents": {
      "get": {
        "tags": [
          "incidents"
        ],
        "summary": "Incident list and current state",
        "responses": {
          "200": {
            "description": "Incident payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/incident-review": {
      "post": {
        "tags": [
          "incidents"
        ],
        "summary": "Set manual review status for an incident candidate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IncidentReviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated review state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/investigation-pack/{candidate_id}": {
      "get": {
        "tags": [
          "incidents"
        ],
        "summary": "Export investigation pack for a candidate",
        "parameters": [
          {
            "name": "candidate_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Investigation pack",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/cases": {
      "get": {
        "tags": [
          "cases"
        ],
        "summary": "Case list",
        "responses": {
          "200": {
            "description": "Case list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaseListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "cases"
        ],
        "summary": "Create a manual case from a confirmed candidate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCaseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created case",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/cases/{case_id}": {
      "get": {
        "tags": [
          "cases"
        ],
        "summary": "Case details",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Case details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/cases/{case_id}/status": {
      "post": {
        "tags": [
          "cases"
        ],
        "summary": "Set manual case status",
        "parameters": [
          {
            "name": "case_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaseStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated case",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/dlp/evidence": {
      "get": {
        "tags": [
          "incidents"
        ],
        "summary": "DLP evidence list",
        "responses": {
          "200": {
            "description": "Evidence list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/readiness/latest": {
      "get": {
        "tags": [
          "readiness"
        ],
        "summary": "Latest readiness bundle status",
        "responses": {
          "200": {
            "description": "Readiness status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/readiness/bundle": {
      "get": {
        "tags": [
          "readiness"
        ],
        "summary": "Readiness bundle artifact list",
        "responses": {
          "200": {
            "description": "Readiness bundle",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/readiness/verify": {
      "get": {
        "tags": [
          "readiness"
        ],
        "summary": "Verify readiness checksums and signature",
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/links": {
      "get": {
        "tags": [
          "portal"
        ],
        "summary": "Gateway-relative portal links",
        "responses": {
          "200": {
            "description": "Link map",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          }
        }
      }
    },
    "/telemetry": {
      "post": {
        "tags": [
          "telemetry"
        ],
        "summary": "Agent telemetry ingest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid telemetry API key"
          }
        }
      }
    },
    "/workforce/kpi/explain": {
      "get": {
        "tags": [
          "workforce"
        ],
        "summary": "Rule-based Workforce KPI explanation",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "department",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/PortalRole"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Explainable Workforce KPI payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkforceKpiExplain"
                }
              }
            }
          },
          "400": {
            "description": "Query limits rejected"
          },
          "403": {
            "description": "Role denied"
          }
        }
      }
    },
    "/risk/narrative": {
      "get": {
        "tags": [
          "risk"
        ],
        "summary": "Rule-based executive risk narrative",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "department",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "module",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/PortalRole"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Risk narrative payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RiskNarrative"
                }
              }
            }
          },
          "400": {
            "description": "Query limits rejected"
          },
          "403": {
            "description": "Role denied"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PortalRole": {
        "type": "string",
        "enum": [
          "executive",
          "manager",
          "security",
          "forensics",
          "admin"
        ]
      },
      "RoleContext": {
        "type": "object",
        "required": [
          "role",
          "scope",
          "server_enforced"
        ],
        "properties": {
          "role": {
            "$ref": "#/components/schemas/PortalRole"
          },
          "role_label": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "allowed_scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "server_enforced": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "JsonObject": {
        "type": "object",
        "additionalProperties": true
      },
      "ContractIndex": {
        "type": "object",
        "required": [
          "ok",
          "contract_version",
          "api_base",
          "artifacts",
          "stable_endpoints"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "contract_version": {
            "type": "string"
          },
          "generated_by": {
            "type": "string"
          },
          "api_base": {
            "type": "string"
          },
          "compatibility": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "targets": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "artifacts": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "stable_endpoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EndpointDescriptor"
            }
          }
        },
        "additionalProperties": true
      },
      "EndpointDescriptor": {
        "type": "object",
        "required": [
          "method",
          "path"
        ],
        "properties": {
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ReportPayload": {
        "type": "object",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "generated_at_utc": {
            "type": "string"
          },
          "executive_points": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "executive_dashboard": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "risk_narrative": {
            "$ref": "#/components/schemas/RiskNarrative"
          },
          "agent_quality": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "agent_coverage_sla": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "business_risk": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          },
          "risk_incident_candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          },
          "role_context": {
            "$ref": "#/components/schemas/RoleContext"
          },
          "cases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          }
        },
        "additionalProperties": true
      },
      "RiskNarrativeEvidence": {
        "type": "object",
        "required": [
          "source",
          "label",
          "value",
          "severity"
        ],
        "properties": {
          "source": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "critical"
            ]
          }
        },
        "additionalProperties": true
      },
      "RiskNarrative": {
        "type": "object",
        "required": [
          "ok",
          "risk_level",
          "risk_score",
          "title",
          "summary",
          "why",
          "evidence",
          "recommended_actions",
          "limitations",
          "model"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "role_context": {
            "$ref": "#/components/schemas/RoleContext"
          },
          "scope": {
            "type": "string",
            "enum": [
              "aggregate",
              "department"
            ]
          },
          "query": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "risk_level": {
            "type": "string",
            "enum": [
              "low",
              "guarded",
              "medium",
              "high",
              "critical"
            ]
          },
          "risk_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RiskNarrativeEvidence"
            }
          },
          "recommended_actions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "model": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "generated_at_utc": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "UebaPayload": {
        "type": "object",
        "required": [
          "ok",
          "score",
          "severity",
          "score_components",
          "reason_codes",
          "model"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "role_context": {
            "$ref": "#/components/schemas/RoleContext"
          },
          "score": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "severity": {
            "type": "string",
            "enum": [
              "normal",
              "low",
              "medium",
              "high",
              "critical"
            ]
          },
          "score_components": {
            "type": "object",
            "required": [
              "activity_anomaly",
              "time_anomaly",
              "application_anomaly",
              "network_anomaly",
              "history_anomaly"
            ],
            "properties": {
              "activity_anomaly": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "time_anomaly": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "application_anomaly": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "network_anomaly": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "history_anomaly": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            },
            "additionalProperties": false
          },
          "reason_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "explanation": {
            "type": "string"
          },
          "model": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "risk": {
            "$ref": "#/components/schemas/JsonObject"
          }
        },
        "additionalProperties": true
      },
      "PfsenseReadiness": {
        "type": "object",
        "required": [
          "ok",
          "contract_version",
          "status",
          "ingestion_available",
          "firewall_events",
          "vpn_events",
          "traffic_summary",
          "top_destinations"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "role_context": {
            "$ref": "#/components/schemas/RoleContext"
          },
          "contract_version": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "contract_only",
              "available"
            ]
          },
          "siem": {
            "type": "boolean"
          },
          "ingestion_available": {
            "type": "boolean"
          },
          "firewall_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          },
          "vpn_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          },
          "traffic_summary": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "top_destinations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          }
        },
        "additionalProperties": true
      },
      "IncidentReviewRequest": {
        "type": "object",
        "required": [
          "candidate_id",
          "status"
        ],
        "properties": {
          "candidate_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "NEW",
              "IN_REVIEW",
              "CONFIRMED",
              "FALSE_POSITIVE",
              "POSTPONED"
            ]
          },
          "reviewer": {
            "type": "string"
          },
          "comment": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "CreateCaseRequest": {
        "type": "object",
        "required": [
          "candidate_id"
        ],
        "properties": {
          "candidate_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "owner": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "decision": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "CaseStatusRequest": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "OPEN",
              "IN_PROGRESS",
              "RESOLVED",
              "REJECTED",
              "ARCHIVED"
            ]
          },
          "decision": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "CaseListResponse": {
        "type": "object",
        "required": [
          "ok",
          "cases"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "cases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          }
        },
        "additionalProperties": true
      },
      "WorkforceKpiExplainFactor": {
        "type": "object",
        "required": [
          "name",
          "label",
          "impact",
          "explanation"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "impact": {
            "type": "string"
          },
          "explanation": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "WorkforceKpiExplain": {
        "type": "object",
        "required": [
          "ok",
          "kpi_score",
          "confidence",
          "coverage",
          "factors",
          "top_applications",
          "warnings",
          "recommendations"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "role_context": {
            "$ref": "#/components/schemas/RoleContext"
          },
          "scope": {
            "type": "string"
          },
          "kpi_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "kpi_status": {
            "type": "string"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "coverage": {
            "type": "object",
            "properties": {
              "agent_coverage_percent": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "data_freshness": {
                "type": "string"
              },
              "missing_sources": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": true
          },
          "factors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkforceKpiExplainFactor"
            }
          },
          "top_applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JsonObject"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "recommendations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "model": {
            "$ref": "#/components/schemas/JsonObject"
          }
        },
        "additionalProperties": true
      }
    }
  }
}
