{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Fieldnotes read-only resources",
    "version": "1.0.0",
    "description": "Public reference retrieval without authentication, API keys, or input bodies. GET reads are idempotent; HEAD returns headers without a body. All search and filtering happen locally over downloaded static resources, never through server query parameters. No writes, hosted inference, remote execution, or MCP transport. Keep advertised URL query parameters and compare corpus revisions; a v query parameter does not select historical content. See /developers/ for Agent Fieldnotes API documentation and /versioning/ for compatibility and the Deprecation and sunset policy. No deprecation or retirement is currently scheduled; breaking read-contract changes require a new version path and explicit migration guidance."
  },
  "externalDocs": {
    "description": "Agent Fieldnotes compatibility, deprecation and sunset policy",
    "url": "https://robust-reef-dmr6.here.now/versioning/"
  },
  "servers": [
    {
      "url": "https://robust-reef-dmr6.here.now"
    }
  ],
  "security": [],
  "paths": {
    "/agent.json": {
      "get": {
        "operationId": "discoverAgent",
        "summary": "Capability manifest",
        "description": "Discover the current contract, corpus revision, public entrypoints, read operations, effects, and limits. No credentials are needed.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Complete capability manifest. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/index.json": {
      "get": {
        "operationId": "listDocuments",
        "summary": "Document metadata index",
        "description": "Download every current document ID, category, source reference, heading, and format URL. There is no server pagination or filtering; select exact IDs locally.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Complete document metadata index. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Index"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search.json": {
      "get": {
        "operationId": "downloadSearchIndex",
        "summary": "Full-text search index",
        "description": "Download metadata plus complete searchable text for local filtering. A query string does not run a search; apply terms and categories in your client or the published CLI.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Complete full-text search index. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/SearchIndex"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/coverage.json": {
      "get": {
        "operationId": "readCoverage",
        "summary": "Source coverage inventory",
        "description": "Inspect included and excluded source units, their reasons, and document mappings. Coverage describes the supplied reference material, not an independent transcription of every linked video.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Complete source coverage inventory. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Coverage"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/downloads/knowledge-base.json": {
      "get": {
        "operationId": "exportKnowledgeBase",
        "summary": "Complete structured corpus",
        "description": "Retrieve every document with full Markdown and provenance. The outer revision applies to every nested document. This is a complete download, not a paginated or summarized response.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Complete complete structured corpus. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/KnowledgeBase"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/documents/{id}.json": {
      "get": {
        "operationId": "readDocument",
        "summary": "Full document",
        "description": "Retrieve full Markdown, metadata, headings, and provenance using an exact ID observed in the index. Check both id and revision before using the body; unknown IDs return a typed 404.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Exact document ID from the current index or local search results.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "description": "Exact stable ID observed in the current index. Never derive an ID from a title or URL slug.",
              "examples": [
                "factory-factory-loop"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete full document. JSON schemaVersion is the string '1'; compare revision with discovery before combining resources.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Corpus-Revision": {
                "description": "Revision of the configured public corpus, not an incoming query parameter.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{16}$",
                  "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                  "examples": [
                    "22ce5d34dbcb5a78"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "404": {
            "description": "NOT_FOUND: this public resource or exact document ID is absent. Re-read links.index and choose a current ID; do not guess a replacement.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED: no server writes are available. Use GET to read or HEAD for headers, without a request body.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              },
              "Allow": {
                "description": "Supported HTTP methods.",
                "schema": {
                  "type": "string",
                  "const": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "NOT_ACCEPTABLE: Accept excludes the resource's available representation. Request application/json for these JSON endpoints.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "CONFIGURATION_ERROR: the delivery gateway cannot safely identify its configured public content. Do not treat this as an empty corpus.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "502": {
            "description": "UPSTREAM_UNAVAILABLE or RESPONSE_TOO_LARGE: the public backing resource could not be retrieved safely, or exceeded the gateway's 4 MiB uncompressed response bound. Keep the failure; do not infer missing content.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "504": {
            "description": "UPSTREAM_UNAVAILABLE: retrieval exceeded the shared 20-second request deadline. A bounded retry of the idempotent read is safe.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "An upstream delivery failure may retain its HTTP status, including access, removal, or hosting-limit failures. Read the typed code and status; no application quota or retry schedule is implied.",
            "headers": {
              "X-Request-ID": {
                "description": "Identifier for this HTTP request; also present in problem responses.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "The read gateway does not cache responses.",
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Vary": {
                "description": "Representation varies with Accept and Accept-Encoding.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Heading": {
        "type": "object",
        "required": [
          "id",
          "text",
          "level"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Heading fragment identifier in the canonical HTML reference."
          },
          "text": {
            "type": "string"
          },
          "level": {
            "type": "integer",
            "minimum": 2,
            "maximum": 6
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "label",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Category": {
        "type": "object",
        "required": [
          "id",
          "label",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "DocumentMetadata": {
        "type": "object",
        "required": [
          "id",
          "title",
          "summary",
          "category",
          "categoryId",
          "tags",
          "collection",
          "wordCount",
          "url",
          "markdownUrl",
          "jsonUrl",
          "headings",
          "sources",
          "sourceUnits"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9-]+$",
            "description": "Exact stable ID observed in the current index. Never derive an ID from a title or URL slug.",
            "examples": [
              "factory-factory-loop"
            ]
          },
          "slug": {
            "type": "string",
            "description": "Descriptive slug; use id for retrieval."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "examples": [
              "Principles",
              "Context",
              "Planning",
              "Execution",
              "Verification",
              "Tools",
              "Team practice"
            ]
          },
          "categoryId": {
            "type": "string",
            "examples": [
              "principles",
              "context",
              "planning",
              "execution",
              "verification",
              "tools",
              "team-practice"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "collection": {
            "type": "string",
            "examples": [
              "factory",
              "foundations",
              "codex"
            ]
          },
          "wordCount": {
            "type": "integer",
            "minimum": 1
          },
          "url": {
            "type": "string",
            "format": "uri-reference",
            "description": "Canonical HTML reference URL, relative to the public origin."
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri-reference",
            "description": "Full Markdown URL. Preserve raw=1 and v query parameters exactly as advertised."
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri-reference",
            "description": "Full document JSON URL, relative to the public origin."
          },
          "headings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Heading"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            },
            "minItems": 1
          },
          "sourceUnits": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "description": "Source-unit identifiers mapped by the coverage inventory; not retrieval URLs."
          }
        }
      },
      "FullDocument": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DocumentMetadata"
          },
          {
            "type": "object",
            "required": [
              "markdown"
            ],
            "properties": {
              "markdown": {
                "type": "string",
                "description": "Complete reference Markdown, not a summary or search excerpt. Provenance is in sources and sourceUnits."
              }
            }
          }
        ]
      },
      "Document": {
        "allOf": [
          {
            "$ref": "#/components/schemas/FullDocument"
          },
          {
            "type": "object",
            "required": [
              "schemaVersion",
              "revision"
            ],
            "properties": {
              "schemaVersion": {
                "type": "string",
                "const": "1"
              },
              "revision": {
                "type": "string",
                "pattern": "^[a-f0-9]{16}$",
                "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
                "examples": [
                  "22ce5d34dbcb5a78"
                ]
              }
            }
          }
        ]
      },
      "SearchDocument": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DocumentMetadata"
          },
          {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "description": "Complete searchable plain text. Filter locally; use the full document for Markdown and citations."
              }
            }
          }
        ]
      },
      "Index": {
        "type": "object",
        "required": [
          "schemaVersion",
          "revision",
          "categories",
          "documents"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$",
            "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
            "examples": [
              "22ce5d34dbcb5a78"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentMetadata"
            }
          }
        }
      },
      "SearchIndex": {
        "type": "object",
        "required": [
          "schemaVersion",
          "revision",
          "documents"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$",
            "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
            "examples": [
              "22ce5d34dbcb5a78"
            ]
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchDocument"
            }
          }
        }
      },
      "KnowledgeBase": {
        "type": "object",
        "required": [
          "schemaVersion",
          "revision",
          "documents"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$",
            "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
            "examples": [
              "22ce5d34dbcb5a78"
            ]
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FullDocument"
            }
          }
        }
      },
      "CoverageUnit": {
        "type": "object",
        "required": [
          "collection",
          "unit",
          "status",
          "documentIds",
          "reason"
        ],
        "properties": {
          "collection": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "included",
              "excluded"
            ]
          },
          "documentIds": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "description": "Exact stable ID observed in the current index. Never derive an ID from a title or URL slug.",
              "examples": [
                "factory-factory-loop"
              ]
            }
          },
          "reason": {
            "type": "string",
            "description": "Explanation of inclusion or exclusion; excluded units may have no document IDs."
          }
        }
      },
      "Coverage": {
        "type": "object",
        "required": [
          "schemaVersion",
          "revision",
          "scope",
          "collections",
          "documentCount",
          "units"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$",
            "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
            "examples": [
              "22ce5d34dbcb5a78"
            ]
          },
          "scope": {
            "type": "string"
          },
          "collections": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "documentCount": {
            "type": "integer",
            "minimum": 0
          },
          "units": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoverageUnit"
            }
          }
        }
      },
      "ReadOperation": {
        "type": "object",
        "required": [
          "name",
          "method",
          "path",
          "output"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "method": {
            "type": "string",
            "const": "GET"
          },
          "path": {
            "type": "string",
            "description": "Public resource path or exact-ID path template, not a write or query service."
          },
          "input": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Descriptions of path substitutions, not a request body."
          },
          "output": {
            "type": "string"
          }
        }
      },
      "Agent": {
        "type": "object",
        "required": [
          "schemaVersion",
          "revision",
          "name",
          "version",
          "description",
          "canonicalOrigin",
          "access",
          "entrypoints",
          "operations",
          "browser",
          "consistency",
          "diagnostics"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$",
            "description": "Mutable corpus revision. Compare across every resource before combining results; this is not a historical snapshot selector.",
            "examples": [
              "22ce5d34dbcb5a78"
            ]
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string",
            "description": "Capability contract version, distinct from the corpus revision."
          },
          "description": {
            "type": "string"
          },
          "canonicalOrigin": {
            "type": "string",
            "format": "uri",
            "description": "Published origin to which the HTTP delivery contract applies."
          },
          "access": {
            "type": "object",
            "required": [
              "authentication",
              "permission",
              "effects",
              "limits"
            ],
            "properties": {
              "authentication": {
                "type": "string",
                "const": "none"
              },
              "permission": {
                "type": "string",
                "const": "read"
              },
              "effects": {
                "type": "string"
              },
              "limits": {
                "type": "string"
              }
            }
          },
          "entrypoints": {
            "type": "object",
            "required": [
              "html",
              "agentGuide",
              "index",
              "searchIndex",
              "coverage",
              "markdown",
              "fullMarkdown",
              "schema",
              "openapi",
              "cli"
            ],
            "properties": {
              "html": {
                "type": "string",
                "format": "uri-reference"
              },
              "agentGuide": {
                "type": "string",
                "format": "uri-reference"
              },
              "index": {
                "type": "string",
                "format": "uri-reference"
              },
              "searchIndex": {
                "type": "string",
                "format": "uri-reference"
              },
              "coverage": {
                "type": "string",
                "format": "uri-reference"
              },
              "markdown": {
                "type": "string",
                "format": "uri-reference"
              },
              "fullMarkdown": {
                "type": "string",
                "format": "uri-reference"
              },
              "schema": {
                "type": "string",
                "format": "uri-reference"
              },
              "openapi": {
                "type": "string",
                "format": "uri-reference"
              },
              "cli": {
                "type": "string",
                "format": "uri-reference"
              }
            }
          },
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReadOperation"
            }
          },
          "browser": {
            "type": "object",
            "required": [
              "global",
              "operations",
              "semantics"
            ],
            "properties": {
              "global": {
                "type": "string",
                "const": "window.WorkshopAgent"
              },
              "operations": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "semantics": {
                "type": "string"
              }
            }
          },
          "consistency": {
            "type": "object",
            "required": [
              "policy",
              "writes"
            ],
            "properties": {
              "policy": {
                "type": "string"
              },
              "writes": {
                "type": "string"
              }
            }
          },
          "diagnostics": {
            "type": "object",
            "required": [
              "errors",
              "retention"
            ],
            "properties": {
              "errors": {
                "type": "string"
              },
              "retention": {
                "type": "string"
              }
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "requestId",
          "instance",
          "links"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "const": "about:blank"
          },
          "title": {
            "type": "string",
            "description": "Short human-readable problem title."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "description": "Safe explanation and recovery guidance for this request."
          },
          "code": {
            "type": "string",
            "enum": [
              "METHOD_NOT_ALLOWED",
              "NOT_FOUND",
              "NOT_ACCEPTABLE",
              "UPSTREAM_UNAVAILABLE",
              "RESPONSE_TOO_LARGE",
              "CONFIGURATION_ERROR"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "Diagnostic identifier matching the X-Request-ID response header; not an authentication token."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "Reference identifying the failing public request."
          },
          "links": {
            "type": "object",
            "required": [
              "index",
              "llms",
              "sitemap"
            ],
            "properties": {
              "index": {
                "type": "string",
                "format": "uri-reference"
              },
              "llms": {
                "type": "string",
                "format": "uri-reference"
              },
              "sitemap": {
                "type": "string",
                "format": "uri-reference"
              }
            }
          }
        }
      }
    }
  }
}
