{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aimeat-io/json-schema/aimeat-io-agent-onboarding-record-schema.json",
  "title": "AgentOnboardingRecord",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aimeat-io-agent-onboarding-api-openapi.yml#/components/schemas/AgentOnboardingRecord",
  "type": "object",
  "properties": {
    "agentGaii": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "completed",
        "failed"
      ]
    },
    "startedAt": {
      "type": "string",
      "format": "date-time"
    },
    "completedAt": {
      "type": "string",
      "format": "date-time"
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentOnboardingStep"
      }
    },
    "readinessScore": {
      "type": "integer"
    },
    "readinessLevel": {
      "type": "string",
      "enum": [
        "basic",
        "standard",
        "full",
        "expert"
      ]
    },
    "detectedPlatform": {
      "type": "string"
    },
    "installedRuntime": {
      "type": "string"
    }
  },
  "$defs": {
    "AgentOnboardingStep": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "order": {
          "type": "integer"
        },
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "description": "Raw i18n key (agentOnboarding.stepDescriptions.{id}); see descriptionText for the resolved string."
        },
        "descriptionText": {
          "type": "string",
          "description": "Localised, human-readable resolution of `description`. Present on the GET /onboarding\nand aimeat_onboarding_status payloads (REST resolves via Accept-Language; MCP uses the\nnode default locale). Added so connector/agent consumers without the i18n bundle never\nsee a raw key.\n"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "passed",
            "failed",
            "skipped"
          ]
        },
        "required": {
          "type": "boolean"
        },
        "validatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "validationMethod": {
          "type": "string",
          "enum": [
            "automatic",
            "api_call",
            "owner_confirm"
          ]
        },
        "failureReason": {
          "type": "string"
        },
        "howTo": {
          "allOf": [
            {
              "$ref": "#/$defs/OnboardingStepHowTo"
            }
          ],
          "nullable": true,
          "description": "Machine-readable how-to-complete descriptor (null when the step id has no mapping)."
        }
      }
    },
    "OnboardingStepHowTo": {
      "type": "object",
      "description": "Authoritative machine-readable \"how to complete this step\" descriptor. A connector drives\neach pending step from this (call `tool` with `args`) instead of fabricating a non-existent\n`aimeat_onboarding_<stepId>` tool. The only onboarding-prefixed tools that exist are the five\naimeat_onboarding_* tools; every other step is completed by calling its mapped real tool.\n",
      "properties": {
        "actor": {
          "type": "string",
          "enum": [
            "agent",
            "server"
          ],
          "description": "Who performs the action -- the agent calls a tool, or the server validates passively."
        },
        "automatic": {
          "type": "boolean",
          "description": "true when the server auto-ticks the step by reading real state (no dedicated confirm call)."
        },
        "gatesCompletion": {
          "type": "boolean",
          "description": "Mirrors `required` -- true when this step gates onboarding completion."
        },
        "validationMethod": {
          "type": "string",
          "enum": [
            "automatic",
            "api_call",
            "owner_confirm"
          ]
        },
        "tool": {
          "type": [
            "string",
            "null"
          ],
          "description": "Exact MCP tool to call, or null for passive/server steps."
        },
        "toolAlias": {
          "type": "string",
          "description": "Optional local-connector convenience tool with the same effect (e.g. aimeat_offers_publish)."
        },
        "restEndpoint": {
          "type": [
            "object",
            "null"
          ],
          "description": "Underlying REST route for non-MCP clients; null for passive steps.",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "GET",
                "POST",
                "PUT",
                "PATCH"
              ]
            },
            "path": {
              "type": "string"
            }
          }
        },
        "args": {
          "type": "object",
          "additionalProperties": true,
          "description": "Copyable argument template. `{name}` and `{test_task_id}` are both substituted server-side (the placeholder only survives when no test task exists yet); `{test_task_id}` is also mirrored in hints.test_task_id."
        },
        "passiveNote": {
          "type": "string",
          "description": "For tool === null steps, the condition under which the server auto-passes the step."
        }
      }
    }
  }
}