{
  "openapi": "3.1.0",
  "info": {
    "title": "Seer",
    "version": "1.0.0",
    "summary": "Publish HTML bundles and pull request reviews an agent builds and a human reads.",
    "description": "Seer holds two things a person is meant to look at: self-contained HTML bundles an agent built, and Overseer reviews of GitHub pull requests. Every write takes a workspace API key, and the key is what decides which workspace the thing lands in — no call names a workspace itself. Full prose instructions live at https://seer.build/skill.md; how to get a key is at https://seer.build/auth.md.",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://seer.build"
    }
  ],
  "externalDocs": {
    "url": "https://seer.build/skill.md",
    "description": "Seer's instructions for agents"
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "responses": {
      "Error": {
        "description": "The call was refused; the body says why.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "errors": {
                  "type": "array",
                  "description": "Field-level validation failures, on the publish and share paths.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "rule": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ReviewNotFound": {
        "description": "No review this caller may read. A slug that does not exist, one in another workspace, and a version out of range are one answer with one set of bytes.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A workspace API key, `seer_sk_…`, sent as `Authorization: Bearer <key>`. A human mints one at /settings/<workspace>, where it is shown exactly once. The key belongs to one workspace and one person."
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "seer_session",
        "description": "A signed-in member's browser session. The read and annotation paths accept it beside an API key, because a person reads a review in a browser."
      }
    }
  },
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "health",
        "summary": "Liveness",
        "security": [],
        "responses": {
          "200": {
            "description": "ok",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/bundles": {
      "get": {
        "operationId": "listBundles",
        "summary": "The bundles in this key's workspace",
        "responses": {
          "200": {
            "description": "Every bundle, with its version history.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "slug",
                      "latestVersion",
                      "kind",
                      "workspace",
                      "url",
                      "versions"
                    ],
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "latestVersion": {
                        "type": "integer"
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "bundle",
                          "plan"
                        ]
                      },
                      "workspace": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "versions": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "version",
                            "createdAt",
                            "bytes",
                            "files"
                          ],
                          "properties": {
                            "version": {
                              "type": "integer"
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "bytes": {
                              "type": "integer"
                            },
                            "files": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/bundles/{slug}": {
      "put": {
        "operationId": "publishBundle",
        "summary": "Publish a bundle, creating its next version",
        "description": "The body is the raw zip, not multipart. It must contain a root index.html. The key resolves the workspace, so the upload lands wherever the key belongs. PUT and POST are identical. `?project=<slug>` attaches the bundle to that project in the same breath; a project the workspace does not hold refuses the whole upload. `?kind=plan` on the FIRST upload makes the slug a plan — a document that should link /plan.css and /theme.js to read in the house style; the kind is immutable and a later upload naming a different one is a 409.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "project",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            },
            "description": "A project in this workspace to attach the bundle to."
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "bundle",
                "plan"
              ]
            },
            "description": "Set at first upload, immutable after. Default bundle."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/zip": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The version that was created, and the two URLs it can be read at.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "version",
                    "kind",
                    "workspace",
                    "url",
                    "versionUrl",
                    "bytes",
                    "files",
                    "hasIndexHtml",
                    "warnings"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "bundle",
                        "plan"
                      ]
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Always the latest version."
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Pinned to this version."
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "files": {
                      "type": "integer"
                    },
                    "hasIndexHtml": {
                      "type": "boolean"
                    },
                    "projects": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Every project holding this bundle, after any `?project=` attach."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Non-fatal problems, e.g. a plan whose index.html links no reading surface."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "post": {
        "operationId": "publishBundleViaPost",
        "summary": "Publish a bundle, creating its next version",
        "description": "The body is the raw zip, not multipart. It must contain a root index.html. The key resolves the workspace, so the upload lands wherever the key belongs. PUT and POST are identical. `?project=<slug>` attaches the bundle to that project in the same breath; a project the workspace does not hold refuses the whole upload. `?kind=plan` on the FIRST upload makes the slug a plan — a document that should link /plan.css and /theme.js to read in the house style; the kind is immutable and a later upload naming a different one is a 409.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "project",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            },
            "description": "A project in this workspace to attach the bundle to."
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "bundle",
                "plan"
              ]
            },
            "description": "Set at first upload, immutable after. Default bundle."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/zip": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The version that was created, and the two URLs it can be read at.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "version",
                    "kind",
                    "workspace",
                    "url",
                    "versionUrl",
                    "bytes",
                    "files",
                    "hasIndexHtml",
                    "warnings"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "bundle",
                        "plan"
                      ]
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Always the latest version."
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Pinned to this version."
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "files": {
                      "type": "integer"
                    },
                    "hasIndexHtml": {
                      "type": "boolean"
                    },
                    "projects": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Every project holding this bundle, after any `?project=` attach."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Non-fatal problems, e.g. a plan whose index.html links no reading surface."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/images": {
      "get": {
        "operationId": "listImages",
        "summary": "The images in this key's workspace",
        "responses": {
          "200": {
            "description": "Every image.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "filename",
                      "workspace",
                      "url",
                      "bytes",
                      "contentType",
                      "createdAt"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "filename": {
                        "type": "string"
                      },
                      "workspace": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "bytes": {
                        "type": "integer"
                      },
                      "contentType": {
                        "type": "string"
                      },
                      "createdAt": {
                        "type": "string",
                        "format": "date-time"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/images/{filename}": {
      "put": {
        "operationId": "publishImage",
        "summary": "Publish a single image",
        "description": "The body is the raw image bytes. Everything but SVG is re-encoded to WebP on the way in. The response carries a markdown snippet, because the reason this route exists is getting a screenshot into a pull request body.",
        "parameters": [
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/avif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/svg+xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored image.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "filename",
                    "workspace",
                    "url",
                    "markdown",
                    "bytes",
                    "originalBytes",
                    "contentType"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "markdown": {
                      "type": "string",
                      "description": "Paste-ready ![alt](url)."
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "originalBytes": {
                      "type": "integer"
                    },
                    "contentType": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "post": {
        "operationId": "publishImageViaPost",
        "summary": "Publish a single image",
        "description": "The body is the raw image bytes. Everything but SVG is re-encoded to WebP on the way in. The response carries a markdown snippet, because the reason this route exists is getting a screenshot into a pull request body.",
        "parameters": [
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/gif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/avif": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/svg+xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored image.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "filename",
                    "workspace",
                    "url",
                    "markdown",
                    "bytes",
                    "originalBytes",
                    "contentType"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "markdown": {
                      "type": "string",
                      "description": "Paste-ready ![alt](url)."
                    },
                    "bytes": {
                      "type": "integer"
                    },
                    "originalBytes": {
                      "type": "integer"
                    },
                    "contentType": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects": {
      "post": {
        "operationId": "createProject",
        "summary": "Create a project",
        "description": "A project groups the work: bundles, reviews, and later tasks and notes, outside any repo. `parent` nests it one level under another project. The model is docs/projects/data-model.md in the source tree.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug",
                  "title"
                ],
                "properties": {
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "description": {
                    "type": "string",
                    "description": "Constrained markdown: emphasis, inline code, links, lists, fenced code."
                  },
                  "parent": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Slug of an existing top-level project to nest under."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The project's whole state, one call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "title",
                    "description",
                    "status",
                    "parent",
                    "workspace",
                    "url",
                    "createdAt",
                    "updatedAt",
                    "children",
                    "tasks",
                    "plans",
                    "bundles",
                    "reviews",
                    "stages",
                    "notes",
                    "noteCount"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string",
                      "description": "Constrained markdown, as authored."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open",
                        "done",
                        "closed"
                      ]
                    },
                    "parent": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The parent project's slug, or null."
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "The human page; it answers markdown to Accept: text/markdown."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "children": {
                      "type": "array",
                      "description": "Shallow summaries, never recursive.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "status",
                          "bundles",
                          "reviews",
                          "stages",
                          "tasks"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "bundles": {
                            "type": "integer"
                          },
                          "reviews": {
                            "type": "integer"
                          },
                          "stages": {
                            "type": "integer"
                          },
                          "tasks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "tasks": {
                      "type": "array",
                      "description": "Open first, then done, then closed; created order within each.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title",
                          "body",
                          "status",
                          "gates",
                          "prs",
                          "drift",
                          "createdAt",
                          "updatedAt",
                          "doneAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored."
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "gates": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "text",
                                "met"
                              ],
                              "properties": {
                                "text": {
                                  "type": "string"
                                },
                                "met": {
                                  "type": "boolean"
                                }
                              }
                            }
                          },
                          "prs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "repo",
                                "number",
                                "title",
                                "state",
                                "url"
                              ],
                              "properties": {
                                "repo": {
                                  "type": "string"
                                },
                                "number": {
                                  "type": "integer"
                                },
                                "title": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Fetched best-effort at write; null when GitHub could not be asked."
                                },
                                "state": {
                                  "type": "string",
                                  "enum": [
                                    "merged",
                                    "closed",
                                    "draft",
                                    "open",
                                    "unchecked"
                                  ],
                                  "description": "Derived from observations, never authored."
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          },
                          "drift": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Derived: named when the facts contradict the authored status."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "doneAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "description": "Bundles of kind plan: the project's documents to read, first.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "bundles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "stages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "updatedAt",
                          "url",
                          "versionUrl",
                          "apiUrl",
                          "apiVersionUrl"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "versionUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiVersionUrl": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "publishedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "publishedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "notes": {
                      "type": "array",
                      "description": "The most recent 20 notes, oldest first so they read chronologically. The full record, with status events interleaved, is GET /api/projects/{slug}/notes.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "task",
                          "body",
                          "author",
                          "createdAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "task": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The task the note hangs off, or null."
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored. Append-only: notes are never edited or deleted."
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The key holder's email at write time."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "noteCount": {
                      "type": "integer",
                      "description": "Every note the project holds."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "get": {
        "operationId": "listProjects",
        "summary": "The projects in this key's workspace",
        "responses": {
          "200": {
            "description": "Every project, most recently touched first, with its counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "slug",
                      "title",
                      "status",
                      "parent",
                      "workspace",
                      "url",
                      "updatedAt",
                      "bundles",
                      "reviews",
                      "stages",
                      "children"
                    ],
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "open",
                          "done",
                          "closed"
                        ]
                      },
                      "parent": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "workspace": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "updatedAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "bundles": {
                        "type": "integer"
                      },
                      "reviews": {
                        "type": "integer"
                      },
                      "stages": {
                        "type": "integer"
                      },
                      "children": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}": {
      "get": {
        "operationId": "readProject",
        "summary": "Everything one project holds, in one call",
        "description": "The re-entry point: description, sub-projects, bundles, reviews. An agent resuming a project reads this one URL. A key reads its own workspace; a session reads across the caller's memberships.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The project's whole state, one call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "title",
                    "description",
                    "status",
                    "parent",
                    "workspace",
                    "url",
                    "createdAt",
                    "updatedAt",
                    "children",
                    "tasks",
                    "plans",
                    "bundles",
                    "reviews",
                    "stages",
                    "notes",
                    "noteCount"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string",
                      "description": "Constrained markdown, as authored."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open",
                        "done",
                        "closed"
                      ]
                    },
                    "parent": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The parent project's slug, or null."
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "The human page; it answers markdown to Accept: text/markdown."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "children": {
                      "type": "array",
                      "description": "Shallow summaries, never recursive.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "status",
                          "bundles",
                          "reviews",
                          "stages",
                          "tasks"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "bundles": {
                            "type": "integer"
                          },
                          "reviews": {
                            "type": "integer"
                          },
                          "stages": {
                            "type": "integer"
                          },
                          "tasks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "tasks": {
                      "type": "array",
                      "description": "Open first, then done, then closed; created order within each.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title",
                          "body",
                          "status",
                          "gates",
                          "prs",
                          "drift",
                          "createdAt",
                          "updatedAt",
                          "doneAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored."
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "gates": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "text",
                                "met"
                              ],
                              "properties": {
                                "text": {
                                  "type": "string"
                                },
                                "met": {
                                  "type": "boolean"
                                }
                              }
                            }
                          },
                          "prs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "repo",
                                "number",
                                "title",
                                "state",
                                "url"
                              ],
                              "properties": {
                                "repo": {
                                  "type": "string"
                                },
                                "number": {
                                  "type": "integer"
                                },
                                "title": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Fetched best-effort at write; null when GitHub could not be asked."
                                },
                                "state": {
                                  "type": "string",
                                  "enum": [
                                    "merged",
                                    "closed",
                                    "draft",
                                    "open",
                                    "unchecked"
                                  ],
                                  "description": "Derived from observations, never authored."
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          },
                          "drift": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Derived: named when the facts contradict the authored status."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "doneAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "description": "Bundles of kind plan: the project's documents to read, first.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "bundles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "stages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "updatedAt",
                          "url",
                          "versionUrl",
                          "apiUrl",
                          "apiVersionUrl"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "versionUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiVersionUrl": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "publishedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "publishedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "notes": {
                      "type": "array",
                      "description": "The most recent 20 notes, oldest first so they read chronologically. The full record, with status events interleaved, is GET /api/projects/{slug}/notes.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "task",
                          "body",
                          "author",
                          "createdAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "task": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The task the note hangs off, or null."
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored. Append-only: notes are never edited or deleted."
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The key holder's email at write time."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "noteCount": {
                      "type": "integer",
                      "description": "Every note the project holds."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      },
      "patch": {
        "operationId": "updateProject",
        "summary": "Update a project's title, description, status, or parent",
        "description": "Send only what changes. Status is one of open, done, closed; transitions are recorded by Seer with their timestamps. `parent: null` detaches.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "description": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "open",
                      "done",
                      "closed"
                    ]
                  },
                  "parent": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The project's whole state, one call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "title",
                    "description",
                    "status",
                    "parent",
                    "workspace",
                    "url",
                    "createdAt",
                    "updatedAt",
                    "children",
                    "tasks",
                    "plans",
                    "bundles",
                    "reviews",
                    "stages",
                    "notes",
                    "noteCount"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string",
                      "description": "Constrained markdown, as authored."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open",
                        "done",
                        "closed"
                      ]
                    },
                    "parent": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The parent project's slug, or null."
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "The human page; it answers markdown to Accept: text/markdown."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "children": {
                      "type": "array",
                      "description": "Shallow summaries, never recursive.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "status",
                          "bundles",
                          "reviews",
                          "stages",
                          "tasks"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "bundles": {
                            "type": "integer"
                          },
                          "reviews": {
                            "type": "integer"
                          },
                          "stages": {
                            "type": "integer"
                          },
                          "tasks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "tasks": {
                      "type": "array",
                      "description": "Open first, then done, then closed; created order within each.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title",
                          "body",
                          "status",
                          "gates",
                          "prs",
                          "drift",
                          "createdAt",
                          "updatedAt",
                          "doneAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored."
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "done",
                              "closed"
                            ]
                          },
                          "gates": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "text",
                                "met"
                              ],
                              "properties": {
                                "text": {
                                  "type": "string"
                                },
                                "met": {
                                  "type": "boolean"
                                }
                              }
                            }
                          },
                          "prs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "repo",
                                "number",
                                "title",
                                "state",
                                "url"
                              ],
                              "properties": {
                                "repo": {
                                  "type": "string"
                                },
                                "number": {
                                  "type": "integer"
                                },
                                "title": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Fetched best-effort at write; null when GitHub could not be asked."
                                },
                                "state": {
                                  "type": "string",
                                  "enum": [
                                    "merged",
                                    "closed",
                                    "draft",
                                    "open",
                                    "unchecked"
                                  ],
                                  "description": "Derived from observations, never authored."
                                },
                                "url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              }
                            }
                          },
                          "drift": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Derived: named when the facts contradict the authored status."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "doneAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "description": "Bundles of kind plan: the project's documents to read, first.",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "bundles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "latestVersion",
                          "updatedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "stages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "updatedAt",
                          "url",
                          "versionUrl",
                          "apiUrl",
                          "apiVersionUrl"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "versionUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "apiVersionUrl": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "latestVersion",
                          "publishedAt",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "latestVersion": {
                            "type": "integer"
                          },
                          "publishedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "notes": {
                      "type": "array",
                      "description": "The most recent 20 notes, oldest first so they read chronologically. The full record, with status events interleaved, is GET /api/projects/{slug}/notes.",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "task",
                          "body",
                          "author",
                          "createdAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "task": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The task the note hangs off, or null."
                          },
                          "body": {
                            "type": "string",
                            "description": "Constrained markdown, as authored. Append-only: notes are never edited or deleted."
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The key holder's email at write time."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "noteCount": {
                      "type": "integer",
                      "description": "Every note the project holds."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}/bundles/{bundle}": {
      "put": {
        "operationId": "attachProjectBundle",
        "summary": "Attach one bundle",
        "description": "Idempotent: `attached` says whether this call changed anything, and repeating it changes nothing and says so. The bundle must live in the key's workspace.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "bundle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The membership, after this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "project",
                    "bundle",
                    "attached"
                  ],
                  "properties": {
                    "project": {
                      "type": "string"
                    },
                    "bundle": {
                      "type": "string"
                    },
                    "attached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "delete": {
        "operationId": "detachProjectBundle",
        "summary": "Detach one bundle",
        "description": "Idempotent: `detached` says whether this call changed anything, and repeating it changes nothing and says so. The bundle must live in the key's workspace.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "bundle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The membership, after this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "project",
                    "bundle",
                    "detached"
                  ],
                  "properties": {
                    "project": {
                      "type": "string"
                    },
                    "bundle": {
                      "type": "string"
                    },
                    "detached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}/reviews/{review}": {
      "put": {
        "operationId": "attachProjectReview",
        "summary": "Attach one review",
        "description": "Idempotent: `attached` says whether this call changed anything, and repeating it changes nothing and says so. The review must live in the key's workspace.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "review",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The membership, after this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "project",
                    "review",
                    "attached"
                  ],
                  "properties": {
                    "project": {
                      "type": "string"
                    },
                    "review": {
                      "type": "string"
                    },
                    "attached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "delete": {
        "operationId": "detachProjectReview",
        "summary": "Detach one review",
        "description": "Idempotent: `detached` says whether this call changed anything, and repeating it changes nothing and says so. The review must live in the key's workspace.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "review",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The membership, after this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "project",
                    "review",
                    "detached"
                  ],
                  "properties": {
                    "project": {
                      "type": "string"
                    },
                    "review": {
                      "type": "string"
                    },
                    "detached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "Create a task in a project",
        "description": "Gates are the conditions the task must pass, authored unmet and flipped as work proves them; a task cannot be done while a gate is unmet. PR pointers are owner/name plus number; Seer derives their state and keeps it fresh.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "body": {
                    "type": "string",
                    "description": "Constrained markdown."
                  },
                  "gates": {
                    "type": "array",
                    "maxItems": 8,
                    "items": {
                      "type": "object",
                      "required": [
                        "text"
                      ],
                      "properties": {
                        "text": {
                          "type": "string",
                          "maxLength": 120
                        },
                        "met": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "prs": {
                    "type": "array",
                    "maxItems": 16,
                    "items": {
                      "type": "object",
                      "required": [
                        "repo",
                        "number"
                      ],
                      "properties": {
                        "repo": {
                          "type": "string",
                          "description": "owner/name"
                        },
                        "number": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task, with its derived PR facts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "title",
                    "body",
                    "status",
                    "gates",
                    "prs",
                    "drift",
                    "createdAt",
                    "updatedAt",
                    "doneAt"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string",
                      "description": "Constrained markdown, as authored."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open",
                        "done",
                        "closed"
                      ]
                    },
                    "gates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "text",
                          "met"
                        ],
                        "properties": {
                          "text": {
                            "type": "string"
                          },
                          "met": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "prs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "repo",
                          "number",
                          "title",
                          "state",
                          "url"
                        ],
                        "properties": {
                          "repo": {
                            "type": "string"
                          },
                          "number": {
                            "type": "integer"
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Fetched best-effort at write; null when GitHub could not be asked."
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "merged",
                              "closed",
                              "draft",
                              "open",
                              "unchecked"
                            ],
                            "description": "Derived from observations, never authored."
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "drift": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Derived: named when the facts contradict the authored status."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "doneAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}/tasks/{id}": {
      "patch": {
        "operationId": "updateTask",
        "summary": "Update a task",
        "description": "Any of title, body, status, gates, prs; gates and prs replace whole. Entering done with an unmet gate is a 422 naming the gate. Status transitions are recorded by Seer; done_at is derived from them.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^tsk_"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "body": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "open",
                      "done",
                      "closed"
                    ]
                  },
                  "gates": {
                    "type": "array",
                    "items": {}
                  },
                  "prs": {
                    "type": "array",
                    "items": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The task as patched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "title",
                    "body",
                    "status",
                    "gates",
                    "prs",
                    "drift",
                    "createdAt",
                    "updatedAt",
                    "doneAt"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string",
                      "description": "Constrained markdown, as authored."
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open",
                        "done",
                        "closed"
                      ]
                    },
                    "gates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "text",
                          "met"
                        ],
                        "properties": {
                          "text": {
                            "type": "string"
                          },
                          "met": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "prs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "repo",
                          "number",
                          "title",
                          "state",
                          "url"
                        ],
                        "properties": {
                          "repo": {
                            "type": "string"
                          },
                          "number": {
                            "type": "integer"
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Fetched best-effort at write; null when GitHub could not be asked."
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "merged",
                              "closed",
                              "draft",
                              "open",
                              "unchecked"
                            ],
                            "description": "Derived from observations, never authored."
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "drift": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Derived: named when the facts contradict the authored status."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "doneAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/projects/{slug}/notes": {
      "post": {
        "operationId": "createNote",
        "summary": "Append a note to a project",
        "description": "Notes are append-only: no edit, no delete, ever — a correction is another note. `task` ties the note to one of the project's tasks; without it the note belongs to the project itself.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Constrained markdown, at most 2000 characters."
                  },
                  "task": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A task id (tsk_…) in this project, or null."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The note as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "task",
                    "body",
                    "author",
                    "createdAt"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "task": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The task the note hangs off, or null."
                    },
                    "body": {
                      "type": "string",
                      "description": "Constrained markdown, as authored. Append-only: notes are never edited or deleted."
                    },
                    "author": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The key holder's email at write time."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      },
      "get": {
        "operationId": "listNotes",
        "summary": "The project's whole record: every note and every status transition",
        "description": "Merged chronologically, oldest first. Notes are authored; events are derived by Seer and cannot be written, which is what makes the record worth reading.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The trail.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "title": "A note",
                        "type": "object",
                        "required": [
                          "kind",
                          "id",
                          "task",
                          "taskTitle",
                          "body",
                          "author",
                          "createdAt"
                        ],
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "note"
                            ]
                          },
                          "id": {
                            "type": "string"
                          },
                          "task": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "taskTitle": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "body": {
                            "type": "string"
                          },
                          "author": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      },
                      {
                        "title": "A status event",
                        "type": "object",
                        "required": [
                          "kind",
                          "task",
                          "taskTitle",
                          "from",
                          "to",
                          "createdAt"
                        ],
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "event"
                            ]
                          },
                          "task": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "taskTitle": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "from": {
                            "type": "string"
                          },
                          "to": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/stage-captures": {
      "post": {
        "operationId": "createStageCapture",
        "summary": "Capture a pushed same-repository branch",
        "description": "The API key's workspace owns the capture. Send a valid stage slug, repository, mutable source branch, and the Idempotency-Key header. baseRef defaults to the repository's default branch. Seer resolves both refs, verifies the merge base, walks both pinned trees, retains source objects within the configured logical-byte cap, and writes a self-contained completed inventory before returning. Compare metadata supplies rename and patch facts but never decides whether the snapshot is complete. Reusing the header for another request is a 409.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Required replay key. It is scoped to the API key's workspace."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug",
                  "repo",
                  "branch",
                  "builder"
                ],
                "properties": {
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                  },
                  "repo": {
                    "type": "string",
                    "description": "owner/name; head repository and arbitrary commits are not accepted."
                  },
                  "branch": {
                    "type": "string",
                    "description": "The mutable source branch in repo. Slash-containing names are allowed."
                  },
                  "baseRef": {
                    "type": "string",
                    "description": "A branch in repo. Defaults to the repository's default branch."
                  },
                  "builder": {
                    "type": "object",
                    "required": [
                      "intent",
                      "context",
                      "agent"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "intent": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 1200,
                        "description": "Constrained markdown."
                      },
                      "context": {
                        "type": "string",
                        "maxLength": 4000,
                        "description": "Constrained markdown."
                      },
                      "agent": {
                        "type": "object",
                        "required": [
                          "name",
                          "model"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "name": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 80,
                            "description": "Plain one-line text; inline code is allowed."
                          },
                          "model": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 80,
                            "description": "Plain one-line text; inline code is allowed."
                          }
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The completed immutable capture inventory.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "workspace",
                    "slug",
                    "state",
                    "repo",
                    "repoId",
                    "branch",
                    "baseRef",
                    "sourceHeadSha",
                    "baseTipSha",
                    "mergeBaseSha",
                    "patch",
                    "complete",
                    "reviewable",
                    "files",
                    "incomplete",
                    "builder",
                    "createdAt"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "completed"
                      ]
                    },
                    "repo": {
                      "type": "string"
                    },
                    "repoId": {
                      "type": "integer"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "baseRef": {
                      "type": "string"
                    },
                    "sourceHeadSha": {
                      "type": "string"
                    },
                    "baseTipSha": {
                      "type": "string"
                    },
                    "mergeBaseSha": {
                      "type": "string"
                    },
                    "patch": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "required": [
                        "sha256",
                        "available"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "sha256": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        }
                      }
                    },
                    "complete": {
                      "type": "boolean"
                    },
                    "reviewable": {
                      "type": "boolean"
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "path",
                          "oldPath",
                          "status",
                          "old",
                          "new",
                          "additions",
                          "deletions",
                          "changes"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "oldPath": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "added",
                              "removed",
                              "modified",
                              "renamed",
                              "mode_changed",
                              "unknown"
                            ]
                          },
                          "old": {
                            "type": "object",
                            "required": [
                              "objectId",
                              "mode",
                              "kind",
                              "availability",
                              "blobSha256",
                              "reason"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "objectId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "availability": {
                                "type": "string",
                                "enum": [
                                  "retained",
                                  "unavailable",
                                  "not_applicable"
                                ]
                              },
                              "blobSha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "new": {
                            "type": "object",
                            "required": [
                              "objectId",
                              "mode",
                              "kind",
                              "availability",
                              "blobSha256",
                              "reason"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "objectId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "availability": {
                                "type": "string",
                                "enum": [
                                  "retained",
                                  "unavailable",
                                  "not_applicable"
                                ]
                              },
                              "blobSha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "additions": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "deletions": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "changes": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "id",
                                "old",
                                "new",
                                "oldFingerprint",
                                "newFingerprint",
                                "contextFingerprint",
                                "source"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "old": {
                                  "type": "object",
                                  "required": [
                                    "start",
                                    "lines"
                                  ],
                                  "additionalProperties": false,
                                  "properties": {
                                    "start": {
                                      "type": "integer"
                                    },
                                    "lines": {
                                      "type": "integer"
                                    }
                                  }
                                },
                                "new": {
                                  "type": "object",
                                  "required": [
                                    "start",
                                    "lines"
                                  ],
                                  "additionalProperties": false,
                                  "properties": {
                                    "start": {
                                      "type": "integer"
                                    },
                                    "lines": {
                                      "type": "integer"
                                    }
                                  }
                                },
                                "oldFingerprint": {
                                  "type": "string"
                                },
                                "newFingerprint": {
                                  "type": "string"
                                },
                                "contextFingerprint": {
                                  "type": "string"
                                },
                                "source": {
                                  "type": "string",
                                  "enum": [
                                    "patch",
                                    "reconstructed"
                                  ]
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "incomplete": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "kind",
                          "path",
                          "side",
                          "reason"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "snapshot_incomplete",
                              "bytes_unavailable",
                              "lines_unavailable",
                              "patch_unavailable",
                              "metadata_incomplete"
                            ]
                          },
                          "path": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "side": {
                            "type": "string",
                            "enum": [
                              "old",
                              "new",
                              "snapshot"
                            ]
                          },
                          "reason": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "builder": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "intent",
                            "context",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "intent": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200,
                              "description": "Constrained markdown."
                            },
                            "context": {
                              "type": "string",
                              "maxLength": 4000,
                              "description": "Constrained markdown."
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Derived builder user; null on legacy reads."
                            },
                            "keyId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Derived builder key; null on legacy reads."
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/stage-captures/{id}": {
      "get": {
        "operationId": "readStageCapture",
        "summary": "Read a completed stage capture inventory",
        "description": "Workspace members and keys read completed captures. Missing, malformed, and cross-workspace ids return the same soft 404. This route never calls GitHub.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored inventory and pinned source facts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "workspace",
                    "slug",
                    "state",
                    "repo",
                    "repoId",
                    "branch",
                    "baseRef",
                    "sourceHeadSha",
                    "baseTipSha",
                    "mergeBaseSha",
                    "patch",
                    "complete",
                    "reviewable",
                    "files",
                    "incomplete",
                    "builder",
                    "createdAt"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "completed"
                      ]
                    },
                    "repo": {
                      "type": "string"
                    },
                    "repoId": {
                      "type": "integer"
                    },
                    "branch": {
                      "type": "string"
                    },
                    "baseRef": {
                      "type": "string"
                    },
                    "sourceHeadSha": {
                      "type": "string"
                    },
                    "baseTipSha": {
                      "type": "string"
                    },
                    "mergeBaseSha": {
                      "type": "string"
                    },
                    "patch": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "required": [
                        "sha256",
                        "available"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "sha256": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        }
                      }
                    },
                    "complete": {
                      "type": "boolean"
                    },
                    "reviewable": {
                      "type": "boolean"
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "path",
                          "oldPath",
                          "status",
                          "old",
                          "new",
                          "additions",
                          "deletions",
                          "changes"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "oldPath": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "added",
                              "removed",
                              "modified",
                              "renamed",
                              "mode_changed",
                              "unknown"
                            ]
                          },
                          "old": {
                            "type": "object",
                            "required": [
                              "objectId",
                              "mode",
                              "kind",
                              "availability",
                              "blobSha256",
                              "reason"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "objectId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "availability": {
                                "type": "string",
                                "enum": [
                                  "retained",
                                  "unavailable",
                                  "not_applicable"
                                ]
                              },
                              "blobSha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "new": {
                            "type": "object",
                            "required": [
                              "objectId",
                              "mode",
                              "kind",
                              "availability",
                              "blobSha256",
                              "reason"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "objectId": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "availability": {
                                "type": "string",
                                "enum": [
                                  "retained",
                                  "unavailable",
                                  "not_applicable"
                                ]
                              },
                              "blobSha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reason": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "additions": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "deletions": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "changes": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "id",
                                "old",
                                "new",
                                "oldFingerprint",
                                "newFingerprint",
                                "contextFingerprint",
                                "source"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "old": {
                                  "type": "object",
                                  "required": [
                                    "start",
                                    "lines"
                                  ],
                                  "additionalProperties": false,
                                  "properties": {
                                    "start": {
                                      "type": "integer"
                                    },
                                    "lines": {
                                      "type": "integer"
                                    }
                                  }
                                },
                                "new": {
                                  "type": "object",
                                  "required": [
                                    "start",
                                    "lines"
                                  ],
                                  "additionalProperties": false,
                                  "properties": {
                                    "start": {
                                      "type": "integer"
                                    },
                                    "lines": {
                                      "type": "integer"
                                    }
                                  }
                                },
                                "oldFingerprint": {
                                  "type": "string"
                                },
                                "newFingerprint": {
                                  "type": "string"
                                },
                                "contextFingerprint": {
                                  "type": "string"
                                },
                                "source": {
                                  "type": "string",
                                  "enum": [
                                    "patch",
                                    "reconstructed"
                                  ]
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "incomplete": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "kind",
                          "path",
                          "side",
                          "reason"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "snapshot_incomplete",
                              "bytes_unavailable",
                              "lines_unavailable",
                              "patch_unavailable",
                              "metadata_incomplete"
                            ]
                          },
                          "path": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "side": {
                            "type": "string",
                            "enum": [
                              "old",
                              "new",
                              "snapshot"
                            ]
                          },
                          "reason": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "builder": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "intent",
                            "context",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "intent": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200,
                              "description": "Constrained markdown."
                            },
                            "context": {
                              "type": "string",
                              "maxLength": 4000,
                              "description": "Constrained markdown."
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Derived builder user; null on legacy reads."
                            },
                            "keyId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Derived builder key; null on legacy reads."
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/stage-captures/{id}/objects/{sha256}": {
      "get": {
        "operationId": "readStageCaptureObject",
        "summary": "Read one retained capture object",
        "description": "Reads a canonical patch or retained old/new blob named by the authorized capture. Workspace members and valid workspace keys may read it. Unknown, unrelated, malformed, and cross-workspace objects share the capture soft 404; a named object missing from durable storage is reported as storage corruption, while a store-open failure is a retryable 502.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
            }
          },
          {
            "name": "sha256",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The retained patch or blob bytes.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/stages": {
      "post": {
        "operationId": "publishStage",
        "summary": "Publish one immutable staged walkthrough",
        "description": "Publishes a validated witness narrative over one completed capture. The capture slug must match, expectedPreviousVersion is 0 in this slice, every canonical change and incomplete material must be accounted for exactly once, and Project attachments resolve before the one transaction writes stage, version, and membership rows. Unknown Project slugs return 422, matching review publication.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "captureId",
                  "expectedPreviousVersion",
                  "slug",
                  "title",
                  "summary",
                  "witness",
                  "groups"
                ],
                "properties": {
                  "captureId": {
                    "type": "string",
                    "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                  },
                  "expectedPreviousVersion": {
                    "type": "integer",
                    "enum": [
                      0
                    ]
                  },
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                  },
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "summary": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1200,
                    "description": "Constrained markdown."
                  },
                  "witness": {
                    "type": "object",
                    "required": [
                      "name",
                      "model"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 80
                      },
                      "model": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 80
                      }
                    }
                  },
                  "groups": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 16,
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "title",
                        "category",
                        "importance",
                        "complexity",
                        "explanation",
                        "examples",
                        "members"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 60,
                          "description": "Plain one-line text; inline code is allowed."
                        },
                        "category": {
                          "type": "string",
                          "enum": [
                            "Contract",
                            "Code",
                            "Tests",
                            "Test fixtures",
                            "Docs",
                            "Generated"
                          ]
                        },
                        "importance": {
                          "type": "string",
                          "enum": [
                            "low",
                            "medium",
                            "high"
                          ]
                        },
                        "complexity": {
                          "type": "string",
                          "enum": [
                            "low",
                            "medium",
                            "high"
                          ]
                        },
                        "explanation": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 1600,
                          "description": "Constrained markdown."
                        },
                        "attention": {
                          "type": "string",
                          "maxLength": 300,
                          "description": "Plain one-line text; inline code is allowed."
                        },
                        "examples": {
                          "type": "array",
                          "maxItems": 5,
                          "items": {
                            "type": "object",
                            "required": [
                              "code",
                              "text"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "code": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 500
                              },
                              "text": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 300
                              }
                            }
                          }
                        },
                        "members": {
                          "type": "array",
                          "maxItems": 10000,
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "required": [
                                  "type",
                                  "id",
                                  "description"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "change"
                                    ]
                                  },
                                  "id": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 80
                                  },
                                  "description": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 400,
                                    "description": "Plain one-line text; inline code is allowed."
                                  }
                                }
                              },
                              {
                                "type": "object",
                                "required": [
                                  "type",
                                  "id",
                                  "description"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "material"
                                    ]
                                  },
                                  "id": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 80
                                  },
                                  "description": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 400,
                                    "description": "Plain one-line text; inline code is allowed."
                                  }
                                }
                              },
                              {
                                "type": "object",
                                "required": [
                                  "type",
                                  "id",
                                  "description"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "file"
                                    ]
                                  },
                                  "id": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 80
                                  },
                                  "description": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 400,
                                    "description": "Plain one-line text; inline code is allowed."
                                  }
                                }
                              }
                            ]
                          },
                          "description": "Across all groups, at most 10,000 members are accepted."
                        }
                      }
                    },
                    "description": "Group ids are unique slugs. Each group must include examples, which may be an empty array. The total member count is capped at 10,000. Rejected requests contain at most 32 field errors."
                  },
                  "projects": {
                    "type": "array",
                    "maxItems": 16,
                    "items": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The immutable stage version and resolved document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "slug",
                    "workspace",
                    "version",
                    "latestVersion",
                    "isLatest",
                    "url",
                    "versionUrl",
                    "apiUrl",
                    "apiVersionUrl",
                    "document"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "slug": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "latestVersion": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "isLatest": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiVersionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "document": {
                      "type": "object",
                      "required": [
                        "identity",
                        "source",
                        "builder",
                        "witness",
                        "projects"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "identity": {
                          "type": "object",
                          "required": [
                            "id",
                            "slug",
                            "version",
                            "title",
                            "createdAt"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "slug": {
                              "type": "string",
                              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 80
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "source": {
                          "type": "object",
                          "required": [
                            "captureId",
                            "repo",
                            "repoId",
                            "branch",
                            "baseRef",
                            "sourceHeadSha",
                            "baseTipSha",
                            "mergeBaseSha"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "captureId": {
                              "type": "string",
                              "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "repo": {
                              "type": "string"
                            },
                            "repoId": {
                              "type": "integer"
                            },
                            "branch": {
                              "type": "string"
                            },
                            "baseRef": {
                              "type": "string"
                            },
                            "sourceHeadSha": {
                              "type": "string"
                            },
                            "baseTipSha": {
                              "type": "string"
                            },
                            "mergeBaseSha": {
                              "type": "string"
                            }
                          }
                        },
                        "builder": {
                          "type": "object",
                          "required": [
                            "intent",
                            "context",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "intent": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200,
                              "description": "Constrained markdown."
                            },
                            "context": {
                              "type": "string",
                              "maxLength": 4000,
                              "description": "Constrained markdown."
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "witness": {
                          "type": "object",
                          "required": [
                            "summary",
                            "groups",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "summary": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200
                            },
                            "groups": {
                              "type": "array",
                              "minItems": 1,
                              "maxItems": 16,
                              "items": {
                                "type": "object",
                                "required": [
                                  "id",
                                  "title",
                                  "category",
                                  "importance",
                                  "complexity",
                                  "explanation",
                                  "examples",
                                  "members"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                                  },
                                  "title": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 60,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "category": {
                                    "type": "string",
                                    "enum": [
                                      "Contract",
                                      "Code",
                                      "Tests",
                                      "Test fixtures",
                                      "Docs",
                                      "Generated"
                                    ]
                                  },
                                  "importance": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "complexity": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "explanation": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 1600,
                                    "description": "Constrained markdown."
                                  },
                                  "attention": {
                                    "type": "string",
                                    "maxLength": 300,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "examples": {
                                    "type": "array",
                                    "maxItems": 5,
                                    "items": {
                                      "type": "object",
                                      "required": [
                                        "code",
                                        "text"
                                      ],
                                      "additionalProperties": false,
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 500
                                        },
                                        "text": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 300
                                        }
                                      }
                                    }
                                  },
                                  "members": {
                                    "type": "array",
                                    "maxItems": 10000,
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "change"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "material"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "file"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        }
                                      ]
                                    },
                                    "description": "Across all groups, at most 10,000 members are accepted."
                                  }
                                }
                              }
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "projects": {
                          "type": "array",
                          "maxItems": 16,
                          "items": {
                            "type": "string",
                            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/stages/{slug}": {
      "get": {
        "operationId": "readLatestStage",
        "summary": "Read the latest stage version",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The resolved latest stage version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "slug",
                    "workspace",
                    "version",
                    "latestVersion",
                    "isLatest",
                    "url",
                    "versionUrl",
                    "apiUrl",
                    "apiVersionUrl",
                    "document"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "slug": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "latestVersion": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "isLatest": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiVersionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "document": {
                      "type": "object",
                      "required": [
                        "identity",
                        "source",
                        "builder",
                        "witness",
                        "projects"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "identity": {
                          "type": "object",
                          "required": [
                            "id",
                            "slug",
                            "version",
                            "title",
                            "createdAt"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "slug": {
                              "type": "string",
                              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 80
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "source": {
                          "type": "object",
                          "required": [
                            "captureId",
                            "repo",
                            "repoId",
                            "branch",
                            "baseRef",
                            "sourceHeadSha",
                            "baseTipSha",
                            "mergeBaseSha"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "captureId": {
                              "type": "string",
                              "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "repo": {
                              "type": "string"
                            },
                            "repoId": {
                              "type": "integer"
                            },
                            "branch": {
                              "type": "string"
                            },
                            "baseRef": {
                              "type": "string"
                            },
                            "sourceHeadSha": {
                              "type": "string"
                            },
                            "baseTipSha": {
                              "type": "string"
                            },
                            "mergeBaseSha": {
                              "type": "string"
                            }
                          }
                        },
                        "builder": {
                          "type": "object",
                          "required": [
                            "intent",
                            "context",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "intent": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200,
                              "description": "Constrained markdown."
                            },
                            "context": {
                              "type": "string",
                              "maxLength": 4000,
                              "description": "Constrained markdown."
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "witness": {
                          "type": "object",
                          "required": [
                            "summary",
                            "groups",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "summary": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200
                            },
                            "groups": {
                              "type": "array",
                              "minItems": 1,
                              "maxItems": 16,
                              "items": {
                                "type": "object",
                                "required": [
                                  "id",
                                  "title",
                                  "category",
                                  "importance",
                                  "complexity",
                                  "explanation",
                                  "examples",
                                  "members"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                                  },
                                  "title": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 60,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "category": {
                                    "type": "string",
                                    "enum": [
                                      "Contract",
                                      "Code",
                                      "Tests",
                                      "Test fixtures",
                                      "Docs",
                                      "Generated"
                                    ]
                                  },
                                  "importance": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "complexity": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "explanation": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 1600,
                                    "description": "Constrained markdown."
                                  },
                                  "attention": {
                                    "type": "string",
                                    "maxLength": 300,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "examples": {
                                    "type": "array",
                                    "maxItems": 5,
                                    "items": {
                                      "type": "object",
                                      "required": [
                                        "code",
                                        "text"
                                      ],
                                      "additionalProperties": false,
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 500
                                        },
                                        "text": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 300
                                        }
                                      }
                                    }
                                  },
                                  "members": {
                                    "type": "array",
                                    "maxItems": 10000,
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "change"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "material"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "file"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        }
                                      ]
                                    },
                                    "description": "Across all groups, at most 10,000 members are accepted."
                                  }
                                }
                              }
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "projects": {
                          "type": "array",
                          "maxItems": 16,
                          "items": {
                            "type": "string",
                            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/stages/{slug}/v/{version}": {
      "get": {
        "operationId": "readStageVersion",
        "summary": "Read one pinned stage version",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,8}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The resolved immutable stage version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "slug",
                    "workspace",
                    "version",
                    "latestVersion",
                    "isLatest",
                    "url",
                    "versionUrl",
                    "apiUrl",
                    "apiVersionUrl",
                    "document"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "slug": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "latestVersion": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "isLatest": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apiVersionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "document": {
                      "type": "object",
                      "required": [
                        "identity",
                        "source",
                        "builder",
                        "witness",
                        "projects"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "identity": {
                          "type": "object",
                          "required": [
                            "id",
                            "slug",
                            "version",
                            "title",
                            "createdAt"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "id": {
                              "type": "string",
                              "pattern": "^sta_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "slug": {
                              "type": "string",
                              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 1
                            },
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 80
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "source": {
                          "type": "object",
                          "required": [
                            "captureId",
                            "repo",
                            "repoId",
                            "branch",
                            "baseRef",
                            "sourceHeadSha",
                            "baseTipSha",
                            "mergeBaseSha"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "captureId": {
                              "type": "string",
                              "pattern": "^stg_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                            },
                            "repo": {
                              "type": "string"
                            },
                            "repoId": {
                              "type": "integer"
                            },
                            "branch": {
                              "type": "string"
                            },
                            "baseRef": {
                              "type": "string"
                            },
                            "sourceHeadSha": {
                              "type": "string"
                            },
                            "baseTipSha": {
                              "type": "string"
                            },
                            "mergeBaseSha": {
                              "type": "string"
                            }
                          }
                        },
                        "builder": {
                          "type": "object",
                          "required": [
                            "intent",
                            "context",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "intent": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200,
                              "description": "Constrained markdown."
                            },
                            "context": {
                              "type": "string",
                              "maxLength": 4000,
                              "description": "Constrained markdown."
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "witness": {
                          "type": "object",
                          "required": [
                            "summary",
                            "groups",
                            "agent",
                            "userId",
                            "keyId"
                          ],
                          "additionalProperties": false,
                          "properties": {
                            "summary": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1200
                            },
                            "groups": {
                              "type": "array",
                              "minItems": 1,
                              "maxItems": 16,
                              "items": {
                                "type": "object",
                                "required": [
                                  "id",
                                  "title",
                                  "category",
                                  "importance",
                                  "complexity",
                                  "explanation",
                                  "examples",
                                  "members"
                                ],
                                "additionalProperties": false,
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                                  },
                                  "title": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 60,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "category": {
                                    "type": "string",
                                    "enum": [
                                      "Contract",
                                      "Code",
                                      "Tests",
                                      "Test fixtures",
                                      "Docs",
                                      "Generated"
                                    ]
                                  },
                                  "importance": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "complexity": {
                                    "type": "string",
                                    "enum": [
                                      "low",
                                      "medium",
                                      "high"
                                    ]
                                  },
                                  "explanation": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 1600,
                                    "description": "Constrained markdown."
                                  },
                                  "attention": {
                                    "type": "string",
                                    "maxLength": 300,
                                    "description": "Plain one-line text; inline code is allowed."
                                  },
                                  "examples": {
                                    "type": "array",
                                    "maxItems": 5,
                                    "items": {
                                      "type": "object",
                                      "required": [
                                        "code",
                                        "text"
                                      ],
                                      "additionalProperties": false,
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 500
                                        },
                                        "text": {
                                          "type": "string",
                                          "minLength": 1,
                                          "maxLength": 300
                                        }
                                      }
                                    }
                                  },
                                  "members": {
                                    "type": "array",
                                    "maxItems": 10000,
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "change"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "material"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        },
                                        {
                                          "type": "object",
                                          "required": [
                                            "type",
                                            "id",
                                            "description"
                                          ],
                                          "additionalProperties": false,
                                          "properties": {
                                            "type": {
                                              "type": "string",
                                              "enum": [
                                                "file"
                                              ]
                                            },
                                            "id": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 80
                                            },
                                            "description": {
                                              "type": "string",
                                              "minLength": 1,
                                              "maxLength": 400,
                                              "description": "Plain one-line text; inline code is allowed."
                                            }
                                          }
                                        }
                                      ]
                                    },
                                    "description": "Across all groups, at most 10,000 members are accepted."
                                  }
                                }
                              }
                            },
                            "agent": {
                              "type": "object",
                              "required": [
                                "name",
                                "model"
                              ],
                              "additionalProperties": false,
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 80,
                                  "description": "Plain one-line text; inline code is allowed."
                                }
                              }
                            },
                            "userId": {
                              "type": "string"
                            },
                            "keyId": {
                              "type": "string"
                            }
                          }
                        },
                        "projects": {
                          "type": "array",
                          "maxItems": 16,
                          "items": {
                            "type": "string",
                            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/stages/{slug}/v/{version}/files/{fileId}": {
      "get": {
        "operationId": "readStageFileLines",
        "summary": "Read retained lines from one staged file",
        "description": "The opaque file id must belong to this immutable version. Paths, repositories, Git object ids, and storage digests are never accepted as authority.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,8}$"
            }
          },
          {
            "name": "fileId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^stf_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
            }
          },
          {
            "name": "side",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "old",
                "new"
              ]
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "At most 400 retained text lines.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "fileId",
                    "path",
                    "side",
                    "start",
                    "end",
                    "totalLines",
                    "lines"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "fileId": {
                      "type": "string",
                      "pattern": "^stf_[0-9abcdefghjkmnpqrstvwxyz]{10}$"
                    },
                    "path": {
                      "type": "string"
                    },
                    "side": {
                      "type": "string",
                      "enum": [
                        "old",
                        "new"
                      ]
                    },
                    "start": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "end": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "totalLines": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "lines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "number",
                          "text"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "number": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/reviews": {
      "post": {
        "operationId": "publishReview",
        "summary": "Publish a review of one or more pull requests",
        "description": "The payload names pull requests and supplies judgment; Overseer derives every fact — files, hunks, line numbers, SHAs — from GitHub itself and refuses a claim that does not stand on them. Send JSON, or multipart/form-data with a `document` part plus one part per attachment. Republishing the same slug keeps the URL and shows what moved. The document format is long and is specified in full at https://seer.build/overseer/skill.md — author against that, not against this summary.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug",
                  "prs"
                ],
                "properties": {
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                  },
                  "prs": {
                    "type": "array",
                    "description": "Pull request pointers, as owner/repo#number or an equivalent object.",
                    "items": {}
                  },
                  "projects": {
                    "type": "array",
                    "description": "Optional project slugs to attach this review to on publish. An unknown slug refuses the publish; attach-only, detaching is the membership DELETE route's explicit act.",
                    "items": {
                      "type": "string",
                      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                    }
                  }
                },
                "additionalProperties": true
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The published version, its URLs, what it spent, and any warnings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "slug",
                    "version",
                    "workspace",
                    "url",
                    "versionUrl",
                    "warnings",
                    "usage",
                    "document"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "versionUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "usage": {
                      "type": "object"
                    },
                    "document": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ]
      }
    },
    "/api/reviews/{slug}": {
      "get": {
        "operationId": "readReview",
        "summary": "Read the current version of a review",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored document, plus the annotations and freshness that move on their own.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "document",
                    "version",
                    "latestVersion"
                  ],
                  "properties": {
                    "document": {
                      "type": "object"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "latestVersion": {
                      "type": "integer"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ReviewNotFound"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/reviews/{slug}/v/{n}": {
      "get": {
        "operationId": "readReviewVersion",
        "summary": "Read a prior version of a review",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          },
          {
            "name": "n",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "That version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "document",
                    "version",
                    "latestVersion"
                  ],
                  "properties": {
                    "document": {
                      "type": "object"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "latestVersion": {
                      "type": "integer"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ReviewNotFound"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/reviews/{slug}/annotations": {
      "post": {
        "operationId": "annotateReview",
        "summary": "File a question on a review, or answer one",
        "description": "Two acts, told apart by whether `answer` is present. Filing is a reader's and takes a signed-in member; answering is the witness's and takes the API key. A body with no `answer` is read as a filing, whatever else is in it.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "title": "File a question",
                    "type": "object",
                    "required": [
                      "target",
                      "body"
                    ],
                    "properties": {
                      "target": {
                        "type": "object",
                        "required": [
                          "type",
                          "id"
                        ],
                        "properties": {
                          "type": {
                            "type": "string",
                            "description": "What kind of thing on the page is being asked about."
                          },
                          "id": {
                            "type": "string",
                            "description": "That thing's id in the published document."
                          }
                        }
                      },
                      "body": {
                        "type": "string",
                        "description": "The question."
                      },
                      "quote": {
                        "type": "string",
                        "description": "Optional: the text on the page it hangs off."
                      }
                    }
                  },
                  {
                    "title": "Answer an open question",
                    "type": "object",
                    "required": [
                      "id",
                      "answer"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The annotation being answered."
                      },
                      "answer": {
                        "type": "object",
                        "required": [
                          "body"
                        ],
                        "properties": {
                          "body": {
                            "type": "string"
                          },
                          "refs": {
                            "type": "array",
                            "description": "Optional code references, resolved exactly as a published document's are.",
                            "items": {}
                          }
                        }
                      }
                    }
                  }
                ]
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "description": "The page's own form. A form files; it never answers.",
                "required": [
                  "target",
                  "body"
                ],
                "properties": {
                  "target": {
                    "type": "string",
                    "description": "`<type>:<id>`, split on the first colon."
                  },
                  "target_type": {
                    "type": "string",
                    "description": "The two halves separately, instead of `target`."
                  },
                  "target_id": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  },
                  "quote": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The annotation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/ReviewNotFound"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/reviews/{slug}/refresh": {
      "post": {
        "operationId": "refreshReview",
        "summary": "Re-read the pull requests behind a review from GitHub",
        "description": "Rate limited to one check a minute per review, and it spends the caller's GitHub budget.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What changed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/ReviewNotFound"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/shares": {
      "get": {
        "operationId": "listShares",
        "summary": "The live share links a workspace has minted",
        "description": "Never carries a token: only their hashes survived the mint.",
        "parameters": [
          {
            "name": "workspace",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^ws_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The shares.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "workspace",
                    "shares"
                  ],
                  "properties": {
                    "workspace": {
                      "type": "string"
                    },
                    "shares": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "kind",
                          "target",
                          "label",
                          "createdBy",
                          "createdAt",
                          "expiresAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "bundle",
                              "review"
                            ]
                          },
                          "target": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "expiresAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      },
      "post": {
        "operationId": "createShare",
        "summary": "Mint one revocable, read-only link to one bundle or review",
        "description": "The token comes back exactly once, in `url`. It is not recoverable after.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind",
                  "target"
                ],
                "properties": {
                  "workspace": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "bundle",
                      "review"
                    ]
                  },
                  "target": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
                  },
                  "label": {
                    "type": "string"
                  },
                  "expiresAt": {
                    "description": "An ISO instant, a day count, or null for never.",
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The share, with its one-time token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "workspace",
                    "kind",
                    "target",
                    "label",
                    "expiresAt",
                    "token",
                    "url"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "workspace": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "bundle",
                        "review"
                      ]
                    },
                    "target": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "token": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    },
    "/api/shares/{id}": {
      "delete": {
        "operationId": "revokeShare",
        "summary": "Revoke a share",
        "description": "The link stops opening, and any page already open on it loses its live channel.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^shr_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "revoked"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "revoked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ]
      }
    }
  }
}