{
  "openapi": "3.1.0",
  "info": {
    "title": "mfserna.dev document surface",
    "version": "1.0.0",
    "description": "The public, read-only documents behind Miguel F. Serna's personal site. This describes content retrieval, not a product API."
  },
  "servers": [
    {
      "url": "https://www.mfserna.dev",
      "description": "Canonical site"
    }
  ],
  "security": [],
  "paths": {
    "/": {
      "get": {
        "summary": "Read the home page",
        "operationId": "getHomePage",
        "description": "Read the home page as HTML or, when requested with Accept: text/markdown, as markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/about": {
      "get": {
        "summary": "Read the about page",
        "operationId": "getAboutPage",
        "description": "Read Miguel's biography as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/contact": {
      "get": {
        "summary": "Read public contact information",
        "operationId": "getContactPage",
        "description": "Read Miguel's public contact information as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/privacy": {
      "get": {
        "summary": "Read the privacy notes",
        "operationId": "getPrivacyPage",
        "description": "Read the site's privacy notes as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/docs": {
      "get": {
        "summary": "Read the site consumption notes",
        "operationId": "getReadingDocs",
        "description": "Read instructions for consuming the site's public documents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/agentNet": {
      "get": {
        "summary": "Read the agentNet report",
        "operationId": "getAgentNetReport",
        "description": "Read the agentNet experiment page as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/projects/{slug}": {
      "get": {
        "summary": "Read a published project",
        "operationId": "getProjectPage",
        "description": "Read one published project writeup as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectSlug"
          },
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/projects/{slug}.md": {
      "get": {
        "summary": "Read published project markdown",
        "operationId": "getProjectMarkdown",
        "description": "Read the markdown source for one published project writeup.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectSlug"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/MarkdownDocument"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/writing/{slug}": {
      "get": {
        "summary": "Read a published writing entry",
        "operationId": "getWritingPage",
        "description": "Read one published writing entry as HTML or negotiated markdown.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WritingSlug"
          },
          {
            "$ref": "#/components/parameters/AcceptDocument"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/NegotiatedDocument"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          }
        }
      }
    },
    "/writing/{slug}.md": {
      "get": {
        "summary": "Read published writing markdown",
        "operationId": "getWritingMarkdown",
        "description": "Read the markdown source for one published writing entry.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WritingSlug"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/MarkdownDocument"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agentNet.md": {
      "get": {
        "summary": "Read the agentNet markdown",
        "operationId": "getAgentNetMarkdown",
        "description": "Read the complete agentNet report as markdown.",
        "responses": {
          "200": {
            "$ref": "#/components/responses/MarkdownDocument"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Read the recruiting brief",
        "operationId": "getRecruitingBrief",
        "description": "Read the plain-text recruiting brief and links to primary evidence.",
        "responses": {
          "200": {
            "description": "Recruiting brief",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "summary": "Read the XML sitemap",
        "operationId": "getSitemap",
        "description": "Read the canonical list of public HTML and document URLs.",
        "responses": {
          "200": {
            "description": "XML sitemap",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "Read the OpenAPI description",
        "operationId": "getOpenApiDocument",
        "description": "Read this OpenAPI document.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "openapi",
                    "info",
                    "paths"
                  ],
                  "properties": {
                    "openapi": {
                      "type": "string"
                    },
                    "info": {
                      "type": "object"
                    },
                    "paths": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pages": {
      "get": {
        "summary": "List public pages",
        "operationId": "listPublicPages",
        "description": "List public page URLs and their direct markdown siblings.",
        "responses": {
          "200": {
            "description": "Public page index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "pages"
                  ],
                  "properties": {
                    "pages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Page"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Problem"
          },
          "405": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "AcceptDocument": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "description": "Use text/markdown when markdown is preferred. HTML is the default.",
        "schema": {
          "type": "string",
          "examples": [
            "text/html",
            "text/markdown"
          ]
        }
      },
      "ProjectSlug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "A published project slug.",
        "schema": {
          "type": "string",
          "enum": [
            "serna64",
            "random-number-generation",
            "antigravity-watch",
            "blockpixel"
          ]
        }
      },
      "WritingSlug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "A published writing slug.",
        "schema": {
          "type": "string",
          "enum": [
            "an-introductory-guide-to-harness-engineering"
          ]
        }
      }
    },
    "schemas": {
      "Page": {
        "type": "object",
        "required": [
          "path",
          "markdown",
          "kind",
          "url",
          "markdownUrl"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Canonical relative HTML path."
          },
          "markdown": {
            "type": "string",
            "description": "Direct relative markdown path."
          },
          "kind": {
            "type": "string",
            "enum": [
              "page",
              "project",
              "writing",
              "report"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code",
          "detail",
          "hint"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "code": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NegotiatedDocument": {
        "description": "HTML or markdown document. The response includes Vary: Accept.",
        "headers": {
          "Vary": {
            "schema": {
              "type": "string",
              "const": "Accept"
            }
          }
        },
        "content": {
          "text/html": {
            "schema": {
              "type": "string"
            }
          },
          "text/markdown": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "MarkdownDocument": {
        "description": "Markdown source document.",
        "content": {
          "text/markdown": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "Problem": {
        "description": "RFC 9457 problem detail with stable code and recovery hint.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested published document does not exist.",
        "content": {
          "text/html": {
            "schema": {
              "type": "string"
            }
          },
          "text/markdown": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "NotAcceptable": {
        "description": "The request accepts neither HTML nor markdown.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}