{
  "openapi": "3.1.0",
  "info": {
    "title": "DSH Go API V2",
    "version": "2.0.0",
    "description": "Canonical read-only DSH Registry V4 API. Remote endpoints discover and resolve packages; local runtime mutation is never executed by this service."
  },
  "servers": [{"url":"https://dsh-go.pages.dev"}],
  "paths": {
    "/api/v2": {"get":{"summary":"API V2 capability map","responses":{"200":{"description":"OK"}}}},
    "/api/v2/capabilities": {"get":{"summary":"Protocol and platform capabilities","responses":{"200":{"description":"OK"}}}},
    "/api/v2/health": {"get":{"summary":"Registry V4 health","responses":{"200":{"description":"Healthy"},"503":{"description":"Registry unavailable"}}}},
    "/api/v2/packages": {"get":{"summary":"List or search packages","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"type","schema":{"$ref":"#/components/schemas/PackageType"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Package collection"}}}},
    "/api/v2/packages/{type}/{id}": {"get":{"summary":"Get canonical package","parameters":[{"$ref":"#/components/parameters/Type"},{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Package"},"404":{"description":"Not found"}}}},
    "/api/v2/packages/{type}/{id}/releases": {"get":{"summary":"List package releases","parameters":[{"$ref":"#/components/parameters/Type"},{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Releases"}}}},
    "/api/v2/packages/{type}/{id}/releases/{version}": {"get":{"summary":"Get immutable release","parameters":[{"$ref":"#/components/parameters/Type"},{"$ref":"#/components/parameters/Id"},{"in":"path","name":"version","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Release"},"404":{"description":"Not found"}}}},
    "/api/v2/search": {"get":{"summary":"Registry V4 search","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"type","schema":{"$ref":"#/components/schemas/PackageType"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Search results"}}}},
    "/api/v2/resolve": {"post":{"summary":"Resolve package and dependency graph","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}}},"responses":{"200":{"description":"Resolution plan"},"400":{"description":"Invalid request"},"409":{"description":"Security or dependency conflict"}}}},
    "/api/v2/install-plan": {"post":{"summary":"Build local-only install plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}}},"responses":{"200":{"description":"Install plan"}}}},
    "/api/v2/publishers": {"get":{"summary":"List publishers","responses":{"200":{"description":"Publishers"}}}},
    "/api/v2/publishers/{id}": {"get":{"summary":"Publisher portfolio","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Publisher"},"404":{"description":"Not found"}}}},
    "/api/v2/advisories": {"get":{"summary":"List advisories","parameters":[{"in":"query","name":"severity","schema":{"type":"string"}}],"responses":{"200":{"description":"Advisories"}}}},
    "/api/v2/advisories/{id}": {"get":{"summary":"Get advisory","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Advisory"},"404":{"description":"Not found"}}}},
    "/api/v2/registry/revision": {"get":{"summary":"Registry V4 revision","responses":{"200":{"description":"Revision"}}}},
    "/api/v2/registry/delta": {"get":{"summary":"Negotiate Registry V4 delta","parameters":[{"in":"query","name":"from","schema":{"type":"string"}}],"responses":{"200":{"description":"Delta or full refresh signal"}}}},
    "/api/v2/mcp": {"post":{"summary":"MCP Tools V2 JSON-RPC endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"}}}}
  },
  "components": {
    "parameters": {
      "Type":{"in":"path","name":"type","required":true,"schema":{"$ref":"#/components/schemas/PackageType"}},
      "Id":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}
    },
    "schemas": {
      "PackageType":{"type":"string","enum":["plugin","mcp","skill","agent"]},
      "ReleaseChannel":{"type":"string","enum":["stable","beta","nightly","dev"]},
      "PackageRequest":{"type":"object","required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/PackageType"},"id":{"type":"string"},"range":{"type":"string","default":"*"},"channel":{"$ref":"#/components/schemas/ReleaseChannel"}}},
      "ResolveRequest":{"oneOf":[{"$ref":"#/components/schemas/PackageRequest"},{"type":"object","required":["request"],"properties":{"request":{"$ref":"#/components/schemas/PackageRequest"},"environment":{"type":"object","properties":{"dsh_version":{"type":"string"},"runtime_version":{"type":"string"},"os":{"type":"string"},"arch":{"type":"string"}}}}}]}
    }
  }
}