{
  "openapi": "3.1.0",
  "info": {
    "title": "mdflow public source facts",
    "version": "1.0.0",
    "description": "Public, unauthenticated, static read-only source-facts interface. Workflows execute only through the local CLI; the website serves read-only documentation and source facts. The snapshot is rebuilt with the website and may be cached by public hosting. No mutations, credentials, project-state queries, or execution requests are part of this interface.",
    "license": {
      "name": "MIT",
      "url": "https://github.com/johnlindquist/mdflow/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://mdflow.dev"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "HTTP usage, errors, public hosting, and local CLI documentation",
    "url": "https://mdflow.dev/docs/"
  },
  "paths": {
    "/facts.json": {
      "get": {
        "operationId": "getSourceFacts",
        "summary": "Read the published CLI source-facts snapshot",
        "description": "GET returns application/json with no authentication, request parameters, or body. Send Accept: application/json. HEAD is supported for HTTP metadata. This read performs no mutations or workflow execution. versionBase identifies CLI source, contract.contractVersion versions the embedded CLI contract, and info.version versions this HTTP description. X-API-Version: 1 identifies the HTTP major version. Additive fields are allowed within v1; clients should tolerate unknown fields. Breaking representation changes require a new URL and a new major specification version, rather than silently changing existing fields. Hosting failures before site handling can use a different error format; check HTTP status and Content-Type.",
        "security": [],
        "responses": {
          "200": {
            "description": "The public static source-facts snapshot, not live local project state or execution results.",
            "headers": {
              "X-API-Version": {
                "description": "Major version of the public source-facts interface.",
                "schema": {
                  "type": "string",
                  "const": "1"
                }
              },
              "Link": {
                "description": "Discovery links with service-desc pointing to /openapi.json and service-doc pointing to /docs/.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceFacts"
                }
              }
            }
          },
          "404": {
            "description": "Requested JSON resource not found by the site.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "405": {
            "description": "The read-only resource was requested with an unsupported method; use GET or HEAD.",
            "headers": {
              "Allow": {
                "description": "Supported HTTP methods for the static resource.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "406": {
            "description": "Accept excludes the JSON representation; send Accept: application/json.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "default": {
            "description": "Other site-handled HTTP errors. Infrastructure failures outside site handling are not guaranteed to use this format.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SourceFacts": {
        "type": "object",
        "properties": {
          "$generated": {
            "type": "string",
            "description": "Source-generation provenance notice."
          },
          "versionBase": {
            "type": "string",
            "description": "CLI source version used to build this snapshot; separate from the HTTP interface version."
          },
          "defaultEngine": {
            "type": "string",
            "description": "Built-in CLI engine default in this source snapshot."
          },
          "engines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Engine names recognized by this CLI source version; not a report of installed engines."
          },
          "enginesLabel": {
            "type": "string",
            "description": "Human-readable engine list."
          },
          "install": {
            "type": "string",
            "description": "Example package invocation; running it may install packages locally."
          },
          "repo": {
            "type": "string",
            "description": "Official source repository URL.",
            "format": "uri"
          },
          "ladder": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EngineResolutionRung"
            },
            "description": "Engine resolution precedence, most explicit first."
          },
          "commands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CliCommand"
            },
            "description": "Local CLI command usage and descriptions."
          },
          "contract": {
            "$ref": "#/components/schemas/OperationContract"
          },
          "agentPrompts": {
            "$ref": "#/components/schemas/AgentPrompts"
          },
          "mdFlags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MdFlag"
            },
            "description": "Local CLI flags and their descriptions."
          }
        },
        "required": [
          "$generated",
          "versionBase",
          "defaultEngine",
          "engines",
          "enginesLabel",
          "install",
          "repo",
          "ladder",
          "commands",
          "contract",
          "agentPrompts",
          "mdFlags"
        ],
        "additionalProperties": true,
        "description": "Static public snapshot of published CLI source facts. Descriptions of local commands and operations are data, not executable HTTP operations or live project state."
      },
      "OperationContract": {
        "type": "object",
        "properties": {
          "contractVersion": {
            "type": "integer",
            "const": 1,
            "description": "Embedded CLI operation-contract version; independent of OpenAPI info.version and versionBase."
          },
          "commands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContractCommand"
            }
          },
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Operation"
            }
          },
          "safetyRules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SafetyRule"
            }
          }
        },
        "required": [
          "contractVersion",
          "commands",
          "operations",
          "safetyRules"
        ],
        "additionalProperties": true,
        "description": "Versioned local CLI command, effect, consent, and safety contract."
      },
      "AgentPrompts": {
        "type": "object",
        "properties": {
          "setup": {
            "type": "string"
          },
          "evals": {
            "type": "string"
          },
          "migrate": {
            "type": "string"
          }
        },
        "required": [
          "setup",
          "evals",
          "migrate"
        ],
        "additionalProperties": true,
        "description": "Published instructional templates; reading them grants no permission to execute."
      },
      "EngineResolutionRung": {
        "type": "object",
        "properties": {
          "rung": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "rung",
          "note"
        ],
        "additionalProperties": true
      },
      "CliCommand": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "usage",
          "description"
        ],
        "additionalProperties": true
      },
      "ContractCommand": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "json": {
            "type": "boolean",
            "description": "Whether the local CLI command exposes a JSON output mode."
          }
        },
        "required": [
          "name",
          "usage",
          "summary",
          "json"
        ],
        "additionalProperties": true
      },
      "Operation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "command": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "effect": {
            "type": "string",
            "enum": [
              "FREE",
              "LOCAL_WRITE",
              "ENGINE"
            ],
            "description": "FREE means no engine invocation, LOCAL_WRITE changes local state, and ENGINE invokes an external engine. FREE alone does not exclude imports, network access, or local code."
          },
          "consent": {
            "type": "string",
            "enum": [
              "none",
              "explicit-local-effect",
              "interactive-only",
              "caller-invoked",
              "interactive-or-yes"
            ],
            "description": "Consent required for the local CLI operation; separate actions need separate consent."
          },
          "sourceMayChange": {
            "type": "boolean"
          },
          "network": {
            "type": "boolean"
          },
          "executesLocalCode": {
            "type": "boolean"
          },
          "localProcess": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "command",
          "summary",
          "effect",
          "consent"
        ],
        "additionalProperties": true,
        "description": "A local CLI operation with its effect and consent boundary. Optional flags indicate possible effects; absence is not a sandbox guarantee."
      },
      "SafetyRule": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "text"
        ],
        "additionalProperties": true
      },
      "MdFlag": {
        "type": "object",
        "properties": {
          "flag": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "flag",
          "description"
        ],
        "additionalProperties": true
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 problem details for site-handled failures. Hosting-layer failures may use another representation.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "Problem type URI; about:blank for standard HTTP status semantics."
          },
          "title": {
            "type": "string",
            "description": "Short summary of the HTTP problem."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP error status; use the actual response status for control flow."
          },
          "detail": {
            "type": "string",
            "description": "Explanation of this failure."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "URI reference identifying the failed request."
          },
          "resolution": {
            "type": "string",
            "description": "Site-provided hint for correcting the request."
          }
        },
        "additionalProperties": true
      }
    }
  }
}