{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.bullpen.fi/reference/schemas/json-error.schema.json",
  "title": "Bullpen CLI JSON error envelope",
  "description": "Shared JSON error envelope documented by docs/public/reference/json-contract.md.",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "error"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "const": false
    },
    "code": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[a-z0-9_]+(?:\\.[a-z0-9_]+)+$"
    },
    "recoverability": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "login_required",
        "backend_repair_required",
        "state_inspection_required",
        "retryable_without_action",
        "retryable_after_state_check",
        "auth_state_required",
        "user_action_required",
        "support_required",
        "not_retryable",
        null
      ]
    },
    "requires_login": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "safe_to_retry": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "next_command": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^bullpen(?:\\s|$)"
    },
    "support_safe_evidence": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "minLength": 1
    },
    "error_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "chain": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    },
    "caused_by": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    },
    "hint": {
      "type": [
        "string",
        "null"
      ]
    },
    "recovery_command": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^bullpen(?:\\s|$)"
    },
    "recovery": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "properties": {
        "schema_version": {
          "type": "integer",
          "const": 1
        },
        "status": {
          "type": "string"
        },
        "error_code": {
          "type": "string"
        },
        "recovery_status": {
          "type": "string",
          "enum": [
            "login_required",
            "user_action_required",
            "provider_transient",
            "external_policy",
            "state_inspection_required",
            "diagnostic_required",
            "diagnostic_incomplete",
            "support_required",
            "retryable",
            "unknown"
          ]
        },
        "resolution_owner": {
          "type": "string"
        },
        "next_action": {
          "type": "string",
          "minLength": 1
        },
        "terminal": {
          "type": "boolean"
        },
        "safe_to_retry": {
          "type": "boolean"
        },
        "support_artifact": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^bullpen(?:\\s|$)"
        },
        "evidence": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "recovery_plan": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "properties": {
        "schema_version": {
          "type": "integer",
          "const": 1
        },
        "status": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        },
        "next_action": {
          "type": "string"
        },
        "terminal": {
          "type": "boolean"
        },
        "safe_to_retry": {
          "type": "boolean"
        },
        "resolution_owner": {
          "type": "string"
        },
        "support_artifact": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^bullpen(?:\\s|$)"
        },
        "evidence": {
          "type": "object",
          "additionalProperties": true
        }
      }
    }
  }
}