{
  "openapi": "3.0.3",
  "info": {
    "title": "SayWhat Preflight",
    "version": "1.0.0",
    "description": "Hosted intent compiler. Import this OpenAPI document into a tool catalog such as Executor.sh. This is a catalog/tool entry, not a coding-agent adapter. SayWhat compiles; your coding agent still executes. Never send .env files, keys, credentials, or tokens in the instruction or context. Setup: https://saywhat.foo/help/executor"
  },
  "servers": [
    {
      "url": "https://saywhat.foo"
    }
  ],
  "tags": [
    {
      "name": "preflight",
      "description": "Compile a rough instruction before a coding agent starts work."
    }
  ],
  "security": [
    {
      "licenseToken": []
    }
  ],
  "paths": {
    "/api/preflight": {
      "post": {
        "operationId": "preflight",
        "tags": [
          "preflight"
        ],
        "summary": "Compile an instruction into an execution-ready spec",
        "description": "Call this with the user's rough instruction. Show receiptText to the human. Execute from agentInstruction. Do not treat Executor as the coding agent.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreflightRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compiled Preflight result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreflightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid license token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health/license": {
      "get": {
        "operationId": "checkLicense",
        "tags": [
          "preflight"
        ],
        "summary": "Verify the license token can call Preflight",
        "description": "Use after attaching SAYWHAT_LICENSE_TOKEN as a Bearer secret. Does not compile an instruction.",
        "responses": {
          "200": {
            "description": "License status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseHealthResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid license token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "licenseToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "SAYWHAT_LICENSE_TOKEN",
        "description": "License token from SayWhat Account → Setup. Store it in the tool catalog's secret store. Never put it in the sandbox, chat, or source."
      }
    },
    "schemas": {
      "PreflightRequest": {
        "type": "object",
        "required": [
          "instruction"
        ],
        "additionalProperties": false,
        "properties": {
          "instruction": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000,
            "description": "The user's rough coding instruction."
          },
          "input": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000,
            "description": "Alias for instruction. Use instruction when both are available."
          },
          "targetAgent": {
            "type": "string",
            "enum": [
              "generic",
              "codex",
              "claude-code",
              "kimi",
              "cursor",
              "windsurf",
              "antigravity",
              "opencode"
            ],
            "default": "generic",
            "description": "Coding-agent formatting target. Not a tool-catalog id. Default generic."
          },
          "agent": {
            "type": "string",
            "enum": [
              "generic",
              "codex",
              "claude-code",
              "kimi",
              "cursor",
              "windsurf",
              "antigravity",
              "opencode"
            ],
            "description": "Alias for targetAgent."
          },
          "playbook": {
            "type": "string",
            "enum": [
              "auto",
              "build-feature",
              "fix-bug",
              "ui-polish",
              "refactor",
              "investigate",
              "deploy",
              "security-review",
              "performance",
              "tests",
              "documentation"
            ],
            "description": "Playbook id, or auto to infer."
          },
          "receiptMode": {
            "type": "string",
            "enum": [
              "compact",
              "standard",
              "verbose"
            ],
            "default": "compact",
            "description": "User-facing receipt verbosity. Default compact."
          },
          "context": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional safe, size-limited project facts. Never include .env, keys, credentials, or source dumps."
          }
        }
      },
      "PreflightResponse": {
        "type": "object",
        "properties": {
          "originalInstruction": {
            "type": "string"
          },
          "agentInstruction": {
            "type": "string",
            "description": "Compiled assignment for the coding agent. Execute from this."
          },
          "receiptText": {
            "type": "string",
            "description": "Compact user-facing Preflight receipt."
          },
          "targetAgent": {
            "type": "string",
            "enum": [
              "generic",
              "codex",
              "claude-code",
              "kimi",
              "cursor",
              "windsurf",
              "antigravity",
              "opencode"
            ]
          },
          "ambiguities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "LicenseHealthResponse": {
        "type": "object",
        "properties": {
          "authenticated": {
            "type": "boolean"
          },
          "entitled": {
            "type": "boolean"
          },
          "plan": {
            "type": "string",
            "nullable": true
          },
          "preflight": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      }
    }
  }
}